Transaction Examples

Beta — Early Access

Kushki ONE is currently in Beta for Peru 🇵🇪. Endpoints, parameters and response structures may change without prior notice. Do not deploy to production without coordinating with the Kushki integration team.

Practical, copy-ready request examples for every payment operation, in both topologies. If you are integrating for the first time, read Building the amount before anything else — it is where most integrations go wrong.

Base URL

Topology	Base URL
Local Network	`http://{terminalIp}:{port}/terminal/v1`
Cloud — Production	`https://cloudt.kushkipagos.com/terminal/v1/{terminalSerial}`
Cloud — UAT	`https://uat-cloudt.kushkipagos.com/terminal/v1/{terminalSerial}`

Every path below is shown relative to that base. The only structural difference between topologies is the {terminalSerial} segment in Cloud:

POST /terminal/v1/sync/charge                          ← Local
POST /terminal/v1/{terminalSerial}/sync/charge         ← Cloud

In Local Network mode the terminal exposes an HTTP server on its own IP. The defaults are 192.168.1.50 for terminalIp and 6868 for port, both configured in the Device Management System (DMS).

Required headers

Header	Value
`Content-Type`	`application/json`
`Authorization`	`Base64( HMAC-SHA256( rawBody, businessCode ) )`
`timestamp`	Unix timestamp in milliseconds

WARNING

Sign the exact bytes you send. Serialize once, sign that string, and send that same string — re-serializing between signing and sending changes key order or whitespace and invalidates the signature.

DANGER

The signing key is the Business-Code, not the private_credential_id. The latter is a terminal configuration field inside the DMS and is never used to sign requests — signing with it returns UNAUTHORIZED on every call.

Idempotency

Every request carries a client_transaction_id (UUID v4). On network failure, retry with the same UUID — the terminal deduplicates and will not charge twice.

Building the amount

All amount fields are integers in the smallest unit of PEN. No separators, no decimal point.

PEN has 2 decimals

The currency in Peru is PEN (Sol), which has two decimal places. The last two digits of the integer you send are always the fractional part. Amounts with no fraction still carry the trailing zeros:

To charge	Send
120.00 PEN	`12000`
100.00 PEN	`10000`
200.00 PEN	`20000`
256.00 PEN	`25600`

DANGER

Forgetting the trailing zeros charges a hundredth of the intended amount. To charge 120.00 PEN you send 12000, not 120.

INFO

The payload carries no currency field. The currency comes from the terminal's DMS configuration, not from the request. If your POS serves more than one market, read currency_code from the terminal configuration and resolve the decimal handling per terminal — the same integer means different money in different markets.

Converting safely

DANGER

Never use floating-point arithmetic. In most languages 12.44 * 100 == 1243.9999999999998, which truncates to 1243 — you undercharge by one cent and your reconciliation breaks. Use integers or a decimal type.

Two rules for the input:

Pass the value as a string, not a float — Decimal(12.44) inherits the binary rounding error you were trying to avoid.

Use a plain decimal string: . as the decimal point and no thousands separator. 100.00 PEN is written 100.00 here. Strip your UI's separators before calling — Decimal("100.00 PEN") raises.

Amount field roles

Field	Meaning
`subtotal_iva`	Portion of the sale subject to IGV
`iva`	IGV amount on that portion. The general rate in Peru is 18%
`subtotal_iva0`	Portion exempt from IGV. Use this alone when the sale has no tax breakdown
`extra_taxes.*`	Industry-specific taxes: `airport_tax`, `iac`, `ice`, `travel_agency`. Send `0` when not applicable
`tip`	Tip. Accepted on `pos_tip` and on `/async/charge`. Requires tipping enabled in DMS

The amount charged is the sum of all of them.

INFO

The field is named iva in the payload, but in Peru the tax it carries is the IGV (Impuesto General a las Ventas). The field name is fixed across all Kushki ONE markets; only the label and the rate change.

Charge

Single-step payment: authorization and capture in one operation. The standard flow for retail.

Sync — blocks until the acquirer answers

POST /sync/charge

