Pesapal

Pesapal uses OAuth 2.0 Bearer Token authentication. Your Consumer Key and Consumer Secret (provided by Pesapal) are exchanged for a short-lived access token valid for 5 minutes.

Obtaining Credentials

Register a merchant account at Pesapal Dashboard. Your Consumer Key and Consumer Secret are generated automatically and displayed in your dashboard. Store these securely in environment variables:

PESAPAL_CONSUMER_KEY=your_consumer_key_here
PESAPAL_CONSUMER_SECRET=your_consumer_secret_here

Request Token Endpoint

POST https://pay.pesapal.com/v3/api/Auth/RequestToken
Content-Type: application/json

Request Body:

{
  "consumer_key": "your_consumer_key",
  "consumer_secret": "your_consumer_secret"
}

Success Response (200 OK):

{
  "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwczovL3BheS5wZXNhcGFsLmNvbSIsImF1ZCI6IlBlc2FwYWwiLCJpYXQiOjE3MDg2NTk2MjcsImV4cCI6MTcwODY1OTkyN30.abc123xyz",
  "expiresIn": 300,
  "error": null
}

Token Usage

Include the token as a Bearer token in subsequent requests:

Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...

Tokens expire after 300 seconds (5 minutes). Always handle 401 responses by requesting a fresh token. Implement token caching to avoid excessive token requests.

Base URLs

• Production: https://pay.pesapal.com/v3/api
• Sandbox/Testing: https://cybqa.pesapal.com/pesapalv3/api

Core API Reference

All endpoints require the Authorization: Bearer {token} header and Content-Type: application/json.

1. Request OAuth Token

Generate a Bearer token from your credentials.

Endpoint:

POST /Auth/RequestToken

Request:

{
  "consumer_key": "YOUR_CONSUMER_KEY",
  "consumer_secret": "YOUR_CONSUMER_SECRET"
}

Response:

{
  "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
  "expiresIn": 300,
  "error": null
}

Use the token value in all subsequent API calls. Cache this token and refresh when you receive a 401 response.

2. Register Webhook/IPN Notification URL

Before submitting order requests, register a webhook URL where Pesapal will send payment status notifications.

Endpoint:

POST /URLSetup/RegisterIPN
Authorization: Bearer {token}

Request Body:

{
  "url": "https://yourdomain.com/api/pesapal/webhook",
  "ipn_notification_type": "GET"
}

Response (200 OK):

{
  "url": "https://yourdomain.com/api/pesapal/webhook",
  "created_date": "2025-02-20T10:30:00Z",
  "ipn_id": "ca870eb0-3d31-4cba-b7e3-e53c1fb13fbd",
  "error": null,
  "status": "200"
}

Important Notes:

• The ipn_id returned is your IPN ID (notification_id) — save this; you'll reference it as notification_id in order requests
• The webhook URL must be publicly accessible and return a 200 OK response
• Pesapal will retry failed webhook deliveries
• During development, use an ngrok tunnel: https://your-ngrok-url.ngrok-free.app/api/pesapal/webhook

3. Submit Order Request (Initiate Payment)

Create a payment transaction and receive a checkout URL to redirect customers to.

Endpoint:

POST /Transactions/SubmitOrderRequest
Authorization: Bearer {token}

Request Body:

{
  "id": "ORDER-20250220-001",
  "currency": "KES",
  "amount": 1500.00,
  "description": "Purchase of digital subscription",
  "callback_url": "https://yourdomain.com/payment/callback",
  "redirect_mode": "",
  "notification_id": "ca870eb0-3d31-4cba-b7e3-e53c1fb13fbd",
  "branch": "Online Store - Nairobi",
  "billing_address": {
    "email_address": "[email protected]",
    "phone_number": "+254712345678",
    "country_code": "KE",
    "first_name": "John",
    "middle_name": "",
    "last_name": "Doe",
    "line_1": "123 Main Street",
    "line_2": "Apartment 4B",
    "city": "Nairobi",
    "state": "Nairobi",
    "postal_code": "00100",
    "zip_code": ""
  }
}

