Skip to main content

POS Terminal

Info

The POS API enables Smart PAY terminals to accept payments using SmartPay NFC cards. It provides endpoints for card verification, payment processing, and refunds.

Warning

POS endpoints do not use Authorization: Bearer .... They require HMAC headers: X-API-Key-ID, X-Timestamp, and X-Signature.

Features​

Card Verification

Instantly verify card status and balance before purchase

NFC Payments

Process secure offline-first or online NFC transactions

Smart Routing

Route transactions to correct subscriber wallet

Refunds

Process full or partial refunds directly from terminal

Endpoints​

Process Payment

POST /api/v1/pos/payment

Execute a payment transaction

Verify Card

POST /api/v1/pos/verify-card

Check card validity, holder name, and balance

Refund

POST /api/v1/pos/refund

Refund a transaction

Lookup Card

POST /api/v1/pos/lookup-card

Get card details (Admin/Support)

Payment Flow​

Tap Card

Customer taps NFC card on Smart PAY terminal

Verify

Terminal calls verify-card to check status and prompt for PIN

Authorize

Customer enters PIN on terminal

Process

Terminal calls payment with encrypted PIN and amount

Receipt

Transaction approved, terminal prints receipt

Security​

  • HMAC auth: Every POS request must include X-API-Key-ID, X-Timestamp, and X-Signature.
  • Signature input: Sign METHOD + "\n" + PATH + "\n" + TIMESTAMP + "\n" + BODY using the integration's HMAC secret.
  • Merchant ID: Include the registered merchant identifier in payment requests.
  • Processor ID: Include the processor account ID that receives POS funds.

Integration Status​

Online

Real-time processing

Offline

Store and forward (coming soon)

Sandbox

Test environment available