Skip to main content
POST
/
api
/
v1
/
pos
/
payment
curl -X POST "https://olive-gateway-a6ba.onrender.com/api/v1/pos/payment" \
  -H "Authorization: Bearer olive_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "card_serial": "OLIV0001",
    "merchant_id": "MERCH_XYZ",
    "processor_id": "TERM_001",
    "amount": "1500.00",
    "pin": "1234",
    "reference": "ORDER-998877"
  }'

{
  "success": true,
  "message": "Payment successful",
  "transaction_id": "txn_pos_12345",
  "authorization_code": "882211",
  "amount_deducted": "1,500.00 SLE",
  "balance_remaining": "48,500.00 SLE",
  "receipt_data": {
    "merchant_name": "Supermart Ltd",
    "terminal_id": "TERM_001",
    "card_masked": "OLIV****0001",
    "date": "2025-01-20T14:30:00Z"
  }
}
Main endpoint for processing purchases. Requires the card serial, verification of PIN, and merchant details.

​
Request

​
Authorization
string
required
Bearer olive_live_xxx (Merchant API Key)

​
Body Parameters

​
card_serial
string
required
Card serial number read from NFC
​
merchant_id
string
required
Registered Merchant ID
​
processor_id
string
required
Terminal/Processor ID
​
amount
string
required
Payment amount (e.g., 500.00)
​
currency
string
default:"SLE"
Currency code
​
pin
string
required
Customer’s 4-digit PIN
​
reference
string
Merchant’s unique reference ID
​
metadata
object
Optional key-value data (e.g., product list)

​
Response

​
success
boolean
Whether payment was approved
​
transaction_id
string
OLIVE transaction ID
​
authorization_code
string
6-digit auth code for receipt
​
receipt_data
object
Printable receipt details

​
Examples

curl -X POST "https://olive-gateway-a6ba.onrender.com/api/v1/pos/payment" \
  -H "Authorization: Bearer olive_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "card_serial": "OLIV0001",
    "merchant_id": "MERCH_XYZ",
    "processor_id": "TERM_001",
    "amount": "1500.00",
    "pin": "1234",
    "reference": "ORDER-998877"
  }'

{
  "success": true,
  "message": "Payment successful",
  "transaction_id": "txn_pos_12345",
  "authorization_code": "882211",
  "amount_deducted": "1,500.00 SLE",
  "balance_remaining": "48,500.00 SLE",
  "receipt_data": {
    "merchant_name": "Supermart Ltd",
    "terminal_id": "TERM_001",
    "card_masked": "OLIV****0001",
    "date": "2025-01-20T14:30:00Z"
  }
}

​
Errors

StatusCodeDescription
400INSUFFICIENT_FUNDSCard balance too low
400Expiredtransaction expired
401INVALID_PINIncorrect PIN entered
403CARD_BLOCKEDCard is blocked/stolen
403MERCHANT_INACTIVEMerchant account suspended
404CARD_NOT_FOUNDSerial number not recognized
500INTERNAL_ERRORServer/Processor error