{
  "amount": {
    "iva": 0,
    "subtotal_iva": 0,
    "subtotal_iva0": 12000,
    "extra_taxes": { "airport_tax": 0, "iac": 0, "ice": 0, "travel_agency": 0 }
  },
  "client_transaction_id": "c5a3f3be-9d6f-4d39-8af5-58dbb589af79",
  "metadata": {
    "reference": "ORD-20240317-001",
    "customer_email": "user@example.com",
    "device": "SUNMI-P3"
  }
}

Returns the full result. Save rawResponse.transaction_reference — you need it for void, capture, re_authorization, pos_tip and refund.

{
  "approved": true,
  "responseCode": "00",
  "authCode": "123456",
  "rawResponse": {
    "transaction_reference": "983a7480-6d97-41b2-9c3e-7f1a2b3c4d5e",
    "authorized_amount": 12000,
    "franchise": "VISA"
  }
}

Full reference: Charge — Local · Charge — Cloud.

Async — returns immediately

Use this when your architecture cannot hold a connection open for the duration of a card-present flow.

POST /async/charge

{
  "events_webhook_url": "https://api.negocio.pe/webhook/terminal-events",
  "amount": {
    "iva": 0,
    "subtotal_iva": 0,
    "subtotal_iva0": 12000,
    "extra_taxes": { "airport_tax": 0, "iac": 0, "ice": 0, "travel_agency": 0 }
  },
  "client_transaction_id": "c5a3f3be-9d6f-4d39-8af5-58dbb589af79"
}

The response is an acknowledgement, not a result:

{
  "event_id": "c08211a1-344c-4f1c-850b-41e33fb08cca",
  "previous_status": "",
  "occurred_at": "2026-08-03T20:53:34.859Z",
  "status": "TERMINAL_ACKNOWLEDGED",
  "client_transaction_id": "c5a3f3be-9d6f-4d39-8af5-58dbb589af79"
}

The outcome arrives at your events_webhook_url. See Webhooks for the event sequence and retry policy.

WARNING

Omitting events_webhook_url on an async call is valid, but then you have no way to learn the result — the transaction runs blind. Only do this if you plan to reconcile via Transaction Search.

Charge with tip, cashback or installments

All three are optional fields on the async charge. The terminal handles the cardholder prompts; it ignores any field whose capability is disabled in DMS.

POST /async/charge

{
  "events_webhook_url": "https://api.negocio.pe/webhook/terminal-events",
  "amount": {
    "iva": 0,
    "subtotal_iva": 0,
    "subtotal_iva0": 12000,
    "tip": 2000,
    "extra_taxes": { "airport_tax": 0, "iac": 0, "ice": 0, "travel_agency": 0 }
  },
  "cashback_amount": 0,
  "query_deferred": true,
  "client_transaction_id": "c5a3f3be-9d6f-4d39-8af5-58dbb589af79"
}

Field	Effect
`amount.tip`	Adds a tip to the total. `2000` = 20.00 PEN
`cashback_amount`	Cash withdrawal on top of the purchase. `0` for none
`query_deferred`	`true` prompts the cardholder to choose installments

WARNING

These three fields are accepted by /async/charge and by pos_tip — not by /sync/charge or authorization. If the matching capability is disabled in DMS the terminal returns a CONFIGURATION error: -4001 for tip, -4002 for cashback. See the Error Catalog.

Pre-authorization flow

Use this when the final amount is unknown at card-present time — hotels, fuel, open tabs.

Step 1 — Authorize

Reserves funds without capturing.

POST /sync/authorization

{
  "amount": {
    "iva": 0,
    "subtotal_iva": 0,
    "subtotal_iva0": 50000,
    "extra_taxes": { "airport_tax": 0, "iac": 0, "ice": 0, "travel_agency": 0 }
  },
  "client_transaction_id": "a1b2c3d4-0000-4000-8000-000000000001"
}

Save rawResponse.transaction_reference. Authorization validity:

Card type	Validity
Debit (Visa / Mastercard)	7 days
Credit (Visa / Mastercard)	28 days

Full reference: Pre-authorization — Local · Cloud.

Step 2 (optional) — Re-authorize

