Colombia - PayIn (v2)

If you still call POST /api/v1/payin, that endpoint is deprecated. Use POST /api/v2/payin for all new integrations.

The PayIn v2 API (POST /api/v2/payin) creates deposit transactions and returns the experience that matches each payment_method. You choose the flow with the fields you send — no separate B2B configuration is required.

Quick Reference

Parameter	Value	Description
Endpoint	`POST /api/v2/payin`	Initiate PayIn transaction
Currency	`COP`	Colombian Peso
Country Code	`CO`	Colombia
Auth	Token-Top + Basic Auth	Required

Payment experiences

Each method resolves to one of three execution modes:

Mode	What you get	When to use
Checkout	`payment_url` — TumiPay hosted page	Default when you only need a link to redirect the customer
Direct	`payment_information` — provider data in the API response	When you render the payment UI yourself (e.g. PSE bank redirect URL)
Hybrid	`payment_url` and `payment_information`	Cash/reference methods where you show instructions immediately and keep a hosted fallback

Methods in Colombia

`payment_method`	Default mode	`payment_url`	`payment_information`
`ALL_METHODS`	Checkout	✅	—
`CARD`	Checkout	✅	—
`PSE`	Checkout	✅	—
`PSE` + `bank` + `person_type`	Direct	—	✅ (`payment_url` = PSE redirect)
`EFECTY`	Hybrid	✅	✅ (`reference`, `convenio`)
`BREB`	Hybrid	✅	✅ (`key_value`)
`BREB_QR`	Hybrid	✅	✅ (`qr_code`)

Request parameters

Required fields

Field	Type	Description
`reference`	string	Unique id from your system
`amount`	number	Amount in COP
`currency`	string	`"COP"`
`country`	string	`"CO"`
`payment_method`	string	See table above
`description`	string	Transaction description
`customer_data`	object	Customer identity and contact

Customer data

Field	Type	Required	Description
`legal_doc`	string	✅	Document number
`legal_doc_type`	string	✅	`CC`, `CE`, `PPN`, `NIT`
`phone_code`	string	✅	`"57"`
`phone_number`	string	✅	Mobile number
`email`	string	✅	Customer email
`full_name`	string	✅	Full name

PSE-only fields (direct experience)

Send both fields inside customer_data to receive the PSE redirect URL in payment_information instead of the generic checkout link:

Field	Type	Description
`customer_data.bank`	string	Bank code from `GET /api/v1/pse/banks`
`customer_data.person_type`	string	`NATURAL` or `JURIDICA`

Optional fields

Field	Type	Description
`ipn_url`	string	Webhook URL for status updates
`redirect_url`	string	Return URL after payment
`expiration_time`	integer	Link validity in minutes (default `720`)

EFECTY minimum amount: 10,000 COP.

Response structure

Every successful PayIn returns the same envelope. The fields inside data depend on the execution mode (Checkout, Direct, or Hybrid).

All timestamps are in UTC. Both data.date (transaction creation) and payment_information.expiration_date (when present) use the format YYYY-MM-DD HH:MM:SS in UTC. Convert to the customer’s local timezone in your UI if needed.

Envelope (always present)

Field	Type	Description
`code`	string	`"01"` on success
`status`	string	`"SUCCESS"`
`message`	string	Human-readable result (e.g. `"Operacion exitosa"`)
`data`	object	Transaction payload (see below)

`data` object — common fields

Field	Type	Always	Description
`ticket`	string	✅	TumiPay transaction ID. Use it to query status or build support tickets.
`date`	string	✅	Transaction creation time in UTC (`Y-m-d H:i:s`).
`transaction`	object	✅	Echo of your request: `reference`, `amount`, `currency`, `payment_method`, `redirect_url`, `ipn_url`, `description`.
`payment_url`	string	Checkout / Hybrid	Hosted page URL. Redirect the customer here when you do not render payment UI yourself.
`payment_information`	object	Direct / Hybrid	Provider instructions (PSE redirect URL, cash reference, Bre-B key, QR, CLABE, etc.). Omitted entirely in Checkout mode — the field is not returned.

