Transfer In
Keep in mind!
Private-Merchant-Id). Never expose it in client-side or frontend code — always call the token endpoint from your backend.Payment flow
Get available banks
Call
GET /transfer/v1/bankList to retrieve the list of supported banks with their code and name. Display this list so the customer can select their bank.Request a Transfer In token
Call
POST /transfer/v1/tokens with the payment details. Returns a one-time token.{
"bankId": "1022",
"amount": {
"subtotalIva": 0,
"subtotalIva0": 150.00,
"iva": 0
},
"currency": "PEN",
"callbackUrl": "https://yoursite.com/payment/return",
"userType": "0",
"documentType": "DNI",
"documentNumber": "12345678",
"email": "user@example.com",
"paymentDescription": "Order #1234"
}⚠️ callbackUrlis required for Peru. The customer is redirected to this URL after completing (or abandoning) the payment.
Initiate the transaction
Call Response:
POST /transfer/v1/init with the token. The response returns a redirectUrl — send the customer there to complete the bank transfer.{
"token": "V0OzRB100000xhxQB8035251pHLBQsq5",
"amount": {
"subtotalIva": 0,
"subtotalIva0": 150.00,
"iva": 0,
"currency": "PEN"
},
"fullResponse": "v2"
}{
"redirectUrl": "https://api.kushkipagos.com/transfer/v1/agent?token=...",
"transactionReference": "28e6ac31-0af1-479a-9a6f-1a596bba6aea"
}Check the transaction status
After the customer returns via Check the
callbackUrl, call GET /transfer/v1/status/{token} to confirm the final status.status field in the response:| Value | Meaning |
|---|---|
approvedTransaction | Payment completed successfully |
declinedTransaction | Payment was rejected by the bank |
initializedTransaction | Payment is still pending |
expiredTransaction | Token or session expired without payment |
Currencies
| Currency | Code |
|---|---|
| Peruvian Sol | PEN |
| US Dollar | USD |
Document types
| Value | Description |
|---|---|
DNI | Documento Nacional de Identidad 🇵🇪 |
CE | Carné de Extranjería 🇵🇪 |
PAS | Pasaporte 🇵🇪 |
RUC | Registro Único de Contribuyentes 🇵🇪 |
User types
| Value | Description |
|---|---|
0 | Natural person |
1 | Company |
Token request fields
| Field | Required | Description |
|---|---|---|
bankId | No | Code of the destination bank. If omitted, the customer selects the bank at the bank portal. |
amount | Yes | Payment amount breakdown (subtotalIva, subtotalIva0, iva). |
currency | Yes | PEN or USD. |
callbackUrl | Yes | URL to redirect the customer after the payment. Required in Peru. |
documentType | No | Customer's document type. |
documentNumber | No | Customer's document number. Required if documentType is provided. |
email | No | Customer's email address. |
userType | No | 0 = natural person, 1 = company. |
paymentDescription | No | Free-text description shown to the customer at the bank portal. |
Init transaction fields
| Field | Required | Description |
|---|---|---|
token | Yes | Token returned by the token endpoint. |
amount | No | Amount breakdown including currency. Required if different from the token amount. |
expirationDate | No | Expiration date/time for the transaction. Only for Peru. |
webhooks | No | Array of URLs to notify when the transaction status changes. |
fullResponse | No | Pass "v2" to receive the complete transaction details in the response. |
metadata | No | Custom key-value pairs for your own tracking. |
Webhooks
webhooks array in your init request to receive real-time status notifications:{
"webhooks": ["https://yoursite.com/kushki/notify"]
}Authentication
Using the API
🟢 Production
🧪 Sandbox (UAT)
https://api.kushkipagos.com/Available Endpoints
Get Bank List
Returns the list of supported banks with their code and name. Display this to the customer before tokenizing.Request a Transfer In Token
Tokenize the transfer request. Returns a one-time token for a single transaction.Got a suggestion on this documentation? Contact us.
Modified at 2026-07-11 00:04:34