Sync operations hold the HTTP connection open until the acquirer answers, then return the complete transaction result.Kushki ONE Local Network 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 and restaurant 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 |
| Abort | GET /sync/abort | Cancel a transaction currently in progress on the terminal |
Transaction search lives in the Search folder.
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 | Any number of times before capture. subtotal_iva0: 0 extends validity only |
| Void window | Same business day, cutoff around 20: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 a GET, and it is not a void#
Two things differ from what you might expect:It is a GET with no request body — in Cloud mode the same operation is a POST. Since there is no body to sign, the Authorization header is computed over an empty string.
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 there 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-side failure |
A connection error rather than an HTTP status usually means the terminal is asleep, off the network, or listening on a different port than the DMS says.
Got a suggestion on this documentation? Contact us.
