Refund Payment

POST/pos/refundOpen in the API playground →

Warning

Refunds are submitted through the POS HMAC integration and reverse funds from the processor back to the subscriber.

Request

X-API-Key-IDstringheaderrequired

API key ID assigned to the POS integration

X-Timestampstringheaderrequired

RFC3339 timestamp used in the HMAC signature

X-Signaturestringheaderrequired

Hex-encoded HMAC-SHA256 of the request

Body Parameters

original_transaction_idstringbodyrequired

ID of transaction to refund

amountstringbodyrequired

Amount to refund (can be partial)

reasonstringbodyrequired

Reason for refund

initiated_bystringbodyrequired

Admin/User ID authorizing refund

---

Response

successboolean

Whether refund succeeded

refund_transaction_idstring

Refund transaction ID

amountstring

Formatted refunded amount

---

Examples

Request

cURL

BODY='{"original_transaction_id":"txn_pos_12345","amount":"1500.00","reason":"Customer returned item","initiated_by":"admin_user_01"}'
TIMESTAMP='2026-03-10T12:00:00Z'
SIGNATURE=$(printf 'POST\n/api/v1/pos/refund\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/refund" \
  -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 Success

{
  "success": true,
  "message": "Refund processed successfully",
  "refund_transaction_id": "rfnd_abc789",
  "amount": "1,500.00 SLE"
}

400 Already Refunded

{
  "success": false,
  "error": "Transaction already fully refunded"
}

---

Errors

Status	Code	Description
400	Validation or business error	Invalid amount or refund not allowed
401	HMAC auth error	Missing/invalid X-API-Key-ID, X-Timestamp, or X-Signature
500	Internal error	Server error