Payment operations run against the terminal's own HTTP server on your LAN. No relay, no terminalSerial: you address the device by IP.Kushki ONE Local Network is currently in Beta for México 🇲🇽. Do not deploy to production without coordinating with the Kushki integration team.
Pick a variant first#
Every operation ships twice, under two path prefixes. The choice is about where you receive the outcome, not about what the terminal does. | 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 | 10 | 7 |
Async exists because card-present flows wait on a human. If your POS can hold a request open for ~15 seconds and you control the thread, sync is simpler. If it cannot, async is the only safe option.Refund and both searches are sync-only. Abort, unlike in Cloud mode, exists in both.
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. It is your idempotency key — reuse it on retries |
transaction_reference | Required on capture, re-authorization, void and refund. Comes from rawResponse.transaction_reference of the original operation |
There is no currency field — the terminal's DMS configuration decides it.IVA#
Mexico's VAT rate is 16%. Split the amount into its taxed and exempt parts and state the tax explicitly — the terminal does not compute it for you:| 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 |
To charge 5.00netplusIVA—5.80 total — send it in cents:"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.
Tips and cashback#
| Endpoint | Tip | Cashback |
|---|
/sync/charge, /sync/authorization | Collected on the terminal screen when enabled in DMS | Not accepted |
/sync/pos_tip | amount.tip | cashback_amount |
/async/charge | amount.tip | cashback_amount |
/async/pos_tip | amount.tip | cashback_amount |
A field the DMS has disabled is ignored, not rejected — a 200 does not prove the tip was applied. Confirm against the amounts in the response or the final APPROVAL event.
Folders#
Sync
10 blocking operations. The result comes back in the HTTP response.
Async
7 non-blocking operations. The result arrives on your webhook.
Search
Two history queries: acquirer-side and on-device.
Got a suggestion on this documentation? Contact us.
