Skip to main content

Getting Started

This guide will help you get up and running with the JPay Africa API in just a few minutes.

Prerequisites​

Before you begin, make sure you have:

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

Creating an App​

To use the JPay Africa API, you need to create an app associated with your merchant account.

Steps to Create an App​

  1. Log in to your merchant dashboard at https://sandbox.merchants.jpay.africa
  2. Navigate to Settings → Applications
  3. Click Create New App
  4. Fill in the application details:
    • App Name: A descriptive name for your application
    • Products: Select the products you want to use:
      • Collections (for receiving payments)
      • Payouts (for sending payments)
    • Allowed IPs (Optional): Whitelist specific IP addresses that can make API requests. When configured:
      • Only requests from whitelisted IPs will be accepted
      • Leave empty to allow requests from any IP address
      • Recommended for production environments
  5. Click Create
  6. You'll receive:
    • App Key: Your application identifier
    • App Secret: Your secret key (keep this secure!)
    • App Code: A numeric code for transactions
danger

Important: Keep your App Secret secure. Never commit it to version control or expose it in client-side code.

Authentication​

App Token Authentication​

The recommended approach is to use 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 the Authorization header for all API requests:

Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc...

For detailed information, see App Token Authentication.

Making Your First Request​

Initiating a Collection​

Let's initiate a collection (receive payment) from a customer:

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",
    "account_number": "1001",
    "callback_url": "https://yourdomain.com/webhook",
    "category": "ecommerce"
  }'

Response:

{
  "payfrom": "+254712345678",
  "amount": "1000.00",
  "ref_no": "ORDER-123",
  "account_number": "1001",
  "callback_url": "https://yourdomain.com/webhook",
  "status": "pending",
  "category": "ecommerce",
  "created_at": "12/04/2024 14:30:45"
}
tip

For more details on the Collections API, see Initiate Checkout.

Next Steps​

Now that you understand the basics:

  1. Learn about authentication methods - Understand different authentication approaches
  2. Explore the Payments API - Learn how to process payments
  3. Handle errors gracefully - Understand error responses
  4. Follow best practices - Build reliable integrations

Testing​

Sandbox Environment​

During development, use our sandbox environment:

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

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

Test Data​

Use these test phone numbers in the sandbox environment:

  • Collection test number: +254712345670
  • Payout test number: +254712345671
  • Amount for testing: Any valid decimal number

Common Issues​

401 Unauthorized​

This error typically means:

  • Your token has expired
  • Your credentials are incorrect
  • Your app is not active

Solution: Generate a new token using your app credentials.

403 Forbidden​

This error means:

  • Your merchant profile is not approved
  • The app doesn't have the required product enabled
  • Your account is not active

Solution: Check your merchant dashboard and ensure your profile is approved.

400 Bad Request​

This error means there's an issue with your request payload.

Solution: Check the request body and ensure all required fields are present and valid.

For more error information, see Error Handling.

Need Help?​