Transfer Out

Transfer Out lets you send funds from your Kushki wallet to a recipient's bank account. Use it for disbursements, supplier payments, refunds, or any payout flow where you need to push money out.

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.

Payment flow

Get the bank list

Call GET /payouts/transfer/v1/bankList (or v2 for extended metadata) to retrieve available destination banks. Use the code value as bankId in the token request.

Request a Transfer Out token

Call POST /payouts/transfer/v1/tokens with the recipient's account details and payment information. Returns a one-time token.

{
  "bankId": "002",
  "accountType": "CC",
  "accountNumber": "1234567890123",
  "currency": "PEN",
  "totalAmount": 500.00,
  "documentType": "DNI",
  "documentNumber": "12345678",
  "name": "Carlos Ramirez",
  "mail": "user@example.com",
  "paymentDescription": "Supplier payment #789"
}

Initiate the disbursement

Call POST /payouts/transfer/v1/init with the token. The response returns a ticketNumber and transactionReference.

{
  "token": "V0OzRB100000xhxQB8035251pHLBQsq5",
  "fullResponse": "v2"
}

Response:

{
  "status": "INITIALIZED",
  "ticketNumber": "1574298975417951",
  "transactionReference": "aef8884f-cd4d-4b9b-9efa-ad582629e4f2"
}

Check the transaction status

Call GET /payouts/transfer/v1/transaction/{ticketNumber} to verify the disbursement was processed.

Check the status field:

Value	Meaning
`INITIALIZED`	Transfer accepted and queued for processing
`APPROVAL`	Funds successfully sent to the recipient
`DECLINED`	Transfer rejected
`VOIDED`	Transfer cancelled before processing

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 🇵🇪

Account types

Peru supports the following bank account types for ACH transfers:

Value	Description
`CC`	Cuenta Corriente (checking account)
`CA`	Cuenta Ahorros (savings account)
`CM`	Cuenta maestra (master account — Peru only)

Account number format

Condition	Format
BCP (`bankId: "002"`) with `CC`	Exactly 13 digits
BCP (`bankId: "002"`) with `CA`	Exactly 14 digits
Any other bank	CCI (Código de Cuenta Interbancaria) — exactly 20 digits, no spaces, hyphens, or special characters

Token request fields

Field	Required	Description
`bankId`	Yes	Code of the destination bank from the bank list endpoint.
`accountType`	Yes	Bank account type: `CC`, `CA`, or `CM`.
`accountNumber`	Yes	Recipient's bank account number. See format rules above.
`currency`	Yes	`PEN` or `USD`.
`totalAmount`	Yes	Total amount to disburse.
`documentType`	Yes	Recipient's document type.
`documentNumber`	Yes	Recipient's document number.
`name`	Yes	Full name of the recipient. No special characters allowed in Peru.
`mail`	No	Recipient's email address.
`paymentDescription`	No	Description of the payment, shown on the bank statement.

Void a transfer

To cancel a Transfer Out transaction before it is processed, call:

DELETE /payouts/transfer/v1/transaction/{ticketNumber}

Pass the ticketNumber returned by the status endpoint. Voids are only possible while the transaction is in INITIALIZED status.

Check wallet balance

Before initiating a disbursement, verify that your Kushki wallet has sufficient funds:

GET /wallet/v1/merchant/balance

Response:

{
  "balanceDate": 1687371952224,
  "currency": "PEN",
  "currentBalance": 717169.22
}

Webhooks

Include a webhooks array in your init request to receive real-time status notifications:

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

Bank List v1 vs v2

Endpoint	Description
`GET /payouts/transfer/v1/bankList`	Returns bank `code` and `name`. Use for standard ACH transfers.
`GET /payouts/transfer/v2/bankList`	Extended response with `internationalCodes` and additional metadata.

Authentication

Using the API

🟢 Production

🧪 Sandbox (UAT)

https://api.kushkipagos.com/

Available Endpoints

Get Bank List

Returns the list of supported destination banks with code and name.

Get Bank List V2

Extended bank list with international codes and additional metadata.

Request a Transfer Out Token

Tokenize the disbursement with recipient account details. Returns a one-time token.

Init Transaction

Start the bank transfer disbursement. Returns a ticket number for tracking.

Get Status

Check the current status of a Transfer Out transaction by ticket number.

Void a Transaction

Cancel a Transfer Out transaction before it is processed.

Wallet Balance

Retrieve the current available balance in your Kushki payout wallet.

Got a suggestion on this documentation? Contact us.

Payment flow#

Currencies#

Document types#

Account types#

Account number format#

Token request fields#

Void a transfer#

Check wallet balance#

Webhooks#

Bank List v1 vs v2#

Authentication#

Using the API#

Available Endpoints#

Payment flow

Currencies

Document types

Account types

Account number format

Token request fields

Void a transfer

Check wallet balance

Webhooks

Bank List v1 vs v2

Authentication

Using the API

Available Endpoints