Process Payment - OLIVE Payment Platform

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"
}

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" + BODY

Body 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 omitted

string

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

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"

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.

POS Terminal

Verify Card

​Request

​Body Parameters

​Response

​Examples

​Errors

Authorizations

Body

Response

Request

Body Parameters

Response

Examples

Errors