How To Confirm A Transaction Or Update The SaylorPay Direct Interface After Receiving Payment - API Docs

Article Image


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.

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

Unverified merchants can call this endpoint (no verification gate).


Request body

FieldTypeRequiredDescription
tracking_idstringYesThe tracking_id of the payment link being paid. 32 lowercase hex chars.
payment_methodstringNo"mobile_money" (default). "bitcoin" exists for internal/special-access use only and is not documented for general consumption.
raw_dataobjectYes for mobile_moneyThe provider payload. See raw_data below. Pass-through for bitcoin.
timestampstringNoISO 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.

KeyTypeRequiredNotes
senderstringYesE.g. "MobileMoney", "Telecel Cash", "ATMoney".
messagestringYesThe raw transaction SMS. Max 500 characters.
received_timestringNoTime the SMS was received.
forwarded_timestringNoTime the SMS was forwarded (e.g. date('Y-m-d H:i:s')).
sim_slotstring/intNoSIM slot the SMS arrived on. Defaults to "1" if omitted.

Validation rules


Example request

bash
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

json
{
  "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 }
FieldTypeDescription
successbooleantrue
statusstringHuman-readable status ("transaction successful").
tracking_idstringThe payment link's tracking ID.
invoice_amountstringThe payment link's amount, formatted to 2 decimals (string).
amount_paidnumberAmount reported by the provider.
invoice_referencestringThe reference supplied when the payment link was created.
reference_used_by_userstringThe reference reported by the provider (from the telco SMS).
timestampintegerUnix timestamp of the recording (server time).
fee_deductednumber0.02 USD.
webhook_statusintegerOnly 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:

HeaderValue
Content-Typeapplication/json
X-SaylorPay-Signaturev1=<hex_hmac_sha256> (only when a secret_key is configured for your account)

Payload (same body as the API response, without webhook_status):

json
{
  "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).

text
signature = hex( HMAC-SHA256( raw_body_bytes, secret_key ) )

Header format: X-SaylorPay-Signature: v1=<signature>.

Verification steps (recommended):

  1. Read the raw request body bytes — do not re-serialize the JSON; key order and whitespace matter.

  2. Strip the v1= prefix from the header value.

  3. Compute hash_hmac('sha256', $rawBody, $secret_key) (or the language equivalent).

  4. Compare using a constant-time comparison (hash_equals, crypto.timingSafeEqual, hmac.compare_digest).

  5. Reject the webhook if the signature doesn't match.

  6. Replay protection: reject webhooks whose timestamp is older than ~5 minutes.

PHP example:

php
$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_status in 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.

StatusBodyWhen
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


Notes & gotchas


Examples (multi-language)

JavaScript (fetch)

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

python
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
<?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);

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.