Response (200 OK):

{
  "order_tracking_id": "9c4c5b3e6f2a1d8e7c9b4a5f6d3e2c1b",
  "merchant_reference": "ORDER-20250220-001",
  "redirect_url": "https://pay.pesapal.com/checkout?reference=9c4c5b3e6f2a1d8e7c9b4a5f6d3e2c1b",
  "error": null
}

Field Details:

• id: Your unique order reference (must be unique per transaction)
• currency: Payment currency — KES, UGX, TZS, or RWF
• amount: Payment amount in decimal format (e.g., 1500.00 for 1500 KES)
• notification_id: IPN ID from RegisterIPNURL endpoint (mandatory)
• callback_url: URL customer returns to after payment (gets order_tracking_id as query param)
• redirect_mode: Optional; specify preferred payment method or leave blank for all methods

Usage Flow:

1. Create the order request
2. Redirect customer to the redirect_url
3. Customer selects payment method and completes payment
4. Pesapal redirects to callback_url with ?order_tracking_id=9c4c5b3e6f2a1d8e7c9b4a5f6d3e2c1b
5. Call GetTransactionStatus to verify the payment server-side

4. Get Transaction Status

Verify payment completion server-side. Call this after redirect callback and when receiving webhook notifications.

Endpoint:

GET /Transactions/GetTransactionStatus?order_tracking_id=9c4c5b3e6f2a1d8e7c9b4a5f6d3e2c1b
Authorization: Bearer {token}

Response (200 OK):

{
  "id": "12345",
  "reference": "9c4c5b3e6f2a1d8e7c9b4a5f6d3e2c1b",
  "merchant_reference": "ORDER-20250220-001",
  "amount": 1500.00,
  "currency": "KES",
  "status": "COMPLETED",
  "description": "Purchase of digital subscription",
  "payment_method": "MPESA",
  "payment_status_description": "Transaction has been processed successfully",
  "created_date": "2025-02-20T10:30:00Z",
  "completion_date": "2025-02-20T10:32:15Z",
  "confirmation_code": "PESAPAL_CONF_ABC123XYZ"
}

Status Values:

• COMPLETED: Payment successful; funds received
• PENDING: Payment initiated; awaiting completion
• FAILED: Payment declined or failed; customer can retry
• INVALID: Invalid or cancelled transaction

Validation Logic:

// Pseudo-code for payment verification
if (response.status === "COMPLETED" && response.amount === expectedAmount && response.currency === expectedCurrency) {
  // Payment verified — fulfill order
  fulfillOrder(response.merchant_reference);
} else {
  // Payment incomplete or mismatched — do not fulfill
  logError(`Payment verification failed for ${response.merchant_reference}`);
}

5. Get Transaction List

Retrieve paginated transaction history for reporting and reconciliation.

Endpoint:

GET /Transactions/GetTransactions?pageNumber=1&pageSize=50&startDate=2025-01-01&endDate=2025-12-31
Authorization: Bearer {token}

Query Parameters:

• pageNumber: Pagination page (1-indexed, default: 1)
• pageSize: Records per page (1-100, default: 50)
• startDate: ISO 8601 date filter (optional)
• endDate: ISO 8601 date filter (optional)

Response:

{
  "data": [
    {
      "id": "12345",
      "reference": "9c4c5b3e6f2a1d8e7c9b4a5f6d3e2c1b",
      "merchant_reference": "ORDER-20250220-001",
      "amount": 1500.00,
      "currency": "KES",
      "status": "COMPLETED",
      "payment_method": "MPESA",
      "created_date": "2025-02-20T10:30:00Z",
      "completion_date": "2025-02-20T10:32:15Z"
    }
  ],
  "pageNumber": 1,
  "pageSize": 50,
  "totalRecords": 1250
}

Use this endpoint for transaction reconciliation, reporting, and audit trails.

6. Refund Request

Issue full or partial refunds for completed transactions. Refunds are sent to the original payment method.

Endpoint:

POST /Transactions/RefundRequest
Authorization: Bearer {token}

