Process Payment

POST/pos/paymentOpen in the API playground →

Info

Main endpoint for processing purchases. POS routes use HMAC authentication, not bearer tokens.

Note

fee_amount reflects the effective fee resolved for the transaction. If your fee configuration charges the subscriber or the processor for POS payments, that configured value is returned here instead of always being 0.00.

Request

X-API-Key-IDstringheaderrequired

API key ID assigned to the POS integration

X-Timestampstringheaderrequired

RFC3339 timestamp used in the HMAC signature (example: 2026-03-10T12:00:00Z)

X-Signaturestringheaderrequired

Hex-encoded HMAC-SHA256 of METHOD + "\n" + PATH + "\n" + TIMESTAMP + "\n" + BODY

Body Parameters

card_serialstringbodyrequired

Card serial number read from NFC

merchant_idstringbodyrequired

Registered merchant identifier

merchant_namestringbody

Merchant display name shown on receipts; defaults to merchant_id when omitted

terminal_idstringbodyrequired

Terminal identifier

amountstringbodyrequired

Payment amount (e.g., 500.00)

currencystringbodyrequireddefault: SLE

Currency code

pinstringbodyrequired

Customer's 4-digit PIN

transaction_refstringbodyrequired

Merchant's unique transaction reference

processor_idstringbodyrequired

Processor account ID that receives the funds

---

Response

successboolean

Whether payment was approved

transaction_idstring

SmartPay transaction ID

approval_codestring

Approval code for the successful payment

amountstring

Formatted transaction amount

remaining_balancestring

Formatted remaining card balance

fee_amountstring

Formatted effective fee charged for the transaction based on the active POS fee configuration

---

Examples

Request

cURL

BODY='{"card_serial":"OLIV0001","merchant_id":"MERCH_XYZ","merchant_name":"Supermart Ltd","terminal_id":"TERM_001","amount":"1500.00","currency":"SLE","pin":"1234","transaction_ref":"ORDER-998877","processor_id":"proc-uuid-123"}'
TIMESTAMP='2026-03-10T12:00:00Z'
SIGNATURE=$(printf 'POST\n/api/v1/pos/payment\n%s\n%s' "$TIMESTAMP" "$BODY" | openssl dgst -sha256 -hmac "$SMARTPAY_HMAC_SECRET" -hex | sed 's/^.* //')

curl -X POST "https://demo.api.vultlocal.com/api/v1/pos/payment" \
  -H "X-API-Key-ID: $SMARTPAY_API_KEY_ID" \
  -H "X-Timestamp: $TIMESTAMP" \
  -H "X-Signature: $SIGNATURE" \
  -H "Content-Type: application/json" \
  -d "$BODY"

Response

200 Approved

{
  "success": true,
  "message": "Payment successful",
  "transaction_id": "txn_pos_12345",
  "approval_code": "882211",
  "amount": "1,500.00 SLE",
  "remaining_balance": "48,500.00 SLE",
  "fee_amount": "15.00 SLE"
}

400 Declined

{
  "success": false,
  "error": "Insufficient funds"
}

400 Invalid PIN

{
  "success": false,
  "error": "Invalid PIN"
}

---

Errors

Status	Code	Description
400	Validation or business error	Invalid payload, declined transaction, or bad PIN
401	HMAC auth error	Missing/invalid X-API-Key-ID, X-Timestamp, or X-Signature
500	Internal error	Server or downstream processor failure