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
| Header | Required | Value |
|---|---|---|
X-API-Key | Yes | Your merchant API key |
Content-Type | Yes | application/json |
Only merchants with verification_status = "verified" may call this endpoint.
Request body
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
amount | number | Yes | — | Payment amount, greater than 0, at most 2 decimal places. e.g. 10, 10.00, 10.20. |
reference | string | Yes | — | Merchant-supplied reference. 1–24 characters, alphanumeric (A–Z, a–z, 0–9) only. |
currency | string | No | GHS | Only "GHS" is accepted. |
receiving_account | string | No | "phone" | "phone" or "merchant_id_till". See Receiving account. |
button_color | string | No | "#03a9f4" | Strictly #rrggbb (6 hex digits). |
Validation rules
amount— required, numeric,> 0, max 2 decimal places.reference— required;^[A-Za-z0-9]{1,24}$.currency— if provided, must be"GHS".receiving_account— if provided, must be"phone"or"merchant_id_till".button_color— if provided,^#[0-9a-fA-F]{6}$.Invalid JSON body →
400.
Reference guidance: use a unique reference for each payment (e.g. an order ID or a random string).
Receiving account
"phone"(default) — the merchant's mobile money phone number."merchant_id_till"— the merchant's mobile money merchant/till ID.
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
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
{ "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 | <small>10.50</small> <small>GHS</small></button></a><style>...</style>", "button_link": "saylorpay://webpayment?data=...", "button_style": { "background_color": "#03a9f4", "text_color": "white" } }
| Field | Type | Description |
|---|---|---|
success | boolean | true |
tracking_id | string | ID for this button generation. Also embedded in button_html as data-tracking-id. |
button_html | string | Ready-to-embed HTML snippet. Safe to drop into a page as-is. |
button_link | string | Raw saylorpay://webpayment?data=... deep link for custom UI or native apps. |
button_style.background_color | string | Color actually used. |
button_style.text_color | string | Always "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.
| Status | Body | When |
|---|---|---|
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
$0.01 deducted per successful generation.
Failed generations are not charged; post-deduction failures are refunded (
amount_refundedin the 500 response).Deduction failure or insufficient balance → no button.
Notes & gotchas
reference— format-validated only. Telcos may uppercase it downstream; use a fresh unique reference per payment.No idempotency — two calls = two buttons = two charges.
Silent
receiving_accountfallback — requestingmerchant_id_tillwithout one configured yields aphonedeep link with no error.HTTP 402 is used for insufficient balance; handle it explicitly in clients.
Deep link only resolves on devices with the SaylorPay app installed.
data-tracking-idis the HTML attribute on the generated button (not the legacytracking_id).
Examples (multi-language)
JavaScript (fetch)
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)
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 $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"];
Saylor