Request Body:

{
  "reference": "9c4c5b3e6f2a1d8e7c9b4a5f6d3e2c1b",
  "amount": 500.00,
  "reason": "Customer requested refund due to duplicate charge",
  "username": "merchant_username"
}

Response (200 OK):

{
  "status": "PENDING",
  "refund_id": "REF-20250220-001",
  "reference": "9c4c5b3e6f2a1d8e7c9b4a5f6d3e2c1b",
  "amount": 500.00,
  "reason": "Customer requested refund due to duplicate charge",
  "created_date": "2025-02-20T11:45:00Z"
}

Refund Constraints:

• Can only refund COMPLETED transactions
• Cannot refund more than the original transaction amount
• Partial refunds allowed for card payments only (mobile money refunds must be full amount)
• Only one refund per transaction
• Refunds are performed in the original transaction currency
• Refund approval required by merchant (not instant)

Refund Timeline:

• Card refunds: 3-5 business days to customer's card
• Mobile money refunds: 1-2 hours to customer's wallet

7. Get Registered IPNs

Retrieve all registered webhook URLs for your merchant account.

Endpoint:

GET /URLSetup/GetIpnList
Authorization: Bearer {token}

Response:

{
  "data": [
    {
      "id": "ca870eb0-3d31-4cba-b7e3-e53c1fb13fbd",
      "url": "https://yourdomain.com/api/pesapal/webhook",
      "active": true,
      "created_date": "2025-02-20T10:30:00Z"
    }
  ]
}

Use this to verify registered webhooks or manage multiple notification URLs.

8. Cancel Order

Cancel a pending or failed order request.

Endpoint:

POST /Transactions/CancelOrder
Authorization: Bearer {token}

Request Body:

{
  "order_tracking_id": "9c4c5b3e6f2a1d8e7c9b4a5f6d3e2c1b"
}

Response:

{
  "order_tracking_id": "9c4c5b3e6f2a1d8e7c9b4a5f6d3e2c1b",
  "status": "CANCELLED"
}

Only orders in PENDING or FAILED status can be cancelled.

Webhooks and IPN (Instant Payment Notifications)

IPN Flow

When a customer completes or fails a payment, Pesapal sends a POST request to your registered webhook URL with transaction details.

Webhook Request to Your Server:

POST https://yourdomain.com/api/pesapal/webhook
Content-Type: application/json

{
  "id": "12345",
  "reference": "9c4c5b3e6f2a1d8e7c9b4a5f6d3e2c1b",
  "merchant_reference": "ORDER-20250220-001",
  "status": "COMPLETED",
  "amount": 1500.00,
  "currency": "KES",
  "payment_method": "MPESA",
  "payment_status_description": "Transaction has been processed successfully",
  "created_date": "2025-02-20T10:30:00Z",
  "confirmation_code": "PESAPAL_CONF_ABC123XYZ"
}

Webhook Best Practices

1. Always verify server-side: Never trust webhook data alone. Always call GetTransactionStatus to verify the payment:

// Example: Node.js webhook handler
app.post('/api/pesapal/webhook', async (req, res) => {
  const { reference } = req.body;

  try {
    // Verify transaction on Pesapal servers
    const response = await fetch(
      `https://pay.pesapal.com/v3/api/Transactions/GetTransactionStatus?order_tracking_id=${reference}`,
      {
        headers: {
          'Authorization': `Bearer ${accessToken}`,
          'Content-Type': 'application/json'
        }
      }
    );

    const transaction = await response.json();

    if (transaction.status === 'COMPLETED') {
      // Update database and fulfill order
      await db.orders.update(
        { pesapal_reference: reference },
        { status: 'paid', completed_at: new Date() }
      );
      await fulfillOrder(transaction.merchant_reference);
    }

    // Always return 200 OK to acknowledge receipt
    res.status(200).json({ success: true });
  } catch (error) {
    console.error('Webhook processing failed:', error);
    res.status(500).json({ error: 'Webhook processing failed' });
  }
});

