Async

Async operations return as soon as the terminal accepts the payment intent, without waiting for the cardholder or the acquirer. Every state change — including the final approval or decline — arrives as a POST to the webhook URL you supply.

Beta — Early Access

Kushki ONE Cloud is currently in Beta for Colombia 🇨🇴. Do not deploy to production without coordinating with the Kushki integration team.

DANGER

The 200 you get back is an acknowledgement, not a result. It carries status: TERMINAL_ACKNOWLEDGED and confirms only that the terminal took the request. Never treat it as an approved payment.

Operations

Operation	Endpoint
Charge (Async)	`POST /async/charge`
Authorization — Pre-auth (Async)	`POST /async/authorization`
Capture (Async)	`POST /async/capture`
Re-authorization (Async)	`POST /async/re_authorization`
Post-tip (Async)	`POST /async/pos_tip`
Void (Async)	`POST /async/void`

Abort and transaction search have no async variant — use the Sync folder.

Wiring the webhook

Add events_webhook_url to the request body. Without it the transaction still executes, but you never learn how it ended.

{
  "events_webhook_url": "https://api.negocio.co/webhook/terminal-events",
  "amount": { "subtotal_iva0": 10000, "subtotal_iva": 0, "iva": 0 },
  "client_transaction_id": "c5a3f3be-9d6f-4d39-8af5-58dbb589af79"
}

Your endpoint must answer any 2xx. Kushki retries on timeouts and on 408, 429, 500, 502, 503 and 504, with exponential backoff, and gives up after 10 attempts or 15 minutes. A 4xx other than 408/429 is treated as a permanent rejection and is never retried.

Do this	Why
Deduplicate by `event_id`	The terminal replays queued events after a network outage
Correlate by `client_transaction_id`	It is the only field shared by every event of one transaction
Watch `previous_status`	Gaps in the chain mean a delivery was lost
Deserialize casing as-is	Top level is `snake_case`; inside `terminal` and `operation` it is `camelCase`

Full envelope and the seven-state lifecycle: see Cloud Services.

Fields only async accepts

These four exist because async is where the terminal drives the interaction. Each depends on a capability enabled for your terminal — when it is disabled the terminal ignores the field instead of rejecting the request.

Field	Endpoint	Effect
`amount.tip`	`/async/charge`	Tip amount. Send `0` when not applicable
`cashback_amount`	`/async/charge`	Cash withdrawal. Send `0` for none
`deferred.months`	`/async/charge`	Number of installments the cardholder will pay. `query_deferred` is Mexico only — do not send it from Colombia
`omit_card`	`/async/capture`, `/async/re_authorization`, `/async/void`	Runs the operation without asking for the card again

INFO

Ignoring a field silently is deliberate, but it means a 200 does not prove the tip or cashback was applied. Confirm against the amounts in the final APPROVAL event.

Got a suggestion on this documentation? Contact us.

Operations#

Wiring the webhook#

Fields only async accepts#

Operations

Wiring the webhook

Fields only async accepts