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.

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 Ecuador consists of 4 sequential steps: tokenization, initialization, bank redirect, and status confirmation.

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, 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 Ecuador:

Field	Description
`amount`	Object with `subtotalIva`, `subtotalIva0`, and `iva`
`callbackUrl`	Redirect URL after bank confirmation
`userType`	`0` = Natural Person · `1` = Company
`documentType`	`CI`, `RUC`, or `PP` (see below)
`documentNumber`	Minimum 6 characters
`email`	Customer's email
`currency`	Always `USD` for Ecuador

Document types accepted in Ecuador:

Value	Document
`CI`	Cédula de Identidad 🇪🇨
`RUC`	Registro Único de Contribuyentes 🇪🇨
`PP`	Passport 🇪🇨

Note: bankId is not required in Ecuador. You do not need to call the Bank List endpoint for this country.

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 their bank's interface to authorize the transfer.

Response fields:

Field	Description
`redirectUrl`	Single-use URL to redirect the customer to their bank
`ticketNumber`	Kushki transaction identifier
`transactionReference`	Unique reference for this transaction
`details.status`	Initial status — always `initializedTransaction` at this point

Customer Completes Payment at the Bank

The customer is redirected to their bank's portal and authorizes (or declines) the transfer. This step happens entirely on the bank side — no action is required from your backend.

Once the customer finishes, the bank 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 Ecuador:

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

Note: expiredTransaction status is only applicable in Mexico — it does not apply to Ecuador.

Amount Object

The amount object is required in both the Token and Init Transaction steps. Use the following structure depending on whether the transaction has taxes:

With IVA taxes

Without taxes (IVA 0)

With extra taxes

{
  "amount": {
    "subtotalIva": 100.00,
    "subtotalIva0": 0,
    "iva": 12.00
  }
}

Set subtotalIva to the taxable base amount and iva to the tax value. Set subtotalIva0 to 0.

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"
      ]
    }
  ]
}

If you already have a Webhook configured in the Console, adding the webhooks object in the API request will trigger both channels. They are not mutually exclusive.

Authentication

Each step uses a different credential:

Step	Header	Key type
Request a Token	`Public-Merchant-Id`	Public Key (from Kushki Console → Credentials)
Init Transaction	`Private-Merchant-Id`	Private Key (from Kushki Console → Credentials)
Get Status	`Private-Merchant-Id`	Private Key

Never expose your Private-Merchant-Id in client-side or frontend code. Token requests 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

Request a Transfer In Token

Tokenizes the transaction data. Requires Public Merchant ID. Token is valid for 30 minutes and single-use.

Init Transaction

Initializes the transfer using the token. Returns a single-use redirectUrl to send the customer to their bank.

Get Status

Retrieves the final status of a transaction using the token as a path parameter.

Got a suggestion on this documentation? Contact us.

Payment Flow#

Amount Object#

Webhook Notifications#

Authentication#

Using the API#

Available Endpoints#

Payment Flow

Amount Object

Webhook Notifications

Authentication

Using the API

Available Endpoints