How To Generate A SaylorPay Payment QR Code Via The API - API Docs

Article Image


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.

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 reference. 1–24 characters, alphanumeric (A–Z, a–z, 0–9) only.
receiving_accountstringNo"phone""phone" or "merchant_id_till". See Receiving account.
formatstringNo"png""png" or "jpg".
image_widthintegerNo350250–1000, multiple of 50.
image_heightintegerNo350250–1000, multiple of 50.
image_background_colorstringNo"#ffffff"Hex color. # optional.
image_foreground_startstringNo"#000000"Gradient start color. # optional.
image_foreground_middlestringNo"#000000"Gradient middle color. # optional.
image_foreground_endstringNo"#000000"Gradient end color. # optional.
jpeg_qualityintegerNo9070–100. Only applies when format is "jpg".

Validation rules

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-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

json
{
  "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"
  }
}
FieldTypeDescription
successbooleantrue
qr_code_urlstringURL of the generated QR image. Download and host this yourself — see File retention.
tracking_idstringID for this generation (also in the filename).
formatstring"png" or "jpg".
image_colorobjectThe 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_url as short-lived. Do not embed it directly in long-lived content.


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
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


Notes & gotchas


Examples (multi-language)

JavaScript (fetch)

javascript
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)

python
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
<?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"];
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.