2. Return 200 OK immediately: Pesapal expects a 200 response within 5 seconds. Process asynchronously if needed.

3. Handle retries: Pesapal retries failed webhooks; use idempotency keys to prevent duplicate processing.

4. Log all webhooks: Store webhook payloads for audit trails and debugging.

IPN Registration in Dashboard

Alternatively, register webhooks directly in your Pesapal Dashboard:

1. Navigate to Settings → API Notifications
2. Enter your webhook URL
3. Click "Register"
4. Save the returned notification_id

Common Integration Patterns

Pattern 1: Basic Payment Checkout

1. Customer clicks "Pay Now"
   ↓
2. Backend: POST /Auth/RequestToken → get Bearer token
   ↓
3. Backend: POST /Transactions/SubmitOrderRequest → get redirect_url
   ↓
4. Frontend: Redirect customer to redirect_url
   ↓
5. Customer: Selects payment method and pays
   ↓
6. Pesapal: Redirects to callback_url with ?order_tracking_id=XXX
   ↓
7. Frontend: GET /Transactions/GetTransactionStatus from backend
   ↓
8. Backend: Verify status === "COMPLETED" and amount matches
   ↓
9. Fulfill order (email confirmation, download link, shipment, etc.)
   ↓
10. (Async) Pesapal IPN webhook provides redundant confirmation

Pattern 2: Webhook-Driven Order Fulfillment

1. Customer completes payment on Pesapal's page
   ↓
2. Pesapal sends IPN to your webhook with transaction details
   ↓
3. Your webhook handler calls GetTransactionStatus to verify
   ↓
4. If verified, update database and trigger fulfillment
   ↓
5. Return 200 OK to Pesapal

Pattern 3: Order Tracking Page

1. After redirect callback, customer sees "Processing..." page
   ↓
2. Page polls GET /Transactions/GetTransactionStatus every 2-3 seconds
   ↓
3. On status change to COMPLETED, display confirmation
   ↓
4. Webhook provides server-side confirmation for fulfillment

Pattern 4: Multi-Currency Marketplace

// Pesapal automatically converts prices
const submitOrder = async (order) => {
  const currency = {
    'KE': 'KES',
    'UG': 'UGX',
    'TZ': 'TZS',
    'RW': 'RWF'
  }[order.country];

  const payload = {
    id: order.id,
    currency: currency,
    amount: order.amount,
    billing_address: {
      ...order.billing_data,
      country_code: order.country
    },
    // ... other fields
  };

  return await submitOrderRequest(payload);
};

Error Handling

HTTP Status Codes

Common Error Scenarios

Pesapal wraps all errors in an error object with type, code, and message fields:

{
  "error": {
    "type": "error_type",
    "code": "error_code",
    "message": "Detailed error message"
  }
}

1. Invalid Token (401)

{
  "error": {
    "type": "unauthorized",
    "code": "401",
    "message": "Invalid or expired token"
  }
}

Solution: Request a new token via POST /Auth/RequestToken

2. Missing Required Fields (400)

{
  "error": {
    "type": "bad_request",
    "code": "400",
    "message": "notification_id is required"
  }
}

Solution: Ensure all required fields in request body are present

3. Duplicate Order ID (400)

{
  "error": {
    "type": "bad_request",
    "code": "400",
    "message": "Order with id ORDER-20250220-001 already exists"
  }
}

Solution: Ensure order IDs are globally unique; use timestamps or UUIDs

4. Order Not Found (404)

{
  "error": {
    "type": "not_found",
    "code": "404",
    "message": "Transaction not found"
  }
}

Solution: Verify the order_tracking_id is correct

Retry Strategy

Implement exponential backoff for transient errors:

const retryWithBackoff = async (fn, maxRetries = 3) => {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await fn();
    } catch (error) {
      if (attempt === maxRetries - 1) throw error;
      if (![500, 503].includes(error.status)) throw error; // Don't retry client errors

      const delayMs = Math.pow(2, attempt) * 1000; // 1s, 2s, 4s
      await new Promise(resolve => setTimeout(resolve, delayMs));
    }
  }
};

