Payment Local

The Payment API (Local Network) lets your POS communicate directly with the terminal's IP address over your local network. No cloud relay is involved — the terminal processes the transaction using its EMV kernel and returns the result synchronously.

Beta — Early Access

Kushki ONE Local Network is currently in Beta for Peru 🇵🇪. Do not deploy to production without coordinating with the Kushki integration team.

Base URL

http://{terminalIp}:6868

Assign a static IP or DHCP reservation to the terminal via DMS. The port defaults to 6868 and is configurable in DMS.

Authentication

INFO

Omit Authorization on requests with no body (e.g. Abort).

Available operations

Operation	Endpoint	Description
Charge	`POST /terminal/v1/sync/charge`	One-step authorization + capture
Authorization	`POST /terminal/v1/sync/authorization`	Reserve funds, capture later
Capture	`POST /terminal/v1/sync/capture`	Collect reserved funds
Re-authorization	`POST /terminal/v1/sync/re_authorization`	Extend or increase a pre-auth
Post-tip	`POST /terminal/v1/sync/pos_tip`	Add tip to an authorized transaction
Void	`POST /terminal/v1/sync/void`	Cancel same-day transaction — cutoff: 20:59 local
Refund	`POST /terminal/v1/sync/refund`	Refund a settled transaction
Abort	`GET /terminal/v1/sync/abort`	Cancel a transaction in progress
Transaction Search (online)	`POST /terminal/v1/sync/transaction_search_online`	Query Kushki acquirer backend
Transaction Search (local)	`POST /terminal/v1/sync/transaction_search_local`	Query terminal storage — works offline

Request examples

Charge

{
  "amount": {
    "subtotal_iva0": 500,
    "subtotal_iva": 0,
    "iva": 0
  },
  "client_transaction_id": "ae6dd41a-9173-4ec7-8734-3178454ef341",
  "metadata": {
    "reference": "ORD-20260101-001",
    "customer_email": "user@example.com"
  }
}

Authorization (Pre-auth)

{
  "amount": {
    "subtotal_iva0": 500,
    "subtotal_iva": 0,
    "iva": 0
  },
  "client_transaction_id": "auth-20260101-001"
}

Capture

{
  "transaction_reference": "718fa526-6f41-405f-a1f5-a71db52dfdd2",
  "amount": {
    "subtotal_iva0": 500,
    "subtotal_iva": 0,
    "iva": 0
  }
}

INFO

Capture amount must be ≤ 110% of total authorized. Only one capture per authorization cycle.

Re-authorization

{
  "transaction_reference": "718fa526-6f41-405f-a1f5-a71db52dfdd2",
  "amount": {
    "subtotal_iva0": 600,
    "subtotal_iva": 0,
    "iva": 0
  }
}

Card type	Maximum hold
Debit	7 days
Credit	28 days

Post-tip

{
  "transaction_reference": "718fa526-6f41-405f-a1f5-a71db52dfdd2",
  "tip_amount": 50
}

Void

{
  "transaction_reference": "718fa526-6f41-405f-a1f5-a71db52dfdd2"
}

WARNING

Void cutoff in Peru: 20:59 local time. Wait at least 1 minute after the original transaction. Use Refund for settled transactions past the cutoff.

Refund

{
  "transaction_reference": "718fa526-6f41-405f-a1f5-a71db52dfdd2",
  "amount": {
    "subtotal_iva0": 500,
    "subtotal_iva": 0,
    "iva": 0
  }
}

Abort

GET /terminal/v1/sync/abort — no request body.

WARNING

Only call Abort while a transaction is active. Calling after completion has no effect.

Transaction Search

Local Network mode provides two search endpoints:

Endpoint	Source	Works offline
`transaction_search_online`	Kushki acquirer backend	❌
`transaction_search_local`	Terminal storage	✅

{
  "page": 1,
  "size": 10,
  "filters": {
    "last_four_digits": "5480",
    "start_date": 0,
    "end_date": 0,
    "transaction_reference": "",
    "transaction_type": ""
  }
}

Use transaction_search_local as an offline fallback or for same-day recovery when internet access is unavailable.

Key concepts

Save `transaction_reference`

Every approved charge or authorization response includes rawResponse.transaction_reference. Persist this value immediately — it is required for void, refund, capture, and re-authorization.

Amount object

The amount object does not include a currency field — currency is configured at the terminal level in DMS.

Field	Description
`subtotal_iva`	Net subtotal subject to IGV
`subtotal_iva0`	Subtotal exempt from IGV
`iva`	IGV amount (18% in Peru: `iva = subtotal_iva × 0.18`)
`tip`	Tip amount (charge only)
`extra_taxes`	Additional taxes: `airport_tax`, `iac`, `ice`, `travel_agency`

Idempotency

Every request must include a unique client_transaction_id (UUID v4). Reusing the same ID on a retry returns the original result without creating a duplicate.

Abort uses GET

In Local Network mode, Abort uses GET /terminal/v1/sync/abort (no body). In Cloud mode, it uses POST /sync/abort. This is the only operation that differs between modes.

Got a suggestion on this documentation? Contact us.

Base URL#

Authentication#

Available operations#

Request examples#

Charge#

Authorization (Pre-auth)#

Capture#

Re-authorization#

Post-tip#

Void#

Refund#

Abort#

Transaction Search#

Key concepts#

Save transaction_reference#

Amount object#

Idempotency#

Abort uses GET#

Base URL

Authentication

Available operations

Request examples

Charge

Authorization (Pre-auth)

Capture

Re-authorization

Post-tip

Void

Refund

Abort

Transaction Search

Key concepts

Save `transaction_reference`

Amount object

Idempotency

Abort uses GET