Extends the amount or the capture deadline. Send 0 to extend the date only. Set omit_card: true to skip card presentation.

POST /async/re_authorization

{
  "events_webhook_url": "https://api.negocio.pe/webhook/terminal-events",
  "amount": {
    "iva": 0,
    "subtotal_iva": 0,
    "subtotal_iva0": 15000,
    "extra_taxes": { "airport_tax": 0, "iac": 0, "ice": 0, "travel_agency": 0 }
  },
  "client_transaction_id": "a1b2c3d4-0000-4000-8000-000000000002",
  "transaction_reference": "983a7480-6d97-41b2-9c3e-7f1a2b3c4d5e",
  "omit_card": false
}

WARNING

A re-authorization can be canceled — but once canceled, no further re-authorizations are accepted on that transaction.

Step 3 — Capture

POST /sync/capture

{
  "amount": {
    "iva": 0,
    "subtotal_iva": 0,
    "subtotal_iva0": 65000,
    "extra_taxes": { "airport_tax": 0, "iac": 0, "ice": 0, "travel_agency": 0 }
  },
  "client_transaction_id": "a1b2c3d4-0000-4000-8000-000000000003",
  "transaction_reference": "983a7480-6d97-41b2-9c3e-7f1a2b3c4d5e"
}

Rules:

Maximum capture is 110% of the authorization plus all non-canceled re-authorizations.

One capture only per authorization cycle.

Post-tip

Adds a tip to an already-approved transaction — the classic restaurant flow where the tip is decided after the card is charged.

POST /sync/pos_tip

{
  "amount": {
    "iva": 0,
    "subtotal_iva": 0,
    "subtotal_iva0": 12000,
    "tip": 2000,
    "extra_taxes": { "airport_tax": 0, "iac": 0, "ice": 0, "travel_agency": 0 }
  },
  "client_transaction_id": "b2c3d4e5-0000-4000-8000-000000000001",
  "transaction_reference": "983a7480-6d97-41b2-9c3e-7f1a2b3c4d5e"
}

Full reference: Post-tip — Local · Cloud.

Void

Reverses an approved transaction on the same business day, before the processor cutoff.

POST /sync/void

{
  "amount": {
    "iva": 0,
    "subtotal_iva": 0,
    "subtotal_iva0": 12000,
    "extra_taxes": { "airport_tax": 0, "iac": 0, "ice": 0, "travel_agency": 0 }
  },
  "client_transaction_id": "c3d4e5f6-0000-4000-8000-000000000001",
  "transaction_reference": "983a7480-6d97-41b2-9c3e-7f1a2b3c4d5e"
}

INFO

Approximate cutoff in Peru: 20:59 local time (Lima). Confirm the exact cutoff with your Kushki integration team — after it passes the transaction has settled and must be reversed with refund instead. Wait at least 1 minute after the original transaction before calling void.

Abort

Cancels an in-flight operation while the terminal is still waiting for the cardholder.

Topology	Request
Local Network	`GET /sync/abort` — also available as `GET /async/abort`
Cloud	`POST /{terminalSerial}/sync/abort` — sync only

No request body in either topology. The signature is computed over an empty string.

DANGER

Abort only works before the transaction reaches the acquirer. Once the state machine hits APPROVAL_REQUESTED the operation can no longer be aborted and the call returns 409 — wait for APPROVAL or DECLINED, then reverse with void or refund.

Complete worked examples

Restaurant in Peru — tax breakdown and tip

Bill: food 200.00 PEN + IGV 18% (36.00 PEN) + tip 20.00 PEN = 256.00 PEN

Component	Value	Minor units
`subtotal_iva`	200.00 PEN	`20000`
`iva`	36.00 PEN	`3600`
`tip`	20.00 PEN	`2000`
Total charged	256.00 PEN	`25600`

{
  "events_webhook_url": "https://api.negocio.pe/webhook/terminal-events",
  "amount": {
    "iva": 3600,
    "subtotal_iva": 20000,
    "subtotal_iva0": 0,
    "tip": 2000,
    "extra_taxes": { "airport_tax": 0, "iac": 0, "ice": 0, "travel_agency": 0 }
  },
  "client_transaction_id": "7f8e9d0c-1111-4000-8000-aabbccddeeff",
  "metadata": { "reference": "MESA-14-T0042", "device": "SUNMI-P3" }
}

