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 "$OLIVE_HMAC_SECRET" -hex | sed 's/^.* //')
curl -X POST "https://demo.api.vultlocal.com/api/v1/pos/refund" \
-H "X-API-Key-ID: $OLIVE_API_KEY_ID" \
-H "X-Timestamp: $TIMESTAMP" \
-H "X-Signature: $SIGNATURE" \
-H "Content-Type: application/json" \
-d "$BODY"
{
"success": true,
"message": "Refund processed successfully",
"refund_transaction_id": "rfnd_abc789",
"amount": "1,500.00 SLE"
}
{
"success": false,
"error": "Transaction already fully refunded"
}
POS
Refund Payment
Refund a previous POS transaction
POST
/
pos
/
refund
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 "$OLIVE_HMAC_SECRET" -hex | sed 's/^.* //')
curl -X POST "https://demo.api.vultlocal.com/api/v1/pos/refund" \
-H "X-API-Key-ID: $OLIVE_API_KEY_ID" \
-H "X-Timestamp: $TIMESTAMP" \
-H "X-Signature: $SIGNATURE" \
-H "Content-Type: application/json" \
-d "$BODY"
{
"success": true,
"message": "Refund processed successfully",
"refund_transaction_id": "rfnd_abc789",
"amount": "1,500.00 SLE"
}
{
"success": false,
"error": "Transaction already fully refunded"
}
Refunds are submitted through the POS HMAC integration and reverse funds from the processor back to the subscriber.
Request
string
required
API key ID assigned to the POS integration
string
required
RFC3339 timestamp used in the HMAC signature
string
required
Hex-encoded HMAC-SHA256 of the request
Body Parameters
string
required
ID of transaction to refund
string
required
Amount to refund (can be partial)
string
required
Reason for refund
string
required
Admin/User ID authorizing refund
Response
boolean
Whether refund succeeded
string
Refund transaction ID
string
Formatted refunded amount
Examples
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 "$OLIVE_HMAC_SECRET" -hex | sed 's/^.* //')
curl -X POST "https://demo.api.vultlocal.com/api/v1/pos/refund" \
-H "X-API-Key-ID: $OLIVE_API_KEY_ID" \
-H "X-Timestamp: $TIMESTAMP" \
-H "X-Signature: $SIGNATURE" \
-H "Content-Type: application/json" \
-d "$BODY"
{
"success": true,
"message": "Refund processed successfully",
"refund_transaction_id": "rfnd_abc789",
"amount": "1,500.00 SLE"
}
{
"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 |
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Body
application/json
Refund details
Response
Refund processed
The response is of type object.
⌘I