Quickstart

This page takes you from nothing to a completed sandbox payment. It should take you about ten minutes, and you do not need a Pesapal account to follow along.

The flow has five steps:

1. Exchange your credentials for an access token
2. Register a URL where Pesapal can notify your server
3. Create an order and get a payment link
4. Send the customer to that link
5. Verify the payment actually completed

Prerequisites

Pesapal publishes sandbox credentials openly, so grab them from the demo keys page.

All requests in this page use the sandbox base URL:

https://cybqa.pesapal.com/pesapalv3/api

The sandbox is a shared account

Every developer using the sandbox shares one merchant account.

Use a notification URL nobody else would use and never put any sensitive details in a test order.

1. Get an Access token

1. Exchange your consumer key and secret for a token.

   cURL

   curl --request POST \
     --url https://cybqa.pesapal.com/pesapalv3/api/Auth/RequestToken \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --data '{
     "consumer_key": "YOUR_CONSUMER_KEY",
     "consumer_secret": "YOUR_CONSUMER_SECRET"
   }'

   Node.js

   const url = 'https://cybqa.pesapal.com/pesapalv3/api/Auth/RequestToken';
   const options = {
     method: 'POST',
     headers: {Accept: 'application/json', 'Content-Type': 'application/json'},
     body: '{"consumer_key":"YOUR_CONSUMER_KEY","consumer_secret":"YOUR_CONSUMER_SECRET"}'
   };
   
   try {
     const response = await fetch(url, options);
     const data = await response.json();
     console.log(data);
   } catch (error) {
     console.error(error);
   }

   Python

   import requests
   
   url = "https://cybqa.pesapal.com/pesapalv3/api/Auth/RequestToken"
   
   payload = {
       "consumer_key": "YOUR_CONSUMER_KEY",
       "consumer_secret": "YOUR_CONSUMER_SECRET"
   }
   headers = {
       "Accept": "application/json",
       "Content-Type": "application/json"
   }
   
   response = requests.post(url, json=payload, headers=headers)
   
   print(response.json())

   PHP

   <?php
   
   $curl = curl_init();
   
   curl_setopt_array($curl, [
     CURLOPT_URL => "https://cybqa.pesapal.com/pesapalv3/api/Auth/RequestToken",
     CURLOPT_RETURNTRANSFER => true,
     CURLOPT_ENCODING => "",
     CURLOPT_MAXREDIRS => 10,
     CURLOPT_TIMEOUT => 30,
     CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
     CURLOPT_CUSTOMREQUEST => "POST",
     CURLOPT_POSTFIELDS => json_encode([
       'consumer_key' => 'YOUR_CONSUMER_KEY',
       'consumer_secret' => 'YOUR_CONSUMER_SECRET'
     ]),
     CURLOPT_HTTPHEADER => [
       "Accept: application/json",
       "Content-Type: application/json"
     ],
   ]);
   
   $response = curl_exec($curl);
   $err = curl_error($curl);
   
   curl_close($curl);
   
   if ($err) {
     echo "cURL Error #:" . $err;
   } else {
     echo $response;
   }

   Go

   package main
   
   import (
     "fmt"
     "strings"
     "net/http"
     "io"
   )
   
   func main() {
   
     url := "https://cybqa.pesapal.com/pesapalv3/api/Auth/RequestToken"
   
     payload := strings.NewReader("{\n  \"consumer_key\": \"YOUR_CONSUMER_KEY\",\n  \"consumer_secret\": \"YOUR_CONSUMER_SECRET\"\n}")
   
     req, _ := http.NewRequest("POST", url, payload)
   
     req.Header.Add("Accept", "application/json")
     req.Header.Add("Content-Type", "application/json")
   
     res, _ := http.DefaultClient.Do(req)
   
     defer res.Body.Close()
     body, _ := io.ReadAll(res.Body)
   
     fmt.Println(res)
     fmt.Println(string(body))
   
   }

