POST /v1/transaction
Record a completed payment against an existing payment link or update/trigger the SaylorPay Direct Interface. Typically called after the SaylorPay SMS-forwarder toolkit integration forwards the SMS to your server after the payer has sent the mobile-money transfer.
Base URL: https://saylorpay.com/api
Method: POST
Path: /v1/transaction
Cost: $0.02 USD flat fee per successful call (deducted from the merchant's balance)
Idempotent: No — a payment link can only be marked paid once. Subsequent calls with the same tracking_id return 409.
Authentication
| Header | Required | Value |
|---|---|---|
X-API-Key | Yes | Your merchant API key |
Content-Type | Yes | application/json |
Unverified merchants can call this endpoint (no verification gate).
Request body
| Field | Type | Required | Description |
|---|---|---|---|
tracking_id | string | Yes | The tracking_id of the payment link being paid. 32 lowercase hex chars. |
payment_method | string | No | "mobile_money" (default). "bitcoin" exists for internal/special-access use only and is not documented for general consumption. |
raw_data | object | Yes for mobile_money | The provider payload. See raw_data below. Pass-through for bitcoin. |
timestamp | string | No | ISO 8601 timestamp from the caller. Accepted and logged; not required. |
raw_data
For payment_method = "mobile_money", raw_data is the data forwarded from the SaylorPay SMS-forwarder toolkit.
| Key | Type | Required | Notes |
|---|---|---|---|
sender | string | Yes | E.g. "MobileMoney", "Telecel Cash", "ATMoney". |
message | string | Yes | The raw transaction SMS. Max 500 characters. |
received_time | string | No | Time the SMS was received. |
forwarded_time | string | No | Time the SMS was forwarded (e.g. date('Y-m-d H:i:s')). |
sim_slot | string/int | No | SIM slot the SMS arrived on. Defaults to "1" if omitted. |
Validation rules
tracking_id— required, must match^[a-f0-9]{32}$.payment_method— if provided, must be"mobile_money"or"bitcoin".raw_data— required object formobile_money; must contain non-emptysenderandmessage;message≤ 500 chars.Invalid JSON body →
400.
Example request
curl -X POST https://saylorpay.com/api/v1/transaction \ -H "X-API-Key: sk_live_9fK2mQx7Lp" \ -H "Content-Type: application/json" \ -d '{ "tracking_id": "9f2c1e4b7a8d4c6e9b0a1f3d5e7c2a4b", "payment_method": "mobile_money", "raw_data": { "sender": "MobileMoney", "message": "Payment received from JOHN DOE. Amount GHS 10.50. Reference INV2024AB12. Transaction ID 1234567890.", "received_time": "2026-10-30 12:34:56", "forwarded_time": "2026-10-30 12:35:02", "sim_slot": "1" }, "timestamp": "2026-10-30T12:35:02+00:00" }'
Success response — 201 Created
{ "success": true, "status": "transaction successful", "tracking_id": "9f2c1e4b7a8d4c6e9b0a1f3d5e7c2a4b", "invoice_amount": "10.50", "amount_paid": 10.5, "invoice_reference": "INV2024AB12", "reference_used_by_user": "INV2024AB12",
"timestamp": 1761837302, "fee_deducted": 0.02, "webhook_status": 200 }
| Field | Type | Description |
|---|---|---|
success | boolean | true |
status | string | Human-readable status ("transaction successful"). |
tracking_id | string | The payment link's tracking ID. |
invoice_amount | string | The payment link's amount, formatted to 2 decimals (string). |
amount_paid | number | Amount reported by the provider. |
invoice_reference | string | The reference supplied when the payment link was created. |
reference_used_by_user | string | The reference reported by the provider (from the telco SMS). |
timestamp | integer | Unix timestamp of the recording (server time). |
fee_deducted | number | 0.02 USD. |
webhook_status | integer | Only present if a webhook URL is configured. HTTP status returned by your webhook endpoint. |
Webhook
If your merchant account has a webhook URL configured, SaylorPay will POST a JSON body to it immediately after a successful transaction is recorded.
Headers:
| Header | Value |
|---|---|
Content-Type | application/json |
X-SaylorPay-Signature | v1=<hex_hmac_sha256> (only when a secret_key is configured for your account) |
Payload (same body as the API response, without webhook_status):
{ "success": true, "status": "transaction successful", "tracking_id": "9f2c1e4b7a8d4c6e9b0a1f3d5e7c2a4b", "invoice_amount": "10.50", "amount_paid": 10.5, "invoice_reference": "INV2024AB12", "reference_used_by_user": "INV2024AB12",
"timestamp": 1761837302, "fee_deducted": 0.02 }
Verifying the signature
The signature is an HMAC-SHA256 over the raw request body bytes, computed with your account's webhook secret (secret_key).
signature = hex( HMAC-SHA256( raw_body_bytes, secret_key ) )
Header format: X-SaylorPay-Signature: v1=<signature>.
Verification steps (recommended):
Read the raw request body bytes — do not re-serialize the JSON; key order and whitespace matter.
Strip the
v1=prefix from the header value.Compute
hash_hmac('sha256', $rawBody, $secret_key)(or the language equivalent).Compare using a constant-time comparison (
hash_equals,crypto.timingSafeEqual,hmac.compare_digest).Reject the webhook if the signature doesn't match.
Replay protection: reject webhooks whose
timestampis older than ~5 minutes.
PHP example:
$rawBody = file_get_contents('php://input'); $header = $_SERVER['HTTP_X_SAYLORPAY_SIGNATURE'] ?? ''; $secret = getenv('SAYLORPAY_WEBHOOK_SECRET'); $expected = 'v1=' . hash_hmac('sha256', $rawBody, $secret); if (!hash_equals($expected, $header)) { http_response_code(401); exit('bad signature'); } $event = json_decode($rawBody, true); if (time() - (int)$event['timestamp'] > 300) { http_response_code(400); exit('stale webhook'); } // process $event http_response_code(200);
Delivery is best-effort: the request has a 10-second timeout and is not retried. If your endpoint is down or slow, you'll see the failure in
webhook_statusin the API response, but the transaction is still recorded. Poll or use the API response as the source of truth if you need guaranteed delivery.
Error responses
All errors return {"error": "<message>"} unless noted.
| Status | Body | When |
|---|---|---|
400 | {"error":"tracking_id is required"} | Missing tracking_id |
400 | {"error":"Invalid tracking_id"} | Malformed tracking ID |
400 | {"error":"payment_method must be mobile_money"} | Unsupported payment method |
400 | {"error":"raw_data is required and must be an object"} | Missing raw_data for mobile_money |
400 | {"error":"raw_data.sender is required"} | Missing sender |
400 | {"error":"raw_data.message is required"} | Missing message |
400 | {"error":"raw_data.message must be at most 500 characters"} | Message too long |
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 for transaction fee","balance":<number>} | Balance below $0.02 |
404 | {"error":"Payment link not found"} | Tracking ID not found for this merchant |
409 | {"error":"Payment link already paid"} | Payment link is already marked paid |
500 | {"error":"<balance error>","balance":<number|null>} | Could not verify/deduct balance |
500 | {"error":"Failed to record transaction, but fee was refunded","amount_refunded":0.02} | Recording failed; fee refunded |
500 | {"error":"Critical: Failed to record transaction AND failed to refund fee","original_fee":0.02,"refund_error":"..."} | Recording and refund both failed — contact support |
Billing
$0.02 USD flat fee per successful call, deducted from the merchant's balance.
Failed recordings are refunded (
amount_refundedin the 500 response).If the payment link is
404(not yours / doesn't exist),409(already paid), or the body is invalid, no fee is charged — the fee is deducted only after validation passes.
Notes & gotchas
Ownership is enforced. A
tracking_idthat doesn't belong to the calling merchant returns404, same as a nonexistent one — this deliberately does not leak existence.Single-use. Once a payment link is
paid, further calls return409. This is your replay protection.webhook_statusappears in the API response only; the webhook payload itself never contains it.Webhook delivery is best-effort — 10-second timeout, no retries. The transaction is recorded regardless of webhook delivery success.
raw_datais forwarded from SaylorPay's SMS-forwarder toolkit.senderandmessageare required;message≤ 500 chars.sim_slotdefaults to"1"if omitted.amount_paidvsinvoice_amount—invoice_amountis what the payment link requested (string, 2 decimals);amount_paidis what the provider reported (number).HTTP 402 for insufficient balance.
Examples (multi-language)
JavaScript (fetch)
const res = await fetch("https://saylorpay.com/api/v1/transaction", { method: "POST", headers: { "X-API-Key": "sk_live_9fK2mQx7Lp", "Content-Type": "application/json" }, body: JSON.stringify({ tracking_id: "9f2c1e4b7a8d4c6e9b0a1f3d5e7c2a4b", payment_method: "mobile_money", raw_data: { sender: "MobileMoney", message: "Payment received from JOHN DOE. Amount GHS 10.50. Reference INV2024AB12. Transaction ID 1234567890.", received_time: "2026-10-30 12:34:56", forwarded_time: "2026-10-30 12:35:02", sim_slot: "1" }, timestamp: new Date().toISOString() }) }); const data = await res.json(); if (!res.ok) throw new Error(data.error); console.log(data);
Python (requests)
import requests resp = requests.post( "https://saylorpay.com/api/v1/transaction", headers={ "X-API-Key": "sk_live_9fK2mQx7Lp", "Content-Type": "application/json", }, json={ "tracking_id": "9f2c1e4b7a8d4c6e9b0a1f3d5e7c2a4b", "payment_method": "mobile_money", "raw_data": { "sender": "MobileMoney", "message": "Payment received from JOHN DOE. Amount GHS 10.50. Reference INV2024AB12. Transaction ID 1234567890.", "received_time": "2026-10-30 12:34:56", "forwarded_time": "2026-10-30 12:35:02", "sim_slot": "1", }, "timestamp": "2026-10-30T12:35:02+00:00", }, ) data = resp.json() if not resp.ok: raise Exception(data.get("error")) print(data)
PHP (cURL)
<?php $ch = curl_init("https://saylorpay.com/api/v1/transaction"); 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([ "tracking_id" => "9f2c1e4b7a8d4c6e9b0a1f3d5e7c2a4b", "payment_method" => "mobile_money", "raw_data" => [ "sender" => "MobileMoney", "message" => "Payment received from JOHN DOE. Amount GHS 10.50. Reference INV2024AB12. Transaction ID 1234567890.", "received_time" => "2026-10-30 12:34:56", "forwarded_time" => "2026-10-30 12:35:02", "sim_slot" => "1", ], "timestamp" => date("c"), ]), ]); $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"); } print_r($data);
Saylor