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 "$OLIVE_HMAC_SECRET" -hex | sed 's/^.* //')
curl -X POST "https://demo.api.vultlocal.com/api/v1/pos/payment" \
-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": "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"
}
{
"success": false,
"error": "Insufficient funds"
}
{
"success": false,
"error": "Invalid PIN"
}
POS
Process Payment
Process an NFC card payment at a POS terminal
POST
/
pos
/
payment
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 "$OLIVE_HMAC_SECRET" -hex | sed 's/^.* //')
curl -X POST "https://demo.api.vultlocal.com/api/v1/pos/payment" \
-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": "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"
}
{
"success": false,
"error": "Insufficient funds"
}
{
"success": false,
"error": "Invalid PIN"
}
Main endpoint for processing purchases. POS routes use HMAC authentication, not bearer tokens.
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
string
required
API key ID assigned to the POS integration
string
required
RFC3339 timestamp used in the HMAC signature (example:
2026-03-10T12:00:00Z)string
required
Hex-encoded HMAC-SHA256 of
METHOD + "\n" + PATH + "\n" + TIMESTAMP + "\n" + BODYBody Parameters
string
required
Card serial number read from NFC
string
required
Registered merchant identifier
string
Merchant display name shown on receipts; defaults to
merchant_id when omittedstring
required
Terminal identifier
string
required
Payment amount (e.g.,
500.00)string
default:"SLE"
required
Currency code
string
required
Customer’s 4-digit PIN
string
required
Merchant’s unique transaction reference
string
required
Processor account ID that receives the funds
Response
boolean
Whether payment was approved
string
OLIVE transaction ID
string
Approval code for the successful payment
string
Formatted transaction amount
string
Formatted remaining card balance
string
Formatted effective fee charged for the transaction based on the active POS fee configuration
Examples
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 "$OLIVE_HMAC_SECRET" -hex | sed 's/^.* //')
curl -X POST "https://demo.api.vultlocal.com/api/v1/pos/payment" \
-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": "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"
}
{
"success": false,
"error": "Insufficient funds"
}
{
"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 |
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Body
application/json
POS payment details
Accepts decimal format like "150.00" or "150"
Example:
"150.00"
Supports any alphanumeric: CARD0001, 48290173K, etc.
Example:
"CARD0001"
Example:
"SLE"
Example:
"MERCHANT001"
Processor account that receives the funds
Example:
"proc-uuid-123"
Example:
"APP-TXN-123"
Display name for receipts
Example:
"ABC Store"
Response
Payment approved
The response is of type object.
⌘I