2. Save the token from the response. It’s valid for one hour, so cache it rather than requesting a new one per call.

   {
       "token": "eyJhbGciOiJIUzI1N....",
       "expiryDate": "2026-09-03T12:08:08.5585879Z",
       "error": null,
       "status": "200",
       "message": "Request processed successfully"
   }

2. Register a Notification URL

Pesapal calls this URL when an order changes. You register it once and reuse the id it returns on every order.

1. Register your endpoint. For now, a request bin from webhook.site works and requires no setup.

   cURL

   curl --request POST \
     --url https://cybqa.pesapal.com/pesapalv3/api/URLSetup/RegisterIPN \
     --header 'Accept: application/json' \
     --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
     --header 'Content-Type: application/json' \
     --data '{
     "url": "https://example.com/pesapal/ipn",
     "ipn_notification_type": "GET"
   }'

   Node.js

   const url = 'https://cybqa.pesapal.com/pesapalv3/api/URLSetup/RegisterIPN';
   const options = {
     method: 'POST',
     headers: {
       Authorization: 'Bearer YOUR_ACCESS_TOKEN',
       Accept: 'application/json',
       'Content-Type': 'application/json'
     },
     body: '{"url":"https://example.com/pesapal/ipn","ipn_notification_type":"GET"}'
   };
   
   try {
     const response = await fetch(url, options);
     const data = await response.json();
     console.log(data);
   } catch (error) {
     console.error(error);
   }

   Python

   import requests
   
   url = "https://cybqa.pesapal.com/pesapalv3/api/URLSetup/RegisterIPN"
   
   payload = {
       "url": "https://example.com/pesapal/ipn",
       "ipn_notification_type": "GET"
   }
   headers = {
       "Authorization": "Bearer YOUR_ACCESS_TOKEN",
       "Accept": "application/json",
       "Content-Type": "application/json"
   }
   
   response = requests.post(url, json=payload, headers=headers)
   
   print(response.json())

   PHP

   <?php
   
   $curl = curl_init();
   
   curl_setopt_array($curl, [
     CURLOPT_URL => "https://cybqa.pesapal.com/pesapalv3/api/URLSetup/RegisterIPN",
     CURLOPT_RETURNTRANSFER => true,
     CURLOPT_ENCODING => "",
     CURLOPT_MAXREDIRS => 10,
     CURLOPT_TIMEOUT => 30,
     CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
     CURLOPT_CUSTOMREQUEST => "POST",
     CURLOPT_POSTFIELDS => json_encode([
       'url' => 'https://example.com/pesapal/ipn',
       'ipn_notification_type' => 'GET'
     ]),
     CURLOPT_HTTPHEADER => [
       "Accept: application/json",
       "Authorization: Bearer YOUR_ACCESS_TOKEN",
       "Content-Type: application/json"
     ],
   ]);
   
   $response = curl_exec($curl);
   $err = curl_error($curl);
   
   curl_close($curl);
   
   if ($err) {
     echo "cURL Error #:" . $err;
   } else {
     echo $response;
   }

   Go

   package main
   
   import (
     "fmt"
     "strings"
     "net/http"
     "io"
   )
   
   func main() {
   
     url := "https://cybqa.pesapal.com/pesapalv3/api/URLSetup/RegisterIPN"
   
     payload := strings.NewReader("{\n  \"url\": \"https://example.com/pesapal/ipn\",\n  \"ipn_notification_type\": \"GET\"\n}")
   
     req, _ := http.NewRequest("POST", url, payload)
   
     req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")
     req.Header.Add("Accept", "application/json")
     req.Header.Add("Content-Type", "application/json")
   
     res, _ := http.DefaultClient.Do(req)
   
     defer res.Body.Close()
     body, _ := io.ReadAll(res.Body)
   
     fmt.Println(res)
     fmt.Println(string(body))
   
   }

2. Save the ipn_id from the response. That value is your notification_id in the next step.

   {
       "url": "https://webhook.site/c83....",
       "created_date": "2026-09-03T11:29:08.61",
       "ipn_id":"28f0d4...",
       "notification_type": 0,
       "ipn_notification_type_description": "GET",
       "ipn_status": 1,
       "ipn_status_decription": "Active",
       "status":"200",
       "message":"Request processed successfully"
   }

