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 Local Network is currently in Beta for Perú 🇵🇪. 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 (Async)	`GET /async/abort`

Refund and both transaction searches 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.pe/webhook/terminal-events",
  "amount": { "subtotal_iva0": 10000, "subtotal_iva": 0, "iva": 0 },
  "client_transaction_id": "c5a3f3be-9d6f-4d39-8af5-58dbb589af79"
}

The webhook is delivered by Kushki, not by the terminal's local HTTP server, so the URL must be reachable from the internet — a 192.168.x.x address will never receive anything.

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 Local Network Services.

Fields only async accepts

Each is gated by a DMS capability — when it is disabled the terminal ignores the field instead of rejecting the request.

Field	Endpoint	Effect
`amount.tip`	`/async/charge`, `/async/pos_tip`	Tip amount. Send `0` when not applicable
`cashback_amount`	`/async/charge`, `/async/pos_tip`	Cash withdrawal. Send `0` for none
`query_deferred`	`/async/charge`	Prompts the cardholder for installments (cuotas)
`omit_card`	`/async/re_authorization`	Skips card presentation

Aborting an async transaction

GET /async/abort cancels whatever the terminal is currently doing. It has no body and no client_transaction_id: the terminal only ever runs one transaction at a time, so there is nothing to disambiguate. You will see the cancellation as a TERMINAL_CANCELED event on the webhook of the transaction it interrupted.

Once the transaction reaches APPROVAL_REQUESTED it is with the acquirer and abort returns 409.

Got a suggestion on this documentation? Contact us.

Operations#

Wiring the webhook#

Fields only async accepts#

Aborting an async transaction#

Operations

Wiring the webhook

Fields only async accepts

Aborting an async transaction