Skip to main content

Getting Started

Get up and running with the JPay Africa API in just a few minutes.

Prerequisites​

  • JPay Africa merchant account
  • Basic knowledge of REST APIs and JSON
  • HTTP client (curl, Postman, or your language's HTTP library)

Step 1: Create an App​

How to Create an App​

  1. Log in to merchants.jpay.africa
  2. Navigate to Settings → Applications
  3. Click Create New App
  4. Fill in the details:
    • App Name: Descriptive name for your application
    • Products: Select Collections and/or Payouts
    • Allowed IPs (Optional): Whitelist IP addresses for production security
  5. Click Create

You'll receive:

  • App Key: Your application identifier
  • App Secret: Your secret key (keep secure!)
  • App Code: Numeric code for transactions
danger

Security: Never commit app_secret to version control or expose it in client-side code.

Step 2: Authenticate​

Get your access token using app-based authentication:

curl -X POST https://sandbox.api.jpay.africa/api/v1/auth/app/token \
  -H "Content-Type: application/json" \
  -d '{
    "app_key": "your_app_key",
    "app_secret": "your_app_secret"
  }'

Response:

{
  "access": "eyJ0eXAiOiJKV1QiLCJhbGc...",
  "refresh": "eyJ0eXAiOiJKV1QiLCJhbGc...",
  "merchant_id": 123,
  "app_code": 12345,
  "products": ["collections", "payouts"]
}

Use the access token in all API requests:

Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc...

→ Learn more about authentication

Step 3: Make Your First Request​

Accept a Payment (Collection)​

curl -X POST https://sandbox.api.jpay.africa/api/v1/payments/collections/checkouts/initiate \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "payfrom": "+254712345678",
    "amount": "1000.00",
    "ref_no": "ORDER-123",
    "callback_url": "https://yourdomain.com/webhook",
    "category": "ecommerce"
  }'

Response:

{
  "payfrom": "+254712345678",
  "amount": "1000.00",
  "ref_no": "ORDER-123",
  "status": 0,
  "category": "ecommerce",
  "channel_name": "M-Pesa",
  "created_at": "12/04/2024 14:30:45"
}

✅ Success! Customer receives a payment prompt on their phone.

→ Full Collections API documentation

Next Steps​

Now that you have the basics:

  1. Explore Core APIs - Accept and send payments
  2. Handle Webhooks - Get real-time transaction updates
  3. Error Handling - Handle errors gracefully
  4. Best Practices - Build reliable integrations

Testing in Sandbox​

Sandbox Environment​

Use the sandbox for development and testing:

https://sandbox.api.jpay.africa/api/v1

The sandbox behaves like production but uses test data and doesn't process real money.

Test Phone Numbers​

  • Collections: +254712345670
  • Payouts: +254712345671
  • Amounts: Any valid decimal number

Common Issues​

401 Unauthorized​

Causes:

  • Token expired (15-minute lifetime)
  • Invalid credentials
  • App is inactive

Solution: Generate a new token with your app credentials.

403 Forbidden​

Causes:

  • Merchant profile not approved
  • App doesn't have required product enabled
  • IP address not whitelisted (if restrictions configured)

Solution: Check merchant dashboard and ensure profile is approved.

400 Bad Request​

Causes:

  • Invalid request payload
  • Missing required fields
  • Invalid phone number or amount format

Solution: Verify all required fields are present and properly formatted.

→ Complete error reference

Need Help?​