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. There are two methods, depending on your integration:

1.1 Payment Form / Payment Links

Use Case: Quick integration for merchants embedding JuniPay forms or sharing payment links.

How: Request a token from your Token Link using your Client ID and Secret.

Example (cURL):

Response:

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

1.2 Direct API Access (Collections, Disbursements, Remittance)

Use Case: Aggregators, advanced integrations, payouts.

How: Generate JWT tokens using your private key with the RS256 algorithm.

Examples in polular frameworks and languages:

Node.js

PHP

Python

Usage in requests:

2. Error Handling

JuniPay follows standard HTTP status codes.

Code	Description
200	Request successful (check response payload for transaction status).
201	Resource created (e.g., payment or transfer).
400	Bad request (validation error, missing parameter).
401	Unauthorized (invalid or missing token).
404	Resource not found.
500–504	Server error (contact JuniPay support if persistent).

Error Response Example:

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

3. Collections (Receiving Money)

3.1 Payment Links

Quickest way to start receiving payments.

Generate links in your Dashboard.

Share via social media, website, or directly.

Example:

https://junipayments.com/{your-business-name}

3.2 Payment Form

Embed JuniPay’s hosted form directly into your website.

Requires: clientId, secret, and a generated token.

Integration Steps:

3.3 Collections API

Endpoint: POST /payment

Request Example:

Response Example:

{
  "status": "pending",
  "message": "TRANSACTION PENDING",
  "transID": "COL1000001221896",
  "foreignID": "1754305435932",
  "reqToken": "1754305435932",
  "transactionId": "TX1234567890",

}

4. Disbursements (Sending Money)

4.1 Verify Recipient

Endpoint: POST /resolve

Purpose: Verify account/phone before sending.

Request Example:

4.2 Transfer Funds

Endpoint: POST /transfer

Request Example:

5. Remittance (Cross-Border Transfers)

5.1 Send Remittance

Endpoint: POST /sendremittance

Request Example:

6. Transaction Status

Endpoint:

Collections: /checktranstatus

Remittance: /checkremittancestatus

Request Example:

Response Example:

{
  "status": "success",
  "transactionId": "TX1234567890",
  "transactionStatus": "completed",
  "amount": 150,
  "currency": "GHS"
}

Perfect — thanks for sharing your current docs and the sample callback response.
Here’s the cleanest way to include callbacks in your JuniPay documentation:

7. Webhooks & Callbacks

When a transaction is processed, JuniPay sends a server-to-server callback (webhook) to the callbackUrl you provided in your API request.

Callbacks are sent for all transaction states:

success → Payment or transfer completed.

failed → Payment or transfer could not be processed.

pending → Transaction still processing (e.g., awaiting customer approval).

7.1 Webhook Request

Method: POST
Headers:

Sample Payload (Success):

{
  "status": "success",
  "message": null,
  "trans_id": "COL100001221903",
  "foreignID": "1754305527617",
  "date": "2025-08-04 11:05:28",
  "amount": 1,
  "channel": "mobile_money",
  "provider": "mtn",
  "phoneNumber": "0557079838"
}

Sample Payload (Failed):

{
  "status": "failed",
  "message": "Insufficient funds",
  "trans_id": "COL100001221904",
  "foreignID": "1754305527618",
  "date": "2025-08-04 11:10:15",
  "amount": 1,
  "channel": "mobile_money",
  "provider": "mtn",
  "phoneNumber": "0557079838"
}

Sample Payload (Pending):

{
  "status": "pending",
  "message": "Awaiting customer approval",
  "trans_id": "COL100001221905",
  "foreignID": "1754305527619",
  "date": "2025-08-04 11:15:40",
  "amount": 1,
  "channel": "mobile_money",
  "provider": "mtn",
  "phoneNumber": "0557079838"
}

7.2 Response from Your Server

Your server must respond with HTTP 200 OK to confirm receipt:

If no 200 response is returned, JuniPay will retry the callback multiple times.

8. Bank Codes

Code	Bank Name
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 of Africa
2022	Universal Merchant Bank Limited
2023	Zenith Bank (Ghana) Limited
2024	First Bank of Nigeria
2025	Societe Generale Ghana

9. Security Best Practices

Never expose your secret or private key in client-side code.

Do not commit keys to GitHub or other version control systems.

Rotate keys regularly.

Validate callbacks by checking signatures (if provided).

10. Developer Tools

Postman Collection: (Coming Soon)

Sandbox Environment: https://sandbox.junipayments.com

Webhook Events: transaction.success, transaction.failed, transaction.pending

JuniPay API Documentation

1. Authentication#

1.1 Payment Form / Payment Links#

1.2 Direct API Access (Collections, Disbursements, Remittance)#

2. Error Handling#

3. Collections (Receiving Money)#

3.1 Payment Links#

3.2 Payment Form#

3.3 Collections API#

4. Disbursements (Sending Money)#

4.1 Verify Recipient#

4.2 Transfer Funds#

5. Remittance (Cross-Border Transfers)#

5.1 Send Remittance#

6. Transaction Status#

7. Webhooks & Callbacks#

7.1 Webhook Request#

7.2 Response from Your Server#

8. Bank Codes#

9. Security Best Practices#

10. Developer Tools#

1. Authentication

1.1 Payment Form / Payment Links

1.2 Direct API Access (Collections, Disbursements, Remittance)

2. Error Handling

3. Collections (Receiving Money)

3.1 Payment Links

3.2 Payment Form

3.3 Collections API

4. Disbursements (Sending Money)

4.1 Verify Recipient

4.2 Transfer Funds

5. Remittance (Cross-Border Transfers)

5.1 Send Remittance

6. Transaction Status

7. Webhooks & Callbacks

7.1 Webhook Request

7.2 Response from Your Server

8. Bank Codes

9. Security Best Practices

10. Developer Tools