Overview

POS charge endpoints process card payments from activated terminals. All charge operations use HMAC signature authentication plus MSK-encrypted request/response bodies where noted below.

Endpoints

Method	Path	MSK request	MSK response	Description
POST	/pos/charge	✅	✅	Create a new payment
POST	/pos/charge/:chargeID/refund	✅	✅	Full or partial refund
POST	/pos/charge/:chargeID/cancel	—	✅	Void before settlement
POST	/pos/charge/:chargeID/reverse	—	✅	Same as cancel

Prerequisites

1. Device completed the POS activation flow (steps 1–8)
2. MSK installed and unwrapped from Keys
3. terminal_id known from decrypted Config response
4. HMAC signing key configured (X-Key-Id)

MSK envelope

Request and response bodies use the same envelope as Config and Activate:

{
  "format": "TR31-DATA",
  "ciphertext": "A1B2C3...",
  "initialization_vector": "000102030405060708090A0B0C0D0E0F",
  "mode": "CBC",
  "key_kcv": "ABCD12"
}

HMAC is computed over the raw envelope JSON in the HTTP body, not the plaintext charge object.

Full example

See End-to-End Example for a complete activation → charge walkthrough.