Retail in Peru — no tip

Sale: 100.00 PEN plus IGV 18% (18.00 PEN) = 118.00 PEN

Component	Value	Minor units
`subtotal_iva`	100.00 PEN	`10000`
`iva`	18.00 PEN	`1800`
Total charged	118.00 PEN	`11800`

{
  "amount": {
    "iva": 1800,
    "subtotal_iva": 10000,
    "subtotal_iva0": 0,
    "extra_taxes": { "airport_tax": 0, "iac": 0, "ice": 0, "travel_agency": 0 }
  },
  "client_transaction_id": "9a8b7c6d-2222-4000-8000-ffeeddccbbaa",
  "metadata": { "reference": "BOL-000198472", "device": "SUNMI-P2SE" }
}

Simple sale with no tax breakdown

When you do not itemize taxes, put the whole amount in subtotal_iva0:

{
  "amount": {
    "iva": 0,
    "subtotal_iva": 0,
    "subtotal_iva0": 11800,
    "extra_taxes": { "airport_tax": 0, "iac": 0, "ice": 0, "travel_agency": 0 }
  },
  "client_transaction_id": "1a2b3c4d-3333-4000-8000-112233445566"
}

That charges 118.00 PEN — the same total as the retail example above, without the breakdown.

Common mistakes

Mistake	Symptom	Fix
Sending a decimal number instead of minor units	Charge is wrong or request rejected	Convert to minor units first: 100.00 PEN is `10000`
Forgetting trailing zeros on whole amounts	Charging a hundredth of the amount	120.00 PEN is `12000`, not `120`
Sending the amount as a string with separators	Validation error	Strip all separators; send an integer, not a string
Using `float` for the conversion	Off-by-one-unit on some amounts	Use integer or decimal arithmetic
Reusing an amount echoed from a webhook	Wrong magnitude	Echoes are decimals (`12000.0`); requests are integers
Reusing a `client_transaction_id` across different sales	Second sale silently deduplicated	One fresh UUID v4 per sale; reuse only when retrying the same one
Re-serializing the body after signing	`401 UNAUTHORIZED`	Sign and send the identical byte string
Signing with `private_credential_id`	`UNAUTHORIZED` on every call	The signing key is the `Business-Code`
Treating the async response as the result	Sale marked approved when it was declined	The ack only means `TERMINAL_ACKNOWLEDGED`; wait for the webhook
Expecting card data in the webhook	Null fields in your records	The webhook carries no PAN or cardholder name — read it from the sync response or Transaction Search
Calling `void` after the 20:59 cutoff	Void rejected	Use `refund` instead

Webhooks

Event sequence, retry policy and how to build an idempotent consumer.

Error Catalog

Response codes and failure reasons, with the recommended action for each.

Got a suggestion on this documentation? Contact us.

Base URL#

Required headers#

Idempotency#

Building the amount#

PEN has 2 decimals#

Converting safely#

Amount field roles#

Charge#

Sync — blocks until the acquirer answers#

Async — returns immediately#

Charge with tip, cashback or installments#

Pre-authorization flow#

Step 1 — Authorize#

Step 2 (optional) — Re-authorize#

Step 3 — Capture#

Post-tip#

Void#

Abort#

Complete worked examples#

Restaurant in Peru — tax breakdown and tip#

Retail in Peru — no tip#

Simple sale with no tax breakdown#

Common mistakes#

Related#

Base URL

Required headers

Idempotency

Building the amount

PEN has 2 decimals

Converting safely

Amount field roles

Charge

Sync — blocks until the acquirer answers

Async — returns immediately

Charge with tip, cashback or installments

Pre-authorization flow

Step 1 — Authorize

Step 2 (optional) — Re-authorize

Step 3 — Capture

Post-tip

Void

Abort

Complete worked examples

Restaurant in Peru — tax breakdown and tip

Retail in Peru — no tip

Simple sale with no tax breakdown

Common mistakes

Related