Payment
terminalSerial: you address the device by IP.Beta — Early Access
Pick a variant first
| Sync | Async | |
|---|---|---|
| Prefix | /sync/ | /async/ |
| HTTP response | The full transaction result | A TERMINAL_ACKNOWLEDGED acknowledgement |
| Blocks? | Yes, until the acquirer answers | No |
| Outcome arrives | In the response | On your events_webhook_url |
| Operations | 7 | 7 |
GET, which changes how you authenticate it: the encrypted value travels as the data query parameter, and the signed payload is the literal {}.Request shape
{
"amount": {
"subtotal_iva0": 10000,
"subtotal_iva": 0,
"iva": 0
},
"client_transaction_id": "c5a3f3be-9d6f-4d39-8af5-58dbb589af79"
}| Element | Rule |
|---|---|
amount | Integers only, in cents. MXN has two decimals, so 10000 is 100.00 MXN |
client_transaction_id | UUID v4, new for every operation. It is your idempotency key — reuse it only when retrying that same operation |
transaction_reference | Required on capture, re-authorization and void. Comes from rawResponse.transaction_reference of the original operation |
WARNING
client_transaction_id and transaction_reference are not interchangeable. The first identifies this call; the second points at the transaction you are acting on. Passing the original transaction's id as client_transaction_id breaks idempotency.currency field — the terminal resolves the currency from its own configuration, and the integration team confirms which one your terminal uses during onboarding.{"data":"<iv_hex>:<cipher_hex>"}. The payloads shown here and on the endpoint pages are the plaintext you encrypt.IVA
| Field | What goes in it |
|---|---|
subtotal_iva | Net amount subject to IVA |
subtotal_iva0 | Amount exempt from IVA |
iva | The IVA itself: subtotal_iva × 0.16 |
"amount": { "subtotal_iva": 500, "iva": 80, "subtotal_iva0": 0 }subtotal_iva0 and leaves the other two at 0. Either way the three fields are required.Optional fields, by operation
| Field | Applies to |
|---|---|
amount.tip | /charge and /authorization — the tip can be set at pre-authorization time, not only when charging |
cashback_amount | /charge |
query_deferred | /charge — Meses Sin Intereses |
omit_card | /capture, /re_authorization and /void |
metadata | /charge, /authorization and /pos_tip. Subfields: reference, customer_email, device |
/pos_tip, amount.tip is not an optional field — it is the amount of the operation. And cashback does not travel on /pos_tip: cashback_amount belongs to /charge only.omit_card decides whether the terminal asks the cardholder for the card. With true the operation runs without it — which is what makes the hotel case work: extending or capturing a pre-authorization after the guest has left the desk.query_deferred: true and the terminal offers Meses Sin Intereses (MSI) to the cardholder after reading the card. Your POS does not choose the number of months. The deferred object used in Chile, Colombia and Peru does not apply here and must not be sent; the two fields are mutually exclusive.DANGER
200, whatever happened — so a 200 proves neither that the operation succeeded nor that an optional field was applied. Always evaluate the response body, and confirm a tip or a cashback against the amounts it returns or the final APPROVAL event.INFO
/charge has been exercised end-to-end with these fields, in sync and async. amount.tip on /authorization and omit_card on its six combinations are defined but not yet exercised.Reversing a transaction
/void, in both variants. What the operation becomes depends on when you call it: within the same calendar day as the original transaction it is a cancellation; from midnight onwards it enters the refund cycle and takes business days. Wait at least 1 minute after the original transaction before reversing it.VOID, REFUND or REVERSE — the last of these being one the platform generates on its own when communication with the terminal fails, and which your POS may find without ever having requested it.Searching history
_online queries the Kushki acquirer and needs internet, _local reads what the terminal stored and works offline — and they do not return the same shape: no shared envelope, casing or field names. Write one parser per endpoint. The full comparison is in Local Network Services.Folders
Got a suggestion on this documentation? Contact us.
Modified at 2026-09-09 14:28:51