Pesapal never checks that your URL works

Registration validates that the value looks like a URL and nothing else. A typo registers successfully, reports Active, and then silently never delivers a notification.

Send a request to your own endpoint before trusting it. See Instant Payment Notifications.

3. Create an Order

cURL

curl --request POST \
  --url https://cybqa.pesapal.com/pesapalv3/api/Transactions/SubmitOrderRequest \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "id": "ORDER-1234",
  "currency": "KES",
  "amount": 100,
  "description": "Test Payment",
  "callback_url": "https://example.com/payment-complete",
  "notification_id": "YOUR_IPN_ID",
  "billing_address": {
    "email_address": "customer@example.com"
  }
}'

Node.js

const url = 'https://cybqa.pesapal.com/pesapalv3/api/Transactions/SubmitOrderRequest';
const options = {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_ACCESS_TOKEN',
    Accept: 'application/json',
    'Content-Type': 'application/json'
  },
  body: '{"id":"ORDER-1234","currency":"KES","amount":100,"description":"Test Payment","callback_url":"https://example.com/payment-complete","notification_id":"YOUR_IPN_ID","billing_address":{"email_address":"customer@example.com"}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

Python

import requests

url = "https://cybqa.pesapal.com/pesapalv3/api/Transactions/SubmitOrderRequest"

payload = {
    "id": "ORDER-1234",
    "currency": "KES",
    "amount": 100,
    "description": "Test Payment",
    "callback_url": "https://example.com/payment-complete",
    "notification_id": "YOUR_IPN_ID",
    "billing_address": { "email_address": "customer@example.com" }
}
headers = {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "Accept": "application/json",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())

