Sync operations hold the HTTP connection open until the acquirer answers, then return the complete transaction result. Use them when your POS can wait on a request for up to 90 seconds.Kushki ONE Cloud is currently in Beta for Perú 🇵🇪. Do not deploy to production without coordinating with the Kushki integration team.
Operations#
| Operation | Endpoint | Use it for |
|---|
| Charge | POST /sync/charge | One-step authorization + capture. The common retail flow |
| Authorization (Pre-auth) | POST /sync/authorization | Reserve funds when the final amount is unknown — hotels, fuel, open tabs |
| Capture | POST /sync/capture | Collect funds reserved by a pre-auth |
| Re-authorization | POST /sync/re_authorization | Extend the validity or increase the reserved amount |
| Post-tip | POST /sync/pos_tip | Add gratuity to an already-authorized transaction |
| Void | POST /sync/void | Cancel a same-day transaction before the processor cutoff |
| Refund | POST /sync/refund | Reverse a settled transaction, days later. Partial refunds supported |
| Abort | POST /sync/abort | Cancel a transaction currently in progress on the terminal |
The two-step flow#
Pre-authorization is the only operation that opens a cycle. The rest close or adjust it.authorization ──→ re_authorization (0..n) ──→ capture ──→ refund
│ │
└──────────────→ void ←───────────────────┘
| Rule | Detail |
|---|
| Pre-auth validity | Debit 7 days, credit 28 days. Visa and Mastercard only |
| Capture ceiling | ≤ 110% of the authorization plus all non-canceled re-authorizations |
| Captures per cycle | Exactly one |
| Re-authorization | Send subtotal_iva0: 0 to extend validity only; send an amount to increase the reserve |
| Void window | Same business day, cutoff around 23:59 local. Wait at least 1 minute after the original transaction |
Every operation after the first needs the transaction_reference returned in rawResponse.transaction_reference. Store it.
Abort is not void#
abort cancels an operation the cardholder is still interacting with. It only works while the transaction is active — once the terminal reaches APPROVAL_REQUESTED the transaction is with the acquirer and abort returns 409. From that point you must wait for the outcome and reverse it with void or refund.
Errors#
All operations share one error model. Read type to classify the source, then look up code:type | Where it broke |
|---|
PARAMETER | Your request. param names the offending field |
AUTH | Signature or timestamp |
CONFIGURATION | Terminal or merchant setup in the DMS |
ACQUIRER | The acquirer rejected it |
TERMINAL-SUNMI | The device itself |
INTERNAL | Kushki or the relay |
Got a suggestion on this documentation? Contact us.
