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. COP has no decimals — 10000 is $ 10.000 |
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.19 |
"amount": { "subtotal_iva": 50000, "iva": 9500, "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 |
deferred | /charge — installments |
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.deferred object — {"deferred": {"months": 24}}. Your POS sends the number of months, up to 48; Colombia does not use credit_type, which exists only in Chile. query_deferred is Mexico only and must not be sent from Colombia; 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:29:20