Cash-out

Cash Out lets you send money that recipients collect in cash at thousands of physical locations across Colombia — no bank account needed. The recipient receives a PIN they present at any participating payment point to collect the funds.

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.

Pre-funded wallet required

Cash Out transactions are charged against your Kushki disbursement wallet balance. Make sure your wallet has sufficient funds before initiating a Cash Out.

Payment Flow

A Cash Out disbursement consists of 3 steps: tokenization, initialization (PIN delivery), and confirmation.

Request a Cash Out Token

Your backend calls the token endpoint using your Public Merchant ID, passing the recipient's identification data and the disbursement amount.

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

Required fields:

Field	Description
`name`	Recipient's first name
`lastName`	Recipient's last name
`documentNumber`	Recipient's document number
`totalAmount`	Amount to disburse
`currency`	Always `COP` for Colombia

Optional fields:

Field	Description
`documentType`	`CC`, `NIT`, `CE`, `TI`, or `PP` (defaults to `CC`)
`email`	Recipient's email address
`phoneNumber`	Recipient's phone number (e.g. `+573912345678`)
`description`	Internal payment description

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 and the amount object. Kushki validates the token, deducts the balance from your wallet, and returns:

A PIN (pin) — the cash pickup code to share with the recipient.

A PDF receipt URL (pdfUrl) — printable receipt.

A ticketNumber to track and manage the disbursement.

Required fields:

Field	Description
`token`	Token from the previous step
`amount`	Object with `subtotalIva`, `subtotalIva0`, `iva`, and `currency`

Optional fields:

Field	Description
`expirationDate`	PIN expiry date (`YYYY-MM-DD HH:mm:ss`, UTC). If omitted, expires after 7 days.
`metadata`	Custom key-value pairs for your internal records
`webhooks`	Real-time notification configuration

Recipient Collects Cash

Share the PIN with the recipient. They go to any participating payment point, present their ID and the PIN, and collect the cash.

This step happens entirely on the recipient's side — no backend action is required.

Get Transaction Status

Call the Transaction Status endpoint using the ticketNumber to confirm whether the cash was collected.

Possible statuses:

Status	Meaning
`initializedTransaction`	PIN generated — awaiting cash collection
`approvedTransaction`	Cash collected by recipient
`expiredTransaction`	PIN expired without collection

Amount Object

The amount object is required in the Init Transaction request.

Without taxes (IVA 0)

With IVA taxes

{
  "amount": {
    "subtotalIva": 0,
    "subtotalIva0": 50000,
    "iva": 0,
    "currency": "COP"
  }
}

Set the full amount in subtotalIva0. All amounts in COP.

Webhook Notifications

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

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

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

Managing Disbursements

After a Cash Out is initialized, you can modify or cancel it while it is still in initializedTransaction status:

Action	When to use
Update	Adjust the disbursement amount before the recipient collects the cash
Delete	Cancel the disbursement and return the funds to your wallet

Once the recipient collects the cash (approvedTransaction), the transaction can no longer be updated or deleted.

Authentication

Step	Header	Key type
Request a Token	`Public-Merchant-Id`	Public Key (from Kushki Console → Credentials)
Init Transaction	`Private-Merchant-Id`	Private Key
Get Status	`Private-Merchant-Id`	Private Key
Update Transaction	`Private-Merchant-Id`	Private Key
Delete Transaction	`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 Cash Out Token

Tokenizes the recipient's data and disbursement amount. Requires Public Merchant ID. Token is valid for 30 minutes and single-use.

Init Transaction

Initializes the cash disbursement and returns the PIN and PDF receipt. Deducts the amount from your wallet balance.

Transaction Status

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

Update a Transaction

Updates the disbursement amount of an initialized Cash Out transaction.

Delete a Transaction

Cancels a Cash Out transaction and returns the funds to your wallet.

Got a suggestion on this documentation? Contact us.

Payment Flow#

Amount Object#

Webhook Notifications#

Managing Disbursements#

Authentication#

Using the API#

Available Endpoints#

Payment Flow

Amount Object

Webhook Notifications

Managing Disbursements

Authentication

Using the API

Available Endpoints