How To Generate A SaylorPay Direct Payment Links Via The API - API Docs

Article Image


POST /v1/payment-links

Create a hosted SaylorPay payment link that a customer can open to complete a mobile-money payment.

Base URL: https://saylorpay.com/api
Method: POST
Path: /v1/payment-links
Cost: $0.02 per successful creation (deducted from the merchant's balance)
Idempotent: No — each successful call creates a new link 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

Unlike payment buttons and QR codes, unverified merchants can call this endpoint. Verification is not required.


Request body

FieldTypeRequiredDefaultDescription
amountnumberYes—Payment amount, greater than 0, at most 2 decimal places.
referencestringYes—Merchant reference. 1–24 characters, alphanumeric (A–Z, a–z, 0–9) only.
currencystringNoMerchant's default_currencyOnly "GHS" is honored. Any other value falls back to the merchant's default currency.
descriptionstringNo""Free-form description shown to the payer. Max 150 characters.
expire_afterintegerNo30Link lifetime in minutes. 1–43200 (1 minute to 30 days).

Validation rules


Example request

bash
curl -X POST https://saylorpay.com/api/v1/payment-links \
  -H "X-API-Key: sk_live_9fK2mQx7Lp" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100.00,
    "reference": "INV2024AB12",
    "currency": "GHS",
    "description": "Order #1234",
    "expire_after": 60
  }'

Success response — 201 Created

json
{
  "success": true,
  "payment_url": "https://pay.saylorpay.com/9f2c1e4b7a8d4c6e9b0a1f3d5e7c2a4b",
  "tracking_id": "9f2c1e4b7a8d4c6e9b0a1f3d5e7c2a4b",
  "expire_after": 60
}
FieldTypeDescription
successbooleantrue
payment_urlstringHosted payment page URL. Share this with the payer.
tracking_idstringIdentifier for this payment link.
expire_afterintegerThe lifetime actually applied, in minutes.

The link remains valid until expire_after minutes have elapsed from creation.


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":"description must be at most 150 characters"}Description too long
400{"error":"expire_after must be an integer between 1 and 43200 minutes"}Invalid expiry
400{"error":"Invalid JSON body"}Body not valid JSON
401{"error":"API key required"}No X-API-Key header
401{"error":"Invalid API key"}Unknown or malformed key
402{"error":"Insufficient balance","balance":<number>}Balance below $0.02
500{"error":"<balance error>","balance":<number|null>}Could not verify/deduct balance
500{"error":"Failed to create payment link, api call refund was successful","amount_refunded":0.02}Creation failed; charge refunded
500{"error":"Critical: Failed to create payment link AND failed to refund user","original_amount":0.02,"refund_error":"..."}Creation and refund failed — contact support

Billing


Notes & gotchas


Examples (multi-language)

JavaScript (fetch)

javascript
const res = await fetch("https://saylorpay.com/api/v1/payment-links", {
  method: "POST",
  headers: {
    "X-API-Key": "sk_live_9fK2mQx7Lp",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    amount: 100.00,
    reference: "INV2024AB12",
    currency: "GHS",
    description: "Order #1234",
    expire_after: 60
  })
});
const data = await res.json();
if (!res.ok) throw new Error(data.error);
console.log(data.payment_url);

Python (requests)

python
import requests

resp = requests.post(
    "https://saylorpay.com/api/v1/payment-links",
    headers={
        "X-API-Key": "sk_live_9fK2mQx7Lp",
        "Content-Type": "application/json",
    },
    json={
        "amount": 100.00,
        "reference": "INV2024AB12",
        "currency": "GHS",
        "description": "Order #1234",
        "expire_after": 60,
    },
)
data = resp.json()
if not resp.ok:
    raise Exception(data.get("error"))
print(data["payment_url"])

PHP (cURL)

php
<?php
$ch = curl_init("https://saylorpay.com/api/v1/payment-links");
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" => 100.00,
        "reference" => "INV2024AB12",
        "currency" => "GHS",
        "description" => "Order #1234",
        "expire_after" => 60,
    ]),
]);
$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["payment_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.