Skip to main content
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"
}
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

​
X-API-Key-ID
string
required
API key ID assigned to the POS integration
​
X-Timestamp
string
required
RFC3339 timestamp used in the HMAC signature (example: 2026-03-10T12:00:00Z)
​
X-Signature
string
required
Hex-encoded HMAC-SHA256 of METHOD + "\n" + PATH + "\n" + TIMESTAMP + "\n" + BODY

​
Body Parameters

​
card_serial
string
required
Card serial number read from NFC
​
merchant_id
string
required
Registered merchant identifier
​
merchant_name
string
Merchant display name shown on receipts; defaults to merchant_id when omitted
​
terminal_id
string
required
Terminal identifier
​
amount
string
required
Payment amount (e.g., 500.00)
​
currency
string
default:"SLE"
required
Currency code
​
pin
string
required
Customer’s 4-digit PIN
​
transaction_ref
string
required
Merchant’s unique transaction reference
​
processor_id
string
required
Processor account ID that receives the funds

​
Response

​
success
boolean
Whether payment was approved
​
transaction_id
string
OLIVE transaction ID
​
approval_code
string
Approval code for the successful payment
​
amount
string
Formatted transaction amount
​
remaining_balance
string
Formatted remaining card balance
​
fee_amount
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"
}

​
Errors

StatusCodeDescription
400Validation or business errorInvalid payload, declined transaction, or bad PIN
401HMAC auth errorMissing/invalid X-API-Key-ID, X-Timestamp, or X-Signature
500Internal errorServer or downstream processor failure

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

POS payment details

​
amount
string
required

Accepts decimal format like "150.00" or "150"

Example:

"150.00"

​
card_serial
string
required

Supports any alphanumeric: CARD0001, 48290173K, etc.

Example:

"CARD0001"

​
currency
string
required
Example:

"SLE"

​
merchant_id
string
required
Example:

"MERCHANT001"

​
pin
string
required
Example:

"1234"

​
processor_id
string
required

Processor account that receives the funds

Example:

"proc-uuid-123"

​
transaction_ref
string
required
Example:

"APP-TXN-123"

​
merchant_name
string

Display name for receipts

Example:

"ABC Store"

​
metadata
object

Response

Payment approved

The response is of type object.