Checkout (hosted only)

Use when you only need a link. Response includes ticket, date, payment_url, and transaction. payment_information is not included. Applies to: ALL_METHODS, CARD, PSE (without bank + person_type).

{
  "code": "01",
  "status": "SUCCESS",
  "message": "Operacion exitosa",
  "data": {
    "ticket": "dAF1RNdSFn936Yi",
    "date": "2025-10-15 15:44:57",
    "payment_url": "https://link.staging.topup.com.co/payments/main?s=dAF1RNdSFn936Yi",
    "transaction": {
      "reference": "your-reference",
      "amount": 50000,
      "currency": "COP",
      "payment_method": "PSE",
      "redirect_url": "https://your-domain.com/ok",
      "ipn_url": "https://your-domain.com/webhook",
      "description": "Test PayIn"
    }
  }
}

Direct (your UI)

Use when you render the payment step yourself. Response includes ticket, date, payment_information, and transaction. No payment_url. Applies to: PSE with customer_data.bank + customer_data.person_type.

Hybrid (hosted + instructions)

Use for cash, keys, QR, or transfer methods. Response includes both payment_url and payment_information. Show instructions immediately in your app and keep the hosted page as fallback. Applies to: EFECTY, BREB, BREB_QR.

Examples by payment method

Each example below shows the data block for that method. All timestamps are UTC.

PSE — Checkout (hosted bank selection)

Mode: Checkout · You get: payment_url only (no payment_information). Omit bank and person_type. Redirect the customer to data.payment_url (path payments/main).

curl --request POST 'https://api-empresas.staging.topup.com.co/production/api/v2/payin' \
--header 'Token-Top: your_auth_token' \
--header 'Authorization: Basic your_auth_key' \
--header 'Content-Type: application/json' \
--data-raw '{
  "reference": "pse-checkout-001",
  "amount": 50000,
  "currency": "COP",
  "country": "CO",
  "payment_method": "PSE",
  "description": "PSE checkout",
  "customer_data": {
    "legal_doc": "1045689877",
    "legal_doc_type": "CC",
    "phone_code": "57",
    "phone_number": "3121234567",
    "email": "customer@example.com",
    "full_name": "John Doe"
  },
  "ipn_url": "https://your-domain.com/webhook",
  "redirect_url": "https://your-domain.com/payment/ok"
}'

{
  "code": "01",
  "status": "SUCCESS",
  "message": "Operacion exitosa",
  "data": {
    "ticket": "abc123",
    "date": "2025-10-15 15:44:57",
    "payment_url": "https://link.staging.topup.com.co/payments/main?s=abc123",
    "transaction": {
      "reference": "pse-checkout-001",
      "amount": 50000,
      "currency": "COP",
      "payment_method": "PSE"
    }
  }
}

PSE — Direct (your UI, PSE redirect URL)

Mode: Direct · You get: payment_information only (no payment_url). Include bank and person_type in customer_data. Use GET /api/v1/pse/banks for bank codes. Open payment_information.payment_url in the browser or WebView — it is the PSE redirect URL, not the TumiPay hosted page.

curl --request POST 'https://api-empresas.staging.topup.com.co/production/api/v2/payin' \
--header 'Token-Top: your_auth_token' \
--header 'Authorization: Basic your_auth_key' \
--header 'Content-Type: application/json' \
--data-raw '{
  "reference": "pse-direct-001",
  "amount": 50000,
  "currency": "COP",
  "country": "CO",
  "payment_method": "PSE",
  "description": "PSE direct",
  "customer_data": {
    "person_type": "NATURAL",
    "bank": "1007",
    "legal_doc": "1045689877",
    "legal_doc_type": "CC",
    "phone_code": "57",
    "phone_number": "3121234567",
    "email": "customer@example.com",
    "full_name": "John Doe"
  },
  "ipn_url": "https://your-domain.com/webhook",
  "redirect_url": "https://your-domain.com/payment/ok"
}'