PHP

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://cybqa.pesapal.com/pesapalv3/api/Transactions/SubmitOrderRequest",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'id' => 'ORDER-1234',
    'currency' => 'KES',
    'amount' => 100,
    'description' => 'Test Payment',
    'callback_url' => 'https://example.com/payment-complete',
    'notification_id' => 'YOUR_IPN_ID',
    'billing_address' => [
        'email_address' => 'customer@example.com'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Accept: application/json",
    "Authorization: Bearer YOUR_ACCESS_TOKEN",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

Go

package main

import (
  "fmt"
  "strings"
  "net/http"
  "io"
)

func main() {

  url := "https://cybqa.pesapal.com/pesapalv3/api/Transactions/SubmitOrderRequest"

  payload := strings.NewReader("{\n  \"id\": \"ORDER-1234\",\n  \"currency\": \"KES\",\n  \"amount\": 100,\n  \"description\": \"Test Payment\",\n  \"callback_url\": \"https://example.com/payment-complete\",\n  \"notification_id\": \"YOUR_IPN_ID\",\n  \"billing_address\": {\n    \"email_address\": \"customer@example.com\"\n  }\n}")

  req, _ := http.NewRequest("POST", url, payload)

  req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")
  req.Header.Add("Accept", "application/json")
  req.Header.Add("Content-Type", "application/json")

  res, _ := http.DefaultClient.Do(req)

  defer res.Body.Close()
  body, _ := io.ReadAll(res.Body)

  fmt.Println(res)
  fmt.Println(string(body))

}

Field	Required	Notes
id	Yes	Your own reference. Must be unique, maximum 50 characters.
currency	Yes	ISO code, for example KES.
amount	Yes	Number or string. Must be greater than zero.
description	Yes	Shown to the customer.
callback_url	Yes	Where the customer’s browser lands after paying.
notification_id	Yes	The ipn_id from step 2.
billing_address	Yes	Must be present. May be an empty object.

Your response should be similar to the following:

{
  "order_tracking_id": "523a3fb1-568b-4c53-b9ff-d9f2c4866653",
  "merchant_reference": "ORDER-1234",
  "redirect_url": "https://cybqa.pesapal.com/pesapaliframe/PesapalIframe3/Index?OrderTrackingId=523a3fb1-...",
  "error": null,
  "status": "200"
}

Store order_tracking_id against your order. It is how you look the payment up later.

Reusing an id silently returns the old order

Submitting an id you have used before returns the original order, at its original amount, with no error. Change the amount and retry with the same reference and you will get back a payment link for the old price.

Generate a fresh id for every order.

Over 50 characters fails without saying why

An id between 51 and 150 characters returns Unable to process your order at the moment.Please try again later, which never mentions length. Keep it under 50.

4. Send the Customer to the Payment Page

Redirect the customer to redirect_url. They choose a payment method and pay using a test card:

Card	Number	Expiry	CVV
Visa, approves	4761 7390 0101 0010	07/28	123

Once the payment is successful, the customer lands back on your callback_url with two query parameters appended:

https://example.com/payment-complete?OrderTrackingId=523a3fb1-...&OrderMerchantReference=ORDER-1234

The callback is not a payment confirmation

Those query parameters tell you nothing about whether the payment succeeded, and the customer may close the tab before the redirect happens. Treat the callback as a cue to show a “checking your payment page”, never as proof.

5. Verify the Payment

This is the step that determines whether the money moved.

cURL

curl --request GET \
  --url 'https://cybqa.pesapal.com/pesapalv3/api/Transactions/GetTransactionStatus?orderTrackingId=YOUR_ORDER_TRACKING_ID' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Node.js

const url = 'https://cybqa.pesapal.com/pesapalv3/api/Transactions/GetTransactionStatus?orderTrackingId=YOUR_ORDER_TRACKING_ID';
const options = {
  method: 'GET',
  headers: {Authorization: 'Bearer YOUR_ACCESS_TOKEN', Accept: 'application/json'}
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

Python

import requests

url = "https://cybqa.pesapal.com/pesapalv3/api/Transactions/GetTransactionStatus"

querystring = {"orderTrackingId":"YOUR_ORDER_TRACKING_ID"}

headers = {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "Accept": "application/json"
}

response = requests.get(url, headers=headers, params=querystring)

print(response.json())

PHP

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://cybqa.pesapal.com/pesapalv3/api/Transactions/GetTransactionStatus?orderTrackingId=YOUR_ORDER_TRACKING_ID",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Accept: application/json",
    "Authorization: Bearer YOUR_ACCESS_TOKEN"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

Go

package main

import (
  "fmt"
  "net/http"
  "io"
)

func main() {

  url := "https://cybqa.pesapal.com/pesapalv3/api/Transactions/GetTransactionStatus?orderTrackingId=YOUR_ORDER_TRACKING_ID"

  req, _ := http.NewRequest("GET", url, nil)

  req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")
  req.Header.Add("Accept", "application/json")

  res, _ := http.DefaultClient.Do(req)

  defer res.Body.Close()
  body, _ := io.ReadAll(res.Body)

  fmt.Println(res)
  fmt.Println(string(body))

}

Your response should be similar to the following:

{
  "payment_method": "Visa",
  "amount": 100,
  "confirmation_code": "7884396530786173704004",
  "payment_status_description": "Completed",
  "status_code": 1,
  "merchant_reference": "ORDER-1234",
  "currency": "KES"
}

status_code: 1 means completed, and 2 means the payment failed. That is the only field you should act on.

An unpaid order comes back as an error

Before the payment lands, the same request returns:

{
  "error": { "code": "payment_details_not_found", "message": "Pending Payment" },
  "status": "500"
}

This is normal. The order exists and is simply unpaid. Note also that the HTTP status is 200 for both success and failure on this API, so never branch on it. See Errors.

What next

You have taken a payment, but not yet built something you could run in production. Three things are missing:

• Handle the notification. Polling works for a demo. Real integrations act on the IPN, which is the only signal that reaches you if the customer closes the tab. See Instant Payment Notifications.
• Handle errors properly. This API returns HTTP 200 for failures and has eight distinct response shapes. See Errors.
• Cache your token. It lasts an hour, not the five minutes Pesapal documents. See Authentication.