How To Generate A SaylorPay Payment Button Via The API - API Docs

Article Image


POST /v1/payment-buttons

Generate a SaylorPay payment button: an encrypted deep link plus ready-to-embed HTML that a merchant can drop on their site or app to collect payment via mobile money.

Base URL: https://saylorpay.com/api/
Method: POST
Path: /v1/payment-buttons
Cost: $0.01 per successful generation (deducted from the merchant's balance)
Idempotent: No — each successful call creates a new button and charges again.

A NOTE on the Base URL: —the base url may change from time to time. Always confirm the latest base URL from the DEV Dashboard.



Authentication

HeaderRequiredValue
X-API-KeyYesYour merchant API key
Content-TypeYesapplication/json

Only merchants with verification_status = "verified" may call this endpoint.


Request body

FieldTypeRequiredDefaultDescription
amountnumberYes—Payment amount, greater than 0, at most 2 decimal places. e.g. 10, 10.00, 10.20.
referencestringYes—Merchant-supplied reference. 1–24 characters, alphanumeric (A–Z, a–z, 0–9) only.
currencystringNoGHSOnly "GHS" is accepted.
receiving_accountstringNo"phone""phone" or "merchant_id_till". See Receiving account.
button_colorstringNo"#03a9f4"Strictly #rrggbb (6 hex digits).

Validation rules

Reference guidance: use a unique reference for each payment (e.g. an order ID or a random string).

Receiving account

If "merchant_id_till" is requested but no till ID is configured, the API silently falls back to the phone number. Telco (MTN, Telecel, AirtelTigo) is resolved automatically from the merchant's configured network.


Example request

bash
curl -X POST https://saylorpay.com/api/v1/payment-buttons \
  -H "X-API-Key: sk_live_9fK2mQx7Lp" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 10.50,
    "reference": "INV2024AB12",
    "currency": "GHS",
    "receiving_account": "phone",
    "button_color": "#03a9f4"
  }'

Success response — 201 Created

json
{
  "success": true,
  "tracking_id": "9f2c1e4b7a8d4c6e9b0a1f3d5e7c2a4b",
  "button_html": "<a href='saylorpay://webpayment?data=...' target='_blank'><button data-tracking-id='9f2c1e4b7a8d4c6e9b0a1f3d5e7c2a4b' class='saylorpay-payment-button' style='...'>Pay With SaylorPay | &nbsp;<small>10.50</small>&nbsp;<small>GHS</small></button></a><style>...</style>",
  "button_link": "saylorpay://webpayment?data=...",
  "button_style": {
    "background_color": "#03a9f4",
    "text_color": "white"
  }
}
FieldTypeDescription
successbooleantrue
tracking_idstringID for this button generation. Also embedded in button_html as data-tracking-id.
button_htmlstringReady-to-embed HTML snippet. Safe to drop into a page as-is.
button_linkstringRaw saylorpay://webpayment?data=... deep link for custom UI or native apps.
button_style.background_colorstringColor actually used.
button_style.text_colorstringAlways "white".

The deep link is opened by the SaylorPay mobile app, which decrypts the embedded {receiver, amount, reference, telco} payload to complete the payment. button_html wraps button_link — use whichever suits you.


Error responses

All errors return {"error": "<message>"} unless noted.

StatusBodyWhen
400{"error":"amount is required"} / {"error":"reference is required"}Missing required field
400{"error":"amount must be a number greater than 0"}Invalid amount
400{"error":"reference must be 1-24 alphanumeric characters"}Invalid reference format
400{"error":"currency must be GHS"}Unsupported currency
400{"error":"receiving_account must be phone or merchant_id_till"}Invalid receiving account
400{"error":"button_color must be a hex color like #03a9f4"}Invalid color
400{"error":"Invalid JSON body"}Body not valid JSON
400{"error":"No receiving account configured"}Merchant has no account details / receiver
401{"error":"API key required"}No X-API-Key header
401{"error":"Invalid API key"}Unknown or malformed key
401{"error":"Only verified merchants are allowed to generate payment buttons. Please complete verification to proceed."}Merchant not verified
402{"error":"Insufficient balance","balance":<number>}Balance below $0.01
500{"error":"<balance error>","balance":<number|null>}Could not verify/deduct balance
500{"error":"Failed to generate payment button, but refund was successful","amount_refunded":0.01}Generation failed; charge refunded
500{"error":"Critical: Failed to generate button AND failed to refund","original_amount":0.01,"refund_error":"..."}Generation and refund both failed — contact support

Billing


Notes & gotchas


Examples (multi-language)

JavaScript (fetch)

javascript
const res = await fetch("https://saylorpay.com/api/v1/payment-buttons", {
  method: "POST",
  headers: {
    "X-API-Key": "sk_live_9fK2mQx7Lp",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    amount: 10.50,
    reference: "INV2024AB12",
    currency: "GHS",
    receiving_account: "phone",
    button_color: "#03a9f4"
  })
});
const data = await res.json();
if (!res.ok) throw new Error(data.error);
console.log(data.button_html);

Python (requests)

python
import requests

resp = requests.post(
    "https://saylorpay.com/api/v1/payment-buttons",
    headers={
        "X-API-Key": "sk_live_9fK2mQx7Lp",
        "Content-Type": "application/json",
    },
    json={
        "amount": 10.50,
        "reference": "INV2024AB12",
        "currency": "GHS",
        "receiving_account": "phone",
        "button_color": "#03a9f4",
    },
)
data = resp.json()
if not resp.ok:
    raise Exception(data.get("error"))
print(data["button_html"])

PHP (cURL)

php
<?php
$ch = curl_init("https://saylorpay.com/api/v1/payment-buttons");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "X-API-Key: sk_live_9fK2mQx7Lp",
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "amount" => 10.50,
        "reference" => "INV2024AB12",
        "currency" => "GHS",
        "receiving_account" => "phone",
        "button_color" => "#03a9f4",
    ]),
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

$data = json_decode($body, true);
if ($status !== 201) {
    throw new Exception($data["error"] ?? "Request failed");
}
echo $data["button_html"];

The Author

About the Author

With years of experience in mobile payment technologies across Africa. The Admin has led the development of SaylorPay's USSD automation engine.

Stay Updated

Subscribe to our newsletter for the latest insights on mobile money technology and financial inclusion in Africa.