{
  "code": "01",
  "status": "SUCCESS",
  "message": "Operacion exitosa",
  "data": {
    "ticket": "abc123",
    "date": "2025-10-15 15:44:57",
    "payment_information": {
      "payment_url": "https://registro.pse.com.co/PSENF/index.html?enc=..."
    },
    "transaction": {
      "reference": "pse-direct-001",
      "amount": 50000,
      "currency": "COP",
      "payment_method": "PSE"
    }
  }
}

EFECTY — Hybrid

Mode: Hybrid · You get: payment_url + payment_information. Minimum amount 10,000 COP. Hosted page: efecty-confirmation. Show reference and convenio so the customer can pay at an Efecty location. expiration_date is in UTC (default 720 minutes unless expiration_time is sent).

{
  "code": "01",
  "status": "SUCCESS",
  "message": "Operacion exitosa",
  "data": {
    "ticket": "dAF1RNdSFn936Yi",
    "date": "2025-10-15 15:44:57",
    "payment_url": "https://link.staging.topup.com.co/efecty-confirmation?s=dAF1RNdSFn936Yi",
    "payment_information": {
      "reference": "9876543210",
      "convenio": "12345",
      "expiration_date": "2025-10-16 03:44:57"
    },
    "transaction": {
      "reference": "efecty-ref-001",
      "amount": 50000,
      "currency": "COP",
      "payment_method": "EFECTY",
      "redirect_url": "https://your-domain.com/payment/ok",
      "ipn_url": "https://your-domain.com/webhook",
      "description": "Efecty cash payment"
    }
  }
}

`payment_information` field	Description
`reference`	Payment reference the customer presents at Efecty
`convenio`	Efecty agreement code
`expiration_date`	UTC expiration (`Y-m-d H:i:s`)

`payment_information` field	Description
`reference`	Payment reference the customer presents at Efecty
`convenio`	Efecty agreement code
`expiration_date`	Payment deadline in UTC (`Y-m-d H:i:s`)

BREB — Hybrid

Mode: Hybrid · You get: payment_url + payment_information. Use payment_method: "BREB". Hosted page: breb-payment. Display key_value so the customer can send the transfer from their bank app. Default validity: 15 minutes (expiration_time overrides). expiration_date is in UTC.

{
  "code": "01",
  "status": "SUCCESS",
  "message": "Operacion exitosa",
  "data": {
    "ticket": "breb-ticket-id",
    "date": "2025-10-15 15:44:57",
    "payment_url": "https://link.staging.topup.com.co/breb-payment?s=breb-ticket-id",
    "payment_information": {
      "key_value": "@TUMI1234567890123",
      "expiration_date": "2025-10-15 16:00:00"
    },
    "transaction": {
      "reference": "breb-ref-001",
      "amount": 50000,
      "currency": "COP",
      "payment_method": "BREB",
      "redirect_url": "https://your-domain.com/payment/ok",
      "ipn_url": "https://your-domain.com/webhook",
      "description": "Bre-B key payment"
    }
  }
}

`payment_information` field	Description
`key_value`	Bre-B key (e.g. `@TUMI…`) the customer uses to pay
`expiration_date`	Key validity end in UTC (`Y-m-d H:i:s`)

BREB_QR — Hybrid

Mode: Hybrid · You get: payment_url + payment_information. Use payment_method: "BREB_QR". Hosted page: breb-qr-payment. Render qr_code (base64 image) in your UI or redirect to payment_url. Default validity: 15 minutes. expiration_date is in UTC.

{
  "code": "01",
  "status": "SUCCESS",
  "message": "Operacion exitosa",
  "data": {
    "ticket": "breb-qr-ticket-id",
    "date": "2025-10-15 15:44:57",
    "payment_url": "https://link.staging.topup.com.co/breb-qr-payment?s=breb-qr-ticket-id",
    "payment_information": {
      "qr_code": "iVBORw0KGgoAAAANSUhEUgAA...",
      "expiration_date": "2025-10-15 16:00:00"
    },
    "transaction": {
      "reference": "breb-qr-ref-001",
      "amount": 50000,
      "currency": "COP",
      "payment_method": "BREB_QR",
      "redirect_url": "https://your-domain.com/payment/ok",
      "ipn_url": "https://your-domain.com/webhook",
      "description": "Bre-B QR payment"
    }
  }
}

