POST /v1/payment-qrcodes
Generate a SaylorPay payment QR code image for a mobile-money payment.
Base URL: https://saylorpay.com/api/
Method: POST
Path: /v1/payment-qrcodes
Cost: $0.01 per successful generation (deducted from the merchant's balance)
Idempotent: No — each successful call creates a new QR image and charges again.
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 reference. 1–24 characters, alphanumeric (A–Z, a–z, 0–9) only. |
receiving_account | string | No | "phone" | "phone" or "merchant_id_till". See Receiving account. |
format | string | No | "png" | "png" or "jpg". |
image_width | integer | No | 350 | 250–1000, multiple of 50. |
image_height | integer | No | 350 | 250–1000, multiple of 50. |
image_background_color | string | No | "#ffffff" | Hex color. # optional. |
image_foreground_start | string | No | "#000000" | Gradient start color. # optional. |
image_foreground_middle | string | No | "#000000" | Gradient middle color. # optional. |
image_foreground_end | string | No | "#000000" | Gradient end color. # optional. |
jpeg_quality | integer | No | 90 | 70–100. Only applies when format is "jpg". |
Validation rules
amount— required, numeric,> 0, max 2 decimal places.reference— required;^[A-Za-z0-9]{1,24}$.receiving_account— if provided,"phone"or"merchant_id_till".format— if provided,"png"or"jpg".image_width/image_height— if provided, integer250–1000, multiple of50.Colors — if provided, a 6-digit hex color; a leading
#is accepted and optional (#03a9f4and03a9f4are equivalent).jpeg_quality— if provided, integer70–100.Invalid JSON body →
400.
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-qrcodes \ -H "X-API-Key: sk_live_9fK2mQx7Lp" \ -H "Content-Type: application/json" \ -d '{ "amount": 10.50, "reference": "INV2024AB12", "receiving_account": "phone", "format": "png", "image_width": 400, "image_height": 400, "image_background_color": "#ffffff", "image_foreground_start": "#03a9f4", "image_foreground_middle": "#03a9f4", "image_foreground_end": "#005f8a" }'
Success response — 201 Created
{ "success": true, "qr_code_url": "https://cdn.saylorpay.com/api-qrcodes/qr_9f2c1e4b7a8d4c6e9b0a1f3d5e7c2a4b.png", "tracking_id": "9f2c1e4b7a8d4c6e9b0a1f3d5e7c2a4b", "format": "png", "image_color": { "background": "FFFFFF", "foreground_start": "03A9F4", "foreground_middle": "03A9F4", "foreground_end": "005F8A" } }
| Field | Type | Description |
|---|---|---|
success | boolean | true |
qr_code_url | string | URL of the generated QR image. Download and host this yourself — see File retention. |
tracking_id | string | ID for this generation (also in the filename). |
format | string | "png" or "jpg". |
image_color | object | The colors actually used, normalized to 6-digit uppercase hex without #. |
The QR image encodes an encrypted SaylorPay payment payload, which the SaylorPay mobile app reads to complete the payment.
File retention
qr_code_url points to a temporary file on SaylorPay's servers. Generated QR images are deleted within 24–72 hours. Download the image and host it yourself for any long-lived use (emails, invoices, printed material, product pages).
Treat
qr_code_urlas short-lived. Do not embed it directly in long-lived content.
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 |
400 | {"error":"receiving_account must be phone or merchant_id_till"} | Invalid receiving account |
400 | {"error":"format must be png or jpg"} | Invalid format |
400 | {"error":"image_width must be an integer between 250 and 1000 in increments of 50"} | Invalid width |
400 | {"error":"image_height must be an integer between 250 and 1000 in increments of 50"} | Invalid height |
400 | {"error":"image_background_color must be a hex color like #ffffff"} (and same for other color fields) | Invalid color |
400 | {"error":"jpeg_quality must be an integer between 70 and 100"} | Invalid JPEG quality |
400 | {"error":"Invalid JSON body"} | Body not valid JSON |
400 | {"error":"No receiving account configured"} | Merchant has no account details |
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 QR codes. 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 QR code, but refund was successful","amount_refunded":0.01} | Generation failed; charge refunded |
500 | {"error":"Critical: Failed to generate QR code AND failed to refund","original_amount":0.01,"refund_error":"..."} | Generation and refund 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 image.
Notes & gotchas
reference— Use a unique reference per payment (telcos may uppercase it downstream).Colors — accepted with or without
#; echoed back without#, uppercased.Size —
250–1000, multiple of50.350(the default) is a valid value.Retention — images are deleted within 24–72 hours. Download and re-host.
No idempotency — two calls = two images = two charges.
Silent
receiving_accountfallback —merchant_id_tillwithout a configured till yields a phone-based QR, no error.HTTP 402 for insufficient balance.
Examples (multi-language)
JavaScript (fetch)
const res = await fetch("https://saylorpay.com/api/v1/payment-qrcodes", { method: "POST", headers: { "X-API-Key": "sk_live_9fK2mQx7Lp", "Content-Type": "application/json" }, body: JSON.stringify({ amount: 10.50, reference: "INV2024AB12", receiving_account: "phone", format: "png", image_width: 400, image_height: 400, image_background_color: "#ffffff", image_foreground_start: "#03a9f4", image_foreground_middle: "#03a9f4", image_foreground_end: "#005f8a" }) }); const data = await res.json(); if (!res.ok) throw new Error(data.error); console.log(data.qr_code_url);
Python (requests)
import requests resp = requests.post( "https://saylorpay.com/api/v1/payment-qrcodes", headers={ "X-API-Key": "sk_live_9fK2mQx7Lp", "Content-Type": "application/json", }, json={ "amount": 10.50, "reference": "INV2024AB12", "receiving_account": "phone", "format": "png", "image_width": 400, "image_height": 400, "image_background_color": "#ffffff", "image_foreground_start": "#03a9f4", "image_foreground_middle": "#03a9f4", "image_foreground_end": "#005f8a", }, ) data = resp.json() if not resp.ok: raise Exception(data.get("error")) print(data["qr_code_url"])
PHP (cURL)
<?php $ch = curl_init("https://saylorpay.com/api/v1/payment-qrcodes"); 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", "receiving_account" => "phone", "format" => "png", "image_width" => 400, "image_height" => 400, "image_background_color" => "#ffffff", "image_foreground_start" => "#03a9f4", "image_foreground_middle" => "#03a9f4", "image_foreground_end" => "#005f8a", ]), ]); $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["qr_code_url"];
Saylor