Transfer in

If your users do not have a credit card or prefer to use the available balance in their bank accounts to make an online purchase, wire transfer is the ideal payment option.

Transfer In allows your customers to pay directly from their bank account through a secure bank redirect flow — no card required. In Colombia 🇨🇴, transfers are processed through PSE (Pagos Seguros en Línea).

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.

Payment Flow

A Transfer In payment in Colombia consists of 5 sequential steps: bank list retrieval, tokenization, initialization, bank redirect, and status confirmation.

Get the Bank List

Before requesting a token, your backend must call the Get Bank List endpoint using your Public Merchant ID to retrieve the available PSE banks.

⚠️ This step is required in Colombia. Unlike other countries, you must always call this endpoint and present the list to your customer so they can select their bank before proceeding.

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

Request a Transfer In Token

Your backend calls the token endpoint using your Public Merchant ID. You must include the transaction amount, the customer's document data, the selected bankId, and a callbackUrl — the URL where the customer will land after completing the payment on the bank side.

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

Required fields for Colombia:

Field	Description
`bankId`	Bank code selected by the customer from the Bank List. Required in Colombia.
`amount`	Object with `subtotalIva`, `subtotalIva0`, and `iva`
`callbackUrl`	Redirect URL after bank confirmation
`userType`	`0` = Natural Person · `1` = Company
`documentType`	`CC`, `NIT`, `CE`, `TI`, or `PP` (see below)
`documentNumber`	Customer's document number
`email`	Customer's email
`currency`	Always `COP` for Colombia

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 obtained in the previous step. Kushki validates the token and returns a redirectUrl.

The redirectUrl is single use — redirect your customer to this URL immediately after receiving it. The customer will be taken to PSE's interface to authorize the transfer with their bank.

Response fields for Colombia:

Field	Description
`redirectUrl`	Single-use URL to redirect the customer to PSE
`trazabilityCode`	Also called CUS — unique PSE payment reference code assigned by PSE.
`bankId`	Code of the bank selected for the transaction
`bankName`	Name of the bank selected for the transaction
`transactionReference`	Unique reference for this transaction

Customer Completes Payment at PSE

The customer is redirected to PSE and then to their bank's portal, where they authorize (or decline) the transfer. This step happens entirely on the PSE/bank side — no action is required from your backend.

Once the customer finishes, PSE redirects them back to your callbackUrl.

Get Transaction Status

After the customer lands on your callbackUrl, call the Get Status endpoint using the original token as a path parameter to confirm the final transaction result.

Possible statuses in Colombia:

Status	Meaning
`initializedTransaction`	Transaction was created but not yet completed
`approvedTransaction`	Transfer authorized — funds are on their way
`declinedTransaction`	Transfer was rejected

The response also includes the trazabilityCode (CUS) which you can use to reconcile the transaction with PSE records.

Amount Object

The amount object is required in the Token request. Use the following structure depending on whether the transaction has taxes:

With IVA taxes

Without taxes (IVA 0)

With extra taxes

{
  "amount": {
    "subtotalIva": 100000,
    "subtotalIva0": 0,
    "iva": 10000
  }
}

Set subtotalIva to the taxable base amount and iva to the tax value. Set subtotalIva0 to 0. All amounts in COP.

Webhook Notifications

You can receive real-time transaction notifications by including the webhooks object in your Init Transaction request. This is independent of any webhooks configured in the Kushki Console — both channels will fire simultaneously.

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

Payment Flow#

Amount Object#

Webhook Notifications#

Payment Flow

Amount Object

Webhook Notifications