Transfer out

Transfer Out lets you disburse funds programmatically — sending money directly to a recipient's bank account using your Kushki wallet balance. In Colombia 🇨🇴, two transfer modes are supported: ACH (standard bank account transfers) and Bre-B (instant payment key transfers).

Keep in mind!

Due to our risk policies, the available payment methods and the integration type may vary once you complete the affiliation. We will tell you how to proceed if this process applies to your merchant.

Transfer Modes

ACH (Bank account)

Bre-B (Payment key)

Standard bank transfers. Requires the recipient's bank account number (accountNumber), account type (CC or CA), and bankId. Use the Get Bank List endpoint to retrieve the available banks.

Payment Flow

A Transfer Out in Colombia consists of 4 sequential steps: bank list retrieval (ACH only), tokenization, initialization, and status confirmation.

Get the Bank List

Required for ACH transfers only. Call the Get Bank List endpoint using your Public Merchant ID to retrieve the list of available recipient banks.

Display the list to the operator and store the selected code — you will pass it as bankId in the token request.

For Bre-B transfers, this step is not required — there is no bankId field.

Two versions available:

Endpoint	Notes
Get Bank List v1	Basic bank list
Get Bank List v2	Enhanced bank list — recommended

Request a Transfer Out Token

Call the token endpoint using your Public Merchant ID. Include the recipient's details, the amount, and the transfer mode fields.

Token rules: Tokens expire in 30 minutes and are single-use. If the transaction fails or the token expires, request a new one.

Required fields for Colombia:

Field	ACH (CC/CA)	Bre-B (KI/KP/KE/KA/KM)
`accountType`	✅ Required	✅ Required
`accountNumber`	✅ Required	✅ Required
`totalAmount`	✅ Required	✅ Required
`currency`	✅ Required (`COP`)	✅ Required (`COP`)
`documentType`	✅ Required	Optional
`documentNumber`	✅ Required	Optional
`bankId`	✅ Required	Not required
`name`	✅ Required	Optional

Account types for Colombia:

Value	Mode	Description
`CC`	ACH	Cuenta Corriente
`CA`	ACH	Cuenta Ahorros
`KI`	Bre-B	National identification number
`KP`	Bre-B	Mobile phone number
`KE`	Bre-B	Email address
`KA`	Bre-B	Alphanumeric alias
`KM`	Bre-B	Merchant code

Document types accepted in Colombia:

Value	Document
`CC`	Cédula de Ciudadanía 🇨🇴
`NIT`	Número de Identificación Tributaria 🇨🇴
`CE`	Cédula de Extranjería 🇨🇴
`TI`	Tarjeta de Identidad 🇨🇴
`PP`	Passport 🇨🇴

Init Transaction

Using your Private Merchant ID, call the Init Transaction endpoint with the token from the previous step. Kushki validates the token and returns a ticketNumber along with the transaction status.

You can optionally include a webhooks object in this request to receive real-time notifications — see the Webhook Notifications section below.

Response fields:

Field	Description
`ticketNumber`	Unique transaction identifier. Use it for status queries and voids.
`status`	Initial transaction status
`details`	Transaction details, including `keyResolution` for Bre-B transfers
`keyResolution`	Bre-B only — resolved recipient info (owner name, bank, account type)

Get Transaction Status

Call the Get Status endpoint using the ticketNumber as a path parameter to confirm the final result.

Possible statuses:

Status	Meaning
`INITIALIZED`	Transaction created but not yet processed
`APPROVAL`	Transfer completed successfully
`DECLINED`	Transfer was rejected

A transaction in INITIALIZED status can be voided using the Void endpoint.

Webhook Notifications

Include the webhooks object in your Init Transaction request to receive real-time notifications:

{
  "webhooks": [
    {
      "events": ["approvedTransaction", "declinedTransaction"],
      "headers": [
        { "label": "Authorization", "value": "Bearer your-token" }
      ],
      "urls": [
        "https://merchant.example.com/webhooks/transfer-out"
      ]
    }
  ]
}

If you already have a Webhook configured in the Console, adding the webhooks object in the API request will trigger both channels simultaneously.

Wallet Balance

Before initiating disbursements, you can check your current Kushki wallet balance using the Balance for Payouts endpoint.

The response returns your currentBalance (in COP) and the balanceDate timestamp of the last update.

Authentication

Each step uses a different credential:

Step	Header	Key type
Get Bank List	`Public-Merchant-Id`	Public Key
Request a Token	`Public-Merchant-Id`	Public Key
Init Transaction	`Private-Merchant-Id`	Private Key
Get Status	`Private-Merchant-Id`	Private Key
Void	`Private-Merchant-Id`	Private Key
Balance for Payouts	`Private-Merchant-Id`	Private Key

Never expose your Private-Merchant-Id in client-side or frontend code. Token requests and bank list calls using the Public Key can be made from the frontend; all other calls must come from your backend.

Using the API

🟢 Production

🧪 Sandbox (UAT)

https://api.kushkipagos.com/

Available Endpoints

Get Bank List

Retrieve the list of available recipient banks. Required for ACH transfers. Use v2 for the best experience.

Get Bank List V2

Enhanced bank list endpoint. Recommended.

Request a Transfer Out Token

Tokenizes the recipient data and amount. Supports ACH and Bre-B modes. Token is valid for 30 minutes and single-use.

Init Transaction

Initiates the disbursement using the token. Returns a ticketNumber for status tracking.

Get Status

Retrieves the current status of a Transfer Out transaction using its ticketNumber.

Void a Transaction

Cancels an INITIALIZED transfer before it is processed.

Balance for Payouts

Returns the current available balance in your Kushki disbursement wallet.

Got a suggestion on this documentation? Contact us.

Transfer Modes#

Payment Flow#

Webhook Notifications#

Wallet Balance#

Authentication#

Using the API#

Available Endpoints#

Transfer Modes

Payment Flow

Webhook Notifications

Wallet Balance

Authentication

Using the API

Available Endpoints