Payments API Overview

The JPay Africa Payments API allows you to process collections and payouts securely and efficiently.

API Endpoints

Collections

Process incoming payments from customers:

• Initiate Collection: POST /payments/collections/checkouts/initiate
• List Collections: GET /payments/collections/checkouts
• Get Collection Details: GET /payments/collections/checkouts/{checkout_id}

Payouts

Send payments to beneficiaries:

• Initiate Payout: POST /payments/payouts/initiate
• List Payouts: GET /payments/payouts
• Get Payout Details: GET /payments/payouts/{payout_id}

Key Concepts

Collection (Checkout)

A collection represents an incoming payment request. Customers are charged and funds are credited to your collection wallet.

Status: pending | processing | completed | failed

Payout

A payout represents an outgoing payment. Funds are debited from your payout wallet and sent to beneficiaries.

Status: pending | processing | completed | failed

Wallet Types

• Collection Wallet: Receives incoming payments
• Payout Wallet: Sends outgoing payments

Requirements

To use the Payments API:

1. ✅ Merchant profile must be APPROVED
2. ✅ App must have the required product enabled
3. ✅ Valid access token with authentication
4. ✅ Correct phone number format (E.164)

Transaction Flow

Collections Flow

1. Initiate Collection
   ↓
2. Customer receives payment prompt
   ↓
3. Payment processed
   ↓
4. Funds credited to collection wallet
   ↓
5. Webhook notification sent

Payouts Flow

1. Initiate Payout
   ↓
2. Funds debited from payout wallet
   ↓
3. Payment processed
   ↓
4. Beneficiary receives funds
   ↓
5. Webhook notification sent

Common Parameters

Phone Numbers

All phone numbers must be in E.164 format:

• Format: +<country_code><phone_number>
• Example: +254712345678
• Kenya Code: +254

Amounts

All amounts are in KES (Kenyan Shilling):

• Format: Decimal number with 2 decimal places
• Example: 1000.00
• Min: 1.00
• Max: 999999.99

Reference Numbers

Reference numbers are unique identifiers for tracking:

• Format: Alphanumeric string (max 50 characters)
• Example: ORDER-2024-001
• Purpose: Link transactions to your internal orders

Error Handling

All API responses follow standard HTTP status codes:

Code	Meaning	Action
200	Success	Proceed normally
400	Bad Request	Check request parameters
401	Unauthorized	Verify authentication
403	Forbidden	Check permissions/status
404	Not Found	Verify resource ID
429	Too Many Requests	Implement backoff
500	Server Error	Retry with backoff

For detailed error information, see Error Handling.

Rate Limits

• Requests per minute: 60
• Burst limit: 100
• Daily limit: No limit (per merchant)

Pagination

List endpoints support pagination:

Parameter	Type	Default	Max
page	integer	1	N/A
page_size	integer	20	100

Example

GET /payments/collections/checkouts?page=2&page_size=50

Filtering

List endpoints support filtering:

Parameter	Type	Description
status	integer	Filter by status
date_from	string	Start date (YYYY-MM-DD)
date_to	string	End date (YYYY-MM-DD)

Example

GET /payments/collections/checkouts?status=1&date_from=2024-01-01&date_to=2024-12-31

Webhooks

Get real-time notifications for transaction events:

• Endpoint: Your callback URL
• Method: POST
• Payload: JSON with transaction details

Webhook Events

• collection.created - Collection initiated
• collection.completed - Collection successful
• collection.failed - Collection failed
• payout.created - Payout initiated
• payout.completed - Payout successful
• payout.failed - Payout failed

Webhooks are sent to your callback URL when transactions are completed. See endpoint documentation for webhook payload examples.

Next Steps

• Initiate Collection - Accept payments
• Initiate Payout - Send payments
• List Transactions - Retrieve history