JuniPay API Documentation

Base URL (Production): https://api.junipayments.com

Base URL (Sandbox): https://sandbox.junipayments.com

Content-Type: application/json

Authentication: Bearer Token (JWT)

1. Authentication

All API requests require authentication. Select the method that aligns with your integration requirements.

1.1 Payment Form & Payment Links

Use Case: Quick integrations embedding JuniPay forms or sharing hosted payment links.

Mechanism: Request a token from the token endpoint using your Client ID and Secret.

Node.js

PHP

Python

Response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI...",
  "expires_in": 3600
}

1.2 Direct API Access

Use Case: Direct server-to-server operations, payment aggregators, payouts, and remittances.

Mechanism: Sign JWT tokens locally on your server using your private key and the RS256 algorithm.

Node.js

PHP

Python

HTTP Header Requirements:

2. Error Handling

JuniPay utilizes standard HTTP response status codes.

Code	Description
200 OK	Request successful. Verify the response payload for specific transaction state.
201 Created	Resource created successfully.
400 Bad Request	Missing parameters or payload validation failed.
401 Unauthorized	Missing, expired, or invalid authentication credentials.
404 Not Found	The requested resource does not exist.
500–504 Server Error	Internal API error. Contact support if issues persist.

Error Response Payload:

{
  "status": "error",
  "code": "INVALID_TOKEN",
  "message": "The token provided is expired or invalid."
}

3. Collections (Receiving Payments)

3.1 Payment Links

Generate shareable payment links directly from the JuniPay Dashboard.

URL Format:

3.2 Payment Form (Inline JS)

Embed the hosted payment modal directly into your front-end application.

Integration Example:

Form Configuration Parameters:

Parameter	Type	Required	Description
`key`	String	Yes	Token generated using your secret key
`clientid`	String	Yes	Client ID from Dashboard
`email`	String	Yes	Customer email address
`amount`	Double	Yes	Amount to debit customer
`total_amt`	Double	Yes	Total order amount
`desc`	String	Yes	Item/service description
`color`	String	No	Modal background theme color
`customer_token`	String	No	Existing customer reference token
`foreignID`	String	No	Unique merchant reference string
`callbackUrl`	String	Yes	Asynchronous POST notification URL
`redirectUrl`	String	Yes	Front-end browser redirection URL
`onClose`	Function	No	JavaScript callback trigger when modal is dismissed

3.3 Collections API

Endpoint: POST /payment

cURL

Node.js

PHP

Python

Header Parameters:

Parameter	Type	Description
`Authorization`	String	`Bearer <YOUR_TOKEN>`
`clientid`	String	Client ID from Dashboard
`Content-Type`	String	`application/json`

Body Parameters:

Parameter	Type	Required	Description
`channel`	String	Yes	Payment channel: `mobile_money` or `card`
`phoneNumber`	String	Conditional	Required for `mobile_money` channel
`provider`	String	Conditional	Network provider: `mtn`, `vodafone`, or `airteltigo`
`amount`	Double	Yes	Base amount in Cedis (GHS)
`tot_amnt`	Double	Yes	Total processed amount in Cedis (GHS)
`senderEmail`	String	No	Customer email for receipts
`description`	String	Yes	Transaction memo
`foreignID`	String	Yes	Unique merchant transaction reference
`callbackUrl`	String	Yes	Webhook endpoint for POST notifications

Response Example:


{
  "status": "pending",//failed||success
  "message": "TRANSACTION PENDING",//TRANSACTION FAILED||TRANSACTION SUCCESS
  "transID": "COL100002407990",
  "transID2": "87810835291",
  "foreignID": "91284735832382467",
  "reqToken": "COL100002407990"
}

Currency Note: All transaction amounts (amount, tot_amnt) are processed natively in Ghanaian Cedis (GHS).

4. Disbursements (Sending Money)

Prerequisites

Compliance Verification: Your account must complete KYC/KYB approval.

Direct API Access: Standard API access requested and enabled in Dashboard.

Key Pair Setup: Public and Private RSA keys configured under Dashboard Settings.

4.1 Verify Recipient

Validate customer account details prior to executing funds transfers.

Endpoint: GET /resolve

Node.js

PHP

Python

Header Parameters:

Parameter	Type	Description
`Authorization`	String	`Bearer <YOUR_TOKEN>`
`clientid`	String	Client ID from Dashboard

URL Query Parameters:

Parameter	Type	Required	Description
`channel`	String	Yes	Target channel: `mobile_money` or `bank`
`phoneNumber`	String	Conditional	Required for `mobile_money`
`provider`	String	Conditional	`mtn`, `vodafone`, or `airteltigo`
`account_number`	String	Conditional	Required for `bank` transfer
`bank_code`	String	Conditional	Valid 4-digit bank routing code

Response Example:


{
  "status": "success",
  "name": "GINA ABAN",
  "provider": "mtn"
}

4.2 Transfer Funds

Endpoint: POST /transfer

cURL

Node.js

PHP

Python

Body Parameters:

Parameter	Type	Required	Description
`channel`	String	Yes	Destination target: `mobile_money` or `bank`
`phoneNumber`	String	Conditional	Target phone number (for `mobile_money`)
`provider`	String	Conditional	Mobile network operator (for `mobile_money`)
`account_number`	String	Conditional	Destination account number (for `bank`)
`bank_code`	String	Conditional	4-digit bank identification code (for `bank`)
`amount`	Double	Yes	Amount in Cedis (GHS)
`sender`	String	Yes	Full legal name of sender
`receiver`	String	Yes	Full legal name of recipient
`receiver_phone`	String	No	Recipient contact phone number
`narration`	String	No	Transfer payment context
`foreignID`	String	Yes	Unique merchant transaction reference
`callbackUrl`	String	Yes	Webhook target for POST updates

5. Remittance (Cross-Border Transfers)

Endpoint: POST /sendremittance

cURL

Node.js

PHP

Python

6. Account Balance & Transaction Queries

6.1 Check Balance

Endpoint: POST /accountbalance

cURL

Node.js

PHP

Python

Response Example:

{
  "code": 200,
  "message": "success",
  "available_balance": 1500.00,
  "balance": 2000.00
}

6.2 Transaction Status Query

Endpoints:

Collections: POST /checktranstatus

Remittance: POST /checkremittancestatus

cURL

Node.js

PHP

Python

Response Example:

{
  "code": 200,
  "status": "SUCCESS",
  "info": {
    "status": "SUCCESS",
    "foreignID": "COL100002420223",
    "transID": "66a1697d-12be-4516-8a9e-20062b7dbbe0",
    "transID2": "87994952675",
    "partnerTransID": "78238387782872",
    "recipient": "0557079838",
    "provider": "mtn",
    "gateway": "mtn",
    "description": "TEST TRANSACTION"
  }
}

7. Webhooks & Callbacks

JuniPay dispatches real-time HTTP POST event payloads to the designated callbackUrl when processing state changes occur.

Webhook Event Payloads

{
  "status": "success",
  "message": null,
  "trans_id": "COL100002377810",
  "foreignID": "1786697474738",
  "date": "2026-08-14 08:51:15",
  "amount": 150.00,
  "channel": "mobile_money",
  "provider": "mtn",
  "phoneNumber": "0557079838"
}

{
  "status": "failed",
  "message": "Insufficient funds or user cancelled",
  "trans_id": "COL100002377810",
  "foreignID": "1786697474738",
  "date": "2026-08-14 08:51:15",
  "amount": 150.00,
  "channel": "mobile_money",
  "provider": "mtn",
  "phoneNumber": "0557079838"
}

{
  "status": "pending",
  "message": "Awaiting customer approval",
  "trans_id": "COL100002377810",
  "foreignID": "1786697474738",
  "date": "2026-08-14 08:51:15",
  "amount": 150.00,
  "channel": "mobile_money",
  "provider": "mtn",
  "phoneNumber": "0557079838"
}

Delivery Guarantees & Receiver Response

Acknowledgement: Your server must respond with an HTTP 200 OK status code.

Retry Policy: Notifications operate under an at-least-once delivery guarantee. If your endpoint returns non-2xx statuses or times out, JuniPay automatically queues retries.

8. Settlement & Reporting

Historical activity logging, statement generation, and settlement reconciliations can be exported via the JuniPay Merchant Dashboard.

9. Appendix: Bank Codes

Code	Financial Institution
`2001`	Access Bank
`2002`	Absa Bank
`2003`	Agricultural Development Bank
`2004`	ARB Apex Bank Limited
`2005`	Bank of Africa
`2006`	Bank of Ghana
`2007`	CalBank PLC
`2008`	Consolidated Bank Ghana Limited
`2009`	Ecobank Ghana Limited
`2010`	Fidelity Bank Ghana Limited
`2011`	First Atlantic Bank Limited
`2012`	First National Bank (Ghana) Limited
`2013`	GCB Bank Limited
`2014`	Guaranty Trust Bank (Ghana) Limited
`2015`	National Investment Bank Limited
`2016`	Prudential Bank Limited
`2017`	Republic Bank (Ghana) PLC
`2018`	Stanbic Bank Ghana Limited
`2019`	Standard Chartered Bank (Ghana) Limited
`2020`	OmniBSIC Bank
`2021`	United Bank for Africa
`2022`	Universal Merchant Bank Limited
`2023`	Zenith Bank (Ghana) Limited
`2024`	First Bank of Nigeria
`2025`	Societe Generale Ghana

10. Security & Operational Guidelines

Secret Key Protection: Keep API secrets and private keys within secure environment storage. Never expose credentials in client-side codebases or public repositories.

Callback Validation: Validate processing callbacks by comparing incoming payload fields against transaction state records before fulfilling orders.

Testing: Utilize the sandbox host https://sandbox.junipayments.com when integrating and executing initial end-to-end tests.

JuniPay API Documentation

1. Authentication#

1.1 Payment Form & Payment Links#

1.2 Direct API Access#

2. Error Handling#

3. Collections (Receiving Payments)#

3.1 Payment Links#

3.2 Payment Form (Inline JS)#

3.3 Collections API#

4. Disbursements (Sending Money)#

Prerequisites#

4.1 Verify Recipient#

4.2 Transfer Funds#

5. Remittance (Cross-Border Transfers)#

6. Account Balance & Transaction Queries#

6.1 Check Balance#

6.2 Transaction Status Query#

7. Webhooks & Callbacks#

Webhook Event Payloads#

Delivery Guarantees & Receiver Response#

8. Settlement & Reporting#

9. Appendix: Bank Codes#

10. Security & Operational Guidelines#

1. Authentication

1.1 Payment Form & Payment Links

1.2 Direct API Access

2. Error Handling

3. Collections (Receiving Payments)

3.1 Payment Links

3.2 Payment Form (Inline JS)

3.3 Collections API

4. Disbursements (Sending Money)

Prerequisites

4.1 Verify Recipient

4.2 Transfer Funds

5. Remittance (Cross-Border Transfers)

6. Account Balance & Transaction Queries

6.1 Check Balance

6.2 Transaction Status Query

7. Webhooks & Callbacks

Webhook Event Payloads

Delivery Guarantees & Receiver Response

8. Settlement & Reporting

9. Appendix: Bank Codes

10. Security & Operational Guidelines