CASH-IN

Cash In lets your customers pay with cash at thousands of physical locations across Colombia — no bank account or card required. The customer receives a PIN (payment reference number) that they present at any participating payment point to complete the transaction.

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 Cash In payment consists of 3 steps: tokenization, initialization (PIN delivery), and confirmation.

Request a Cash In Token

Your backend calls the token endpoint using your Public Merchant ID, passing the customer's identification data and the payment 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`	Customer's first name
`lastName`	Customer's last name
`identification`	Customer's document number
`documentType`	See document types below
`totalAmount`	Total amount to charge
`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. Kushki validates the token and returns:

A PIN (pin) — the reference number the customer presents at the payment point.

A PDF receipt URL (pdfUrl) — printable receipt to give the customer.

An agreementDetails object listing all available payment points and their agreement numbers.

A ticketNumber to track the transaction.

Optional fields:

Field	Description
`expirationDate`	Custom PIN expiry date (`YYYY-MM-DD HH:mm:ss`, UTC). Must be at least 1 day after creation. Defaults to 7 days.
`amount`	Breakdown with `subtotalIva`, `subtotalIva0`, `iva`, and optional `extraTaxes`
`webhooks`	Real-time notification configuration
`fullResponse`	Set to `"v2"` to receive the full `details` object in the response
`metadata`	Custom key-value pairs for your internal use

Payment points available in Colombia:

The agreementDetails object in the response lists the active payment networks. Typical Colombia networks include:

Network	Processor
Baloto	BancoBogota
Carulla	BancoBogota
Efecty	Payvalida
Bancolombia	Payvalida

Customer Pays at a Payment Point

Share the PIN and the receipt with your customer. They go to any participating payment point and present the PIN to complete the cash payment.

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

Get Transaction Status

Call the Transaction Status endpoint with the ticketNumber to confirm whether the payment was completed.

Possible statuses:

Status	Meaning
`initializedTransaction`	PIN generated — awaiting payment at the counter
`approvedTransaction`	Cash payment received and confirmed
`expiredTransaction`	PIN expired without payment

Amount Object

The amount object is optional in the Init Transaction request. If omitted, the amount from the token request is used.

With IVA taxes

Without taxes (IVA 0)

With extra taxes

{
  "amount": {
    "subtotalIva": 42017,
    "subtotalIva0": 0,
    "iva": 7983
  }
}

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

Webhook Notifications

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

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

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

Sandbox Testing

In the UAT environment, you can simulate the full Cash In flow using specific identification numbers:

Scenario	`identification` value
✅ Successful transaction	Any valid number
⏳ Initialized (pending)	`9999999999`
❌ Declined transaction	`1000000000`

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 In Token

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

Init Transaction

Initializes the cash payment and returns the PIN, PDF receipt URL, and available payment points.

Transaction Status

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

Update a Transaction

Updates the amount of an existing Cash In transaction before the customer pays.

Delete a Transaction

Cancels a Cash In transaction and invalidates the PIN.

Got a suggestion on this documentation? Contact us.

Payment Flow#

Amount Object#

Webhook Notifications#

Sandbox Testing#

Authentication#

Using the API#

Available Endpoints#

Payment Flow

Amount Object

Webhook Notifications

Sandbox Testing

Authentication

Using the API

Available Endpoints