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.
Authentication
| Header | Required | Value |
|---|---|---|
X-API-Key | Yes | Your merchant API key |
Content-Type | Yes | application/json |
Unlike payment buttons and QR codes, unverified merchants can call this endpoint. Verification is not required.
Request body
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
amount | number | Yes | — | Payment amount, greater than 0, at most 2 decimal places. |
reference | string | Yes | — | Merchant reference. 1–24 characters, alphanumeric (A–Z, a–z, 0–9) only. |
currency | string | No | Merchant's default_currency | Only "GHS" is honored. Any other value falls back to the merchant's default currency. |
description | string | No | "" | Free-form description shown to the payer. Max 150 characters. |
expire_after | integer | No | 30 | Link lifetime in minutes. 1–43200 (1 minute to 30 days). |
Validation rules
amount— required, numeric,> 0, max 2 decimal places.reference— required;^[A-Za-z0-9]{1,24}$.currency— if provided, only"GHS"is honored; otherwise falls back todefault_currency.description— if provided, max 150 characters.expire_after— if provided, integer1–43200(minutes).Invalid JSON body →
400.
Example request
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
{ "success": true, "payment_url": "https://pay.saylorpay.com/9f2c1e4b7a8d4c6e9b0a1f3d5e7c2a4b", "tracking_id": "9f2c1e4b7a8d4c6e9b0a1f3d5e7c2a4b", "expire_after": 60 }
| Field | Type | Description |
|---|---|---|
success | boolean | true |
payment_url | string | Hosted payment page URL. Share this with the payer. |
tracking_id | string | Identifier for this payment link. |
expire_after | integer | The 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.
| 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":"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
$0.02 deducted per successful creation (higher than payment buttons and QR codes).
Failed creations are not charged; post-deduction failures are refunded (
amount_refundedin the 500 response).Deduction failure or insufficient balance → no link.
Notes & gotchas
No verification required — unlike the other generation endpoints, unverified merchants can create links.
reference— Use a unique reference per payment.currency— onlyGHSis honored. Non-GHS values fall back silently to the merchant's default currency; no error.expire_afteris in minutes. The response always echoes the value actually applied (the default30if you didn't send one).No idempotency — two calls = two links = two charges.
HTTP 402 for insufficient balance.
payment_urlis stable while the link is unexpired; once expired, the hosted page will reflect that status.
Examples (multi-language)
JavaScript (fetch)
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)
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 $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"];
Saylor