`payment_information` field	Description
`qr_code`	QR image payload (base64) for display or scanning
`expiration_date`	QR validity end in UTC (`Y-m-d H:i:s`)

ALL_METHODS — Checkout

Mode: Checkout · You get: payment_url only (no payment_information). Customer chooses the payment method on the TumiPay hosted page (payments/main).

{
  "code": "01",
  "status": "SUCCESS",
  "message": "Operacion exitosa",
  "data": {
    "ticket": "ticket-all-methods",
    "date": "2025-10-15 15:44:57",
    "payment_url": "https://link.staging.topup.com.co/payments/main?s=ticket-all-methods",
    "transaction": {
      "reference": "all-methods-ref-001",
      "amount": 50000,
      "currency": "COP",
      "payment_method": "ALL_METHODS",
      "redirect_url": "https://your-domain.com/payment/ok",
      "ipn_url": "https://your-domain.com/webhook",
      "description": "All methods checkout"
    }
  }
}

CARD — Checkout

Mode: Checkout · You get: payment_url only (no payment_information). Redirect the customer to the secure card form on the hosted page (payments/main). Final status arrives via webhook (ipn_url).

{
  "code": "01",
  "status": "SUCCESS",
  "message": "Operacion exitosa",
  "data": {
    "ticket": "ticket-card",
    "date": "2025-10-15 15:44:57",
    "payment_url": "https://link.staging.topup.com.co/payments/main?s=ticket-card",
    "transaction": {
      "reference": "card-ref-001",
      "amount": 50000,
      "currency": "COP",
      "payment_method": "CARD",
      "redirect_url": "https://your-domain.com/payment/ok",
      "ipn_url": "https://your-domain.com/webhook",
      "description": "Card payment"
    }
  }
}

Bre-B PayIn — Bre-B specific flow details
PayIn API reference — Full v2 reference and Peru/Mexico examples

Overview

Country Configuration

PayIn

Colombia - PayIn (v2)

Quick Reference

Payment experiences

Methods in Colombia

Request parameters

Required fields

Customer data

PSE-only fields (direct experience)

Optional fields

Response structure

Envelope (always present)

`data` object — common fields

Checkout (hosted only)

Direct (your UI)

Hybrid (hosted + instructions)

Examples by payment method

PSE — Checkout (hosted bank selection)

PSE — Direct (your UI, PSE redirect URL)

EFECTY — Hybrid

BREB — Hybrid

BREB_QR — Hybrid

ALL_METHODS — Checkout

CARD — Checkout

​Colombia - PayIn (v2)

​Quick Reference

​Payment experiences

​Methods in Colombia

​Request parameters

​Required fields

​Customer data

​PSE-only fields (direct experience)

​Optional fields

​Response structure

​Envelope (always present)

​data object — common fields

​Checkout (hosted only)

​Direct (your UI)

​Hybrid (hosted + instructions)

​Examples by payment method

​PSE — Checkout (hosted bank selection)

​PSE — Direct (your UI, PSE redirect URL)

​EFECTY — Hybrid

​BREB — Hybrid

​BREB_QR — Hybrid

​ALL_METHODS — Checkout

​CARD — Checkout

​Related

Colombia - PayIn (v2)

Quick Reference

Payment experiences

Methods in Colombia

Request parameters

Required fields

Customer data

PSE-only fields (direct experience)

Optional fields

Response structure

Envelope (always present)

`data` object — common fields

Checkout (hosted only)

Direct (your UI)

Hybrid (hosted + instructions)

Examples by payment method

PSE — Checkout (hosted bank selection)

PSE — Direct (your UI, PSE redirect URL)

EFECTY — Hybrid

BREB — Hybrid

BREB_QR — Hybrid

ALL_METHODS — Checkout

CARD — Checkout

Related