// Usage
const transaction = await retryWithBackoff(() =>
  getTransactionStatus(order_tracking_id)
);

Supported Currencies and Payment Methods

Kenya (KES)

• Mobile Money: M-Pesa (Safaricom)
• Cards: Visa, Mastercard, American Express
• Bank Transfers: Equity Bank, KCB, Standard Chartered
• Digital: Airtel Money

Uganda (UGX)

• Mobile Money: MTN Mobile Money, Airtel Money
• Cards: Visa, Mastercard
• Bank Transfers: Stanbic, Standard Chartered, Uganda Commercial Bank
• Digital: Pesapal Sabi (POS terminal for Visa/MC)

Tanzania (TZS)

• Mobile Money: Tigo Pesa, Vodacom M-Pesa, Airtel Money
• Cards: Visa, Mastercard
• Bank Transfers: NMB Bank, CRDB Bank, Equity Bank

Rwanda (RWF)

• Mobile Money: MTN Mobile Money, Airtel Money
• Cards: Visa, Mastercard
• Bank Transfers: BPR Bank, Equity Bank, KCB Rwanda

Important Notes and Gotchas

Token Management

• Tokens expire after 300 seconds (5 minutes)
• Cache tokens and reuse within the 5-minute window to reduce requests
• Always handle 401 responses by requesting a fresh token
• Never hardcode tokens; always request fresh tokens on startup

Order IDs

• Must be unique per transaction across your entire system
• Use UUID v4 or timestamp-random format to ensure uniqueness
• Cannot contain special characters; use alphanumeric and hyphens only
• 50-character maximum length

Payment Verification

• Never fulfill orders based on frontend callbacks alone
• Always verify status === "COMPLETED" and amount === expectedAmount server-side
• Implement idempotent order fulfillment to handle duplicate webhooks
• Use database transactions to prevent double-fulfillment

IPN Webhooks

• Webhook URLs must be publicly accessible (no localhost/private IPs)
• Return 200 OK within 5 seconds; process fulfillment asynchronously
• Pesapal retries failed webhooks; implement idempotency
• During development, use ngrok or similar tunneling service
• Test webhook registration before going live

Currency Handling

• Amounts must be in decimal format (1500.00, not 150000 cents)
• Pesapal automatically handles local currency conversions
• Card payments may be in USD; mobile money in local currency
• Specify correct currency code (KES, UGX, TZS, RWF) or request will fail

Refunds

• Only COMPLETED transactions can be refunded
• Cannot refund more than the original amount
• Partial refunds only supported for card payments
• Mobile money refunds must be full amount
• Only one refund per transaction allowed
• Merchant approval required; not instant

PCI-DSS Compliance

• Pesapal is PCI-DSS Level 1 certified
• Never capture or store card data yourself
• All card data handled by Pesapal's secure page
• Your application never receives raw card information

Testing

• Use sandbox credentials from Pesapal Dashboard
• Sandbox URL: https://cybqa.pesapal.com/pesapalv3/api
• Test with various payment methods before going live
• Sandbox transactions don't incur fees

Useful Links

• Developer Documentation: https://developer.pesapal.com/
• API Reference: https://developer.pesapal.com/how-to-integrate/e-commerce/api-30-json/api-reference
• Authentication Guide: https://developer.pesapal.com/how-to-integrate/e-commerce/api-30-json/authentication
• SubmitOrderRequest: https://developer.pesapal.com/how-to-integrate/e-commerce/api-30-json/submitorderrequest
• GetTransactionStatus: https://developer.pesapal.com/how-to-integrate/e-commerce/api-30-json/gettransactionstatus
• RegisterIPNURL: https://developer.pesapal.com/how-to-integrate/e-commerce/api-30-json/registeripnurl
• RefundRequest: https://developer.pesapal.com/how-to-integrate/e-commerce/api-30-json/refund-request
• Merchant Dashboard: https://dashboard.pesapal.com
• Forum & Support: https://developer.pesapal.com/forum