Payment Cloud

The Payment API (Cloud) lets your POS trigger card transactions on the terminal through Kushki's cloud relay. Your server calls cloudt.kushkipagos.com, Kushki routes the command to the terminal identified by its serial number, and the terminal returns the result synchronously.

Beta — Early Access

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

Base URL and endpoint pattern

Environment	Base URL
Production	`https://cloudt.kushkipagos.com`
UAT	`https://uat-cloudt.kushkipagos.com`

POST /terminal/v1/{terminalSerial}/sync/{operation}

Authentication

WARNING

timestamp must be in milliseconds (13 digits). A 10-digit seconds value will be rejected.

Available operations

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

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 the total authorized amount. 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

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 before voiding. 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
  }
}

Transaction Search

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

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.

Terminal blocking

The terminal blocks all input during card interaction. Do not send another payment command until the current operation returns a response.

Got a suggestion on this documentation? Contact us.

Base URL and endpoint pattern#

Authentication#

Available operations#

Request examples#

Charge#

Authorization (Pre-auth)#

Capture#

Re-authorization#

Void#

Refund#

Transaction Search#

Key concepts#

Save transaction_reference#

Amount object#

Idempotency#

Terminal blocking#

Base URL and endpoint pattern

Authentication

Available operations

Request examples

Charge

Authorization (Pre-auth)

Capture

Re-authorization

Void

Refund

Transaction Search

Key concepts

Save `transaction_reference`

Amount object

Idempotency

Terminal blocking