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/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

Step 4: Receive Webhook Notifications​

Because mobile money and bank transactions are asynchronous, JPay will send a POST request containing transaction details to your callback_url once the status is updated.

Sample Node.js / Express Webhook Handler​

const express = require('express');
const app = express();

// Use express.raw() to preserve raw body for signature verification
app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-jpay-signature'];
  const timestamp = req.headers['x-jpay-timestamp'];
  
  // Parse body bytes to JSON
  const payload = JSON.parse(req.body.toString('utf8'));
  console.log('Received transaction callback:', payload);

  // Note: For production, always verify the signature first to prevent spoofing!
  // Send a 200 OK response immediately to acknowledge receipt of webhook
  res.status(200).send({ status: 'success' });
});

app.listen(3000, () => console.log('Webhook server running on port 3000'));
info

Important: In production, you must verify the signature of every callback request to prove authenticity and block spoofed payloads. See the Webhook Signature Verification Guide for secure integration steps and multilingual examples (Node.js, Python, PHP, Go).

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?​