Cash In

Cash In lets your customers pay in cash at a physical payment network location (e.g., Payvalida). Kushki generates a PIN code that the customer presents at the collection point. Once paid, you receive a webhook notification and can confirm the status via the Transaction Status endpoint.

Keep in mind!

Token generation requires your Private Key (Private-Merchant-Id). Never expose it in client-side or frontend code — always call the token endpoint from your backend.

How it works

Request a Cash In token

Call POST /cash/v1/tokens with the customer's personal details and the total amount. Kushki returns a single-use token that expires in 30 minutes.

{
  "name": "Carlos",
  "lastName": "Ramirez",
  "identification": "12345678",
  "documentType": "DNI",
  "email": "user@example.com",
  "totalAmount": 500,
  "currency": "PEN",
  "description": "Order #1234"
}

Response:

{
  "token": "b209ff69ae02be9bc0e58dee225fd8f5"
}

Initialize the transaction

Call POST /cash/v1/charges/init with the token and the amount breakdown. Kushki returns a PIN that the customer uses to pay at the collection point, plus a receipt URL.

{
  "token": "b209ff69ae02be9bc0e58dee225fd8f5",
  "amount": {
    "currency": "PEN",
    "subtotalIva": 0,
    "subtotalIva0": 500,
    "iva": 0,
    "ice": 0
  },
  "expirationDate": "2026-06-10 00:00:00",
  "fullResponse": "v2"
}

Response:

{
  "pin": "7929926379",
  "ticketNumber": "193222411482",
  "transactionReference": "fa3cb92f-f53f-46e8-a9f9-0c40e9ae2df2",
  "pdfUrl": "https://api.kushkipagos.com/cash/v1/charges/193222411482/receipt"
}

Share the pin and pdfUrl (receipt) with your customer. The PIN is valid until expirationDate (default 7 days; maximum 15 days in Peru).

Customer pays at the collection point

The customer visits a participating payment network location and pays using the PIN. No action needed on your end — Kushki notifies you via webhook when payment is confirmed.

Verify the transaction status

Call GET /cash/v1/status/{ticketNumber} to confirm the final status of the transaction.

{
  "ticketNumber": "2347529752172881",
  "status": "approvedTransaction",
  "totalAmount": 500,
  "currency": "PEN",
  "merchantName": "Mi Comercio Perú",
  "name": "Carlos",
  "lastName": "Ramirez",
  "documentType": "DNI",
  "identification": "12345678",
  "pin": "7929926379"
}

Token request fields

Field	Required	Description
`name`	Yes	Customer's first name.
`lastName`	Yes	Customer's last name.
`identification`	Yes	Customer's document number.
`documentType`	Yes	`DNI`, `CE`, `PAS`, or `RUC`.
`totalAmount`	Yes	Total amount to collect.
`currency`	Yes	`PEN` or `USD`.
`email`	No	Customer's email address.
`description`	No	Payment description.

Init transaction fields

Field	Required	Description
`token`	Yes	One-time token from the token endpoint.
`amount`	Yes	Amount object — see Amount breakdown.
`expirationDate`	No	PIN expiry date in `YYYY-MM-DD HH:mm:ss` (UTC). Must be at least one day after creation. Default: 7 days; max 15 days in Peru.
`webhooks`	No	Array of URLs to notify when the customer pays.
`fullResponse`	No	Pass `"v2"` for full transaction details in the response.
`metadata`	No	Custom key-value pairs for your own tracking.

Amount breakdown

{
  "currency": "PEN",
  "subtotalIva": 0,
  "subtotalIva0": 500,
  "iva": 0,
  "ice": 0
}

Field	Required	Description
`currency`	Yes	`PEN` or `USD`.
`subtotalIva`	Yes	Subtotal subject to VAT. Set to `0` if no taxes apply.
`subtotalIva0`	Yes	Subtotal not subject to VAT (tax-exempt amount).
`iva`	Yes	VAT amount. Set to `0` if no taxes apply.
`ice`	Yes	ICE (Impuesto a Consumos Especiales). Set to `0` if not applicable.

Document types

Value	Description
`DNI`	Documento Nacional de Identidad 🇵🇪
`CE`	Carné de Extranjería 🇵🇪
`PAS`	Pasaporte 🇵🇪
`RUC`	Registro Único de Contribuyentes 🇵🇪

Webhooks

Include a webhooks array in your init request to receive a notification when the customer completes payment:

{
  "webhooks": ["https://yoursite.com/kushki/notify"]
}

Sandbox testing

Use the following identification values to simulate different transaction outcomes:

`identification`	Simulated outcome
Any valid value	Successful transaction
`9999999999`	Initialized (pending payment)
`1000000000`	Declined transaction

Authentication

Using the API

🟢 Production

🧪 Sandbox (UAT)

https://api.kushkipagos.com/

Available Endpoints

Request Cash In Token

Generate a one-time token with the customer's details and total amount. Token expires in 30 minutes.

Initialize Transaction

Start the cash transaction. Returns the PIN for the customer to pay at the collection point and a receipt PDF URL.

Get Transaction Status

Check the current status of a cash transaction by ticket number.

Got a suggestion on this documentation? Contact us.

How it works#

Token request fields#

Init transaction fields#

Amount breakdown#

Document types#

Webhooks#

Sandbox testing#

Authentication#

Using the API#

Available Endpoints#

How it works

Token request fields

Init transaction fields

Amount breakdown

Document types

Webhooks

Sandbox testing

Authentication

Using the API

Available Endpoints