JuniPay API Documentation

Base URL (Production): https://api.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(Hosted Checkout)

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.

Import the inline.js file into your web page:

cURL

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

Sub-merchants (optional)
Platform merchants who collect on behalf of third parties can attribute collections to those parties.

1. Contact Juni to request Sub-merchants for your account.
2. Once enabled, open Dashboard → Sub-merchants.
3. Add an entity or individual sub-merchant and complete Ghana Card verification (as required).
4. Copy the merchant identification key (smk_…) from that sub-merchant.
5. Pass it on legacy POST /payment as meta.subMerchantIdentificationKey (see below).

Keys are account-scoped: only keys issued under your merchant account are accepted. Unknown or another merchant’s key returns an error. Attribution works for verified and unverified sub-merchants.
View attributed payments under Sub-merchants → Transactions.

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	Yes	Customer email for receipts
`description`	String	Yes	Transaction memo
`foreignID`	String	Yes	Unique merchant transaction reference
`callbackUrl`	String	Yes	Webhook endpoint for POST notifications
`meta`	Object	No	Optional metadata bag
`meta.subMerchantIdentificationKey`	String	No	Sub-merchant merchant identification key from Dashboard (`smk_…`). Attributes this collection to that sub-merchant. Must belong to your merchant account. Omit for unattributed collections.

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

Verify Recipient Note: Only Ghanaian mobile wallets and bank accounts can be verfied.

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

This API serves as the primary gateway to facilitate cross-border money transfers across the world through JuniPay's platform.

Prerequisites

You must be verified by going through compliance and getting approved.

You must request and be approved to use Direct Access APIs.

Your private and public keys must be generated on the Getting Started page on your Dashboard.

A package to generate your token from your private key (e.g., jsonwebtoken).

Verify First: Run the verify (resolve) endpoint to ensure the validity of the phone number or bank account number before dispatching the transfer.

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
`sender_firstName`	String	Yes	First name of the sender
`sender_lastName`	String	Yes	Last name of the sender
`sender_email`	String	Yes	Email address of the sender
`sender_address`	String	Yes	Address of the sender
`sender_dob`	String	Yes	Date of birth of the sender (YYYY-MM-DD)
`sender_country`	String	Yes	Country of the sender (e.g., USA)
`channel`	String	Yes	Payout channel: `mobile_money` or `bank`
`sendAmount`	Double	Yes	Amount received/delivered, in destination currency (Cedis)
`desc`	String	Yes	Reason/description for sending remittance
`rec_fullName`	String	Yes	Full name of the receiver
`rec_city`	String	Yes	City of the receiver
`rec_relationship`	String	Yes	Sender's relationship with the receiver
`foreignID`	String	Yes	Unique reference string used to track and query the transaction
`sendingCurrency`	String	Yes	3-digit ISO currency code for the sending currency (e.g., USD, GBP)
`receivingCurrency`	String	Yes	3-digit ISO currency code for the receiving currency (e.g., GHS, INR)
`sendAmountForeign`	String	Yes	Amount sent, expressed in the sending currency
`exchangeRate`	String	Yes	Exchange rate applied to the transaction
`callbackUrl`	String	Yes	Destination URL for transaction event webhooks (POST)
`rec_phoneNumber`	String	Conditional	Phone number of receiver (required if `channel` is `mobile_money`)
`rec_provider`	String	Conditional	Mobile money operator e.g., `mtn`, `vodafone`, `airteltigo` (required if `channel` is `mobile_money`)
`rec_bankNumber`	String	Conditional	Bank account number of receiver (required if `channel` is `bank`)
`rec_bankCode`	String	Conditional	Destination bank routing/sort code (required if `channel` is `bank`)

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(Hosted Checkout)#

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(Hosted Checkout)

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