PayIn API (v2)

PayIn v1 (POST /api/v1/payin) is deprecated. Existing integrations may continue to work, but all new development should use POST /api/v2/payin. See the v1 deprecated reference for legacy details and migration notes.

Use POST /api/v2/payin to create PayIn transactions. The response shape depends on the payment_method and the fields you send — not on a separate B2B/backoffice configuration.

Payment experiences

Mode	Response fields	Typical methods
Checkout	`payment_url`	`ALL_METHODS`, `CARD`, `PSE` (without bank), `BANK_TRANSFER`, `CASH`, Mexico cash methods
Direct	`payment_information`	`PSE` with `customer_data.bank` + `customer_data.person_type`
Hybrid	`payment_url` + `payment_information`	`EFECTY`, `BREB`, `BREB_QR`, Peru `QR`, Mexico `SPEI`

Timestamps are UTC. data.date and payment_information.expiration_date (when present) use YYYY-MM-DD HH:MM:SS in UTC. In Checkout mode, payment_information is not returned — only ticket, date, payment_url, and transaction.

Response structure

Checkout (hosted)

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

Direct (provider data only)

payment_url is omitted. Example: PSE with bank + person_type.

Hybrid (hosted + instructions)

Both payment_url and payment_information are returned. Example: EFECTY, BREB, BREB_QR, Peru QR, Mexico SPEI. Country-specific examples:

Colombia PayIn — PSE checkout vs direct, EFECTY, BREB
Peru PayIn — QR hybrid, bank transfer checkout
Mexico PayIn — SPEI hybrid, cash checkout
Guatemala PayIn — hosted checkout (CARD, CASH, TRANSFER)
Honduras PayIn — hosted checkout (CARD, CASH, TRANSFER)

This API enables customer deposit transactions across supported countries. Payment method availability is region-specific:

Colombia: ALL_METHODS, PSE, TRANSFIYA, EFECTY, CASH, CARD
Peru: BANK_TRANSFER, QR, CASH, CARD, PAGOEFECTIVO
Mexico: ALL_METHODS, CARD, CASH, SPEI, OXXO
Guatemala: ALL_METHODS, CARD, CASH, TRANSFER
Honduras: ALL_METHODS, CARD, CASH, TRANSFER

For comprehensive country-specific configuration (supported document types, currencies, banks, and payment methods), refer to the Colombia, Peru, Mexico, Guatemala, and Honduras documentation.

Transaction Limits

Amount limits:

Minimum amount (PSE): $2,000
Minimum amount (Efecty): $10,000
Maximum amount: $2,000,000

To adjust these limits, please contact the Tumipay support team at soporte@tumipay.co.

Transaction Flow

The PayIn process follows a clear sequence of interactions between different participants:

Card Payments (Colombia Only)

Card payment processing is currently available exclusively for Colombia (country: "CO"). Transactions follow the standard PayIn flow: initiate a transaction with payment_method set to CARD, redirect the customer to the payment_url, where they securely submit card details. The charge is processed asynchronously, and the final transaction status is delivered via webhook notification.

3D Secure

Some card transactions require 3D Secure (3DS) authentication. By having the 3DS authentication service active, your customers will be requested to complete an extra verification step (challenge) with the card issuer to finish the transaction. This challenge usually consists of an OTP sent by the bank to your customer’s e-mail address or telephone number. To test this flow in the sandbox environment, use the card numbers marked with Yes in the 3DS challenge column below. When the challenge screen appears, enter any six-digit code (for example 123456) to continue.

Sandbox test cards

Use the following card numbers in the sandbox environment. Use 123 as the CVV for all transactions:

Card number	3DS challenge	Charge result
4456 5400 0000 0063	No	Approved
4456 5433 7171 3314	No	Approved
4456 5419 8206 8615	No	Approved
4456 5412 4981 1088	No	Approved
4456 5300 0000 0031	Yes	Declined
4456 5300 0000 0106	Yes	Declined
4456 5365 8366 7765	Yes	Declined
4456 5365 0144 9767	Yes	Declined
4456 5327 0584 8821	Yes	Declined
4456 5280 8038 9860	Yes	Approved
4456 5292 6723 4200	Yes	Approved
4456 5291 6532 8302	Yes	Approved
4456 5248 6977 0255	Yes	Approved
4456 5233 4006 9956	Yes	Approved

Endpoints

POST Initiate a PayIn Transaction

/api/v2/payin

PayIn v2 — create transactions and receive checkout URLs, direct provider data, or both depending on the payment method.

/api/v1/payin (deprecated)

Legacy endpoint — returns only a hosted payment_url. Migrate to v2 for direct and hybrid flows.

Request Headers

string

required

Authentication token

string

required

Authorization key to access the resource

Request Body

string

required

A unique identifier sent by the client to track the transaction

integer

required

The total amount of the transaction

string

required

Three-letter currency code (ISO 4217). Use COP, PEN, MXN, GTQ, or HNL.

string

required

Two-letter country code (ISO 3166-1 alpha-2): CO, PE, MX, GT, or HN.

string

required

Specifies the payment method. See country-specific options:

string

Description of the transaction

string

required

The URL where the user will be redirected after completing the transaction

string

required

Webhook URL for transaction status updates

object

required

Show Customer data object

string

required

The customer’s legal document number

string

required

The type of legal document provided. See country-specific types:

string

required

Country code for the customer’s phone number

string

required

The customer’s phone number, excluding the country code

string

required

The customer’s email address

string

required

The customer’s full name as it appears on official documents

Response

string

required

Response code (see Error Codes)

string

required

Transaction status (e.g., “SUCCESS”)

string

Detailed message about the transaction status

object

required

Show Transaction data object

string

Unique identifier for the transaction

string

The date and time when the transaction was processed

string

Hosted checkout URL (Checkout and Hybrid modes)

object

Provider payment data (Direct and Hybrid modes). Shape varies by method — e.g. PSE redirect URL, QR payload, SPEI CLABE.

object

Show Transaction details

string

Client reference identifier

integer

Transaction amount

string

Currency code

string

Selected payment method

Error Response

string

Error code (see Error Codes)

string

Error status (e.g., “ERROR”)

string

Type of validation error (e.g., “VALIDATION_ERROR”)

string

Details about the validation error

cURL

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": "3cNPNGbX7meiMppXzVz7g781ysektqq5X",
    "amount": 5000,
    "currency": "COP",
    "country": "CO",
    "payment_method": "ALL_METHODS",
    "description": "Test PayIn",
    "redirect_url": "https://www.tumipay.co/success",
    "ipn_url": "https://your-server.com/webhook",
    "expiration_time": 720,
    "customer_data": {
        "legal_doc": "1234567890",
        "legal_doc_type": "CC",
        "phone_code": "57",
        "phone_number": "3121234567",
        "email": "customer@example.com",
        "full_name": "John Doe"
    }
}'

JavaScript

// Using fetch API
const response = await fetch('https://api-empresas.staging.topup.com.co/production/api/v2/payin', {
  method: 'POST',
  headers: {
    'Token-Top': 'your_auth_token',
    'Authorization': 'Basic your_auth_key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    reference: '3cNPNGbX7meiMppXzVz7g781ysektqq5X',
    amount: 5000,
    currency: 'COP',
    country: 'CO',
    payment_method: 'ALL_METHODS',
    description: 'Test PayIn',
    redirect_url: 'https://www.tumipay.co/success',
    ipn_url: 'https://your-server.com/webhook',
    expiration_time: 720,
    customer_data: {
      legal_doc: '1234567890',
      legal_doc_type: 'CC',
      phone_code: '57',
      phone_number: '3121234567',
      email: 'customer@example.com',
      full_name: 'John Doe'
    }
  })
});
const data = await response.json();

Python

import requests
import json

url = "https://api-empresas.staging.topup.com.co/production/api/v2/payin"

headers = {
    'Token-Top': 'your_auth_token',
    'Authorization': 'Basic your_auth_key',
    'Content-Type': 'application/json'
}

payload = {
    "reference": "3cNPNGbX7meiMppXzVz7g781ysektqq5X",
    "amount": 5000,
    "currency": "COP",
    "country": "CO",
    "payment_method": "ALL_METHODS",
    "description": "Test PayIn",
    "redirect_url": "https://www.tumipay.co/success",
    "ipn_url": "https://your-server.com/webhook",
    "expiration_time": 720,
    "customer_data": {
        "legal_doc": "1234567890",
        "legal_doc_type": "CC",
        "phone_code": "57",
        "phone_number": "3121234567",
        "email": "customer@example.com",
        "full_name": "John Doe"
    }
}

response = requests.post(url, headers=headers, data=json.dumps(payload))
result = response.json()

PHP

<?php
$url = "https://api-empresas.staging.topup.com.co/production/api/v2/payin";

$headers = array(
    'Token-Top: your_auth_token',
    'Authorization: Basic your_auth_key',
    'Content-Type: application/json'
);

$payload = array(
    "reference" => "3cNPNGbX7meiMppXzVz7g781ysektqq5X",
    "amount" => 5000,
    "currency" => "COP",
    "country" => "CO",
    "payment_method" => "ALL_METHODS",
    "description" => "Test PayIn",
    "redirect_url" => "https://www.tumipay.co/success",
    "ipn_url" => "https://your-server.com/webhook",
    "expiration_time" => 720,
    "customer_data" => array(
        "legal_doc" => "1234567890",
        "legal_doc_type" => "CC",
        "phone_code" => "57",
        "phone_number" => "3121234567",
        "email" => "customer@example.com",
        "full_name" => "John Doe"
    )
);

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);
?>

Examples for Peru

BANK_TRANSFER

The payment link will show the available banks for the transfer.

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": "bank-transfer-ref-001",
    "amount": 5000,
    "currency": "PEN",
    "country": "PE",
    "payment_method": "BANK_TRANSFER",
    "description": "Bank transfer deposit",
    "redirect_url": "https://www.tumipay.pe/success",
    "ipn_url": "https://your-server.com/webhook",
    "expiration_time": 720,
    "customer_data": {
        "legal_doc": "12345678",
        "legal_doc_type": "DNI",
        "phone_code": "51",
        "phone_number": "987654321",
        "email": "customer@example.com",
        "full_name": "Maria Vargas"
    }
}'

QR

A QR code is generated for the customer to scan and complete the payment.

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": "qr-ref-001",
    "amount": 3000,
    "currency": "PEN",
    "country": "PE",
    "payment_method": "QR",
    "description": "QR payment",
    "redirect_url": "https://www.tumipay.pe/success",
    "ipn_url": "https://your-server.com/webhook",
    "expiration_time": 720,
    "customer_data": {
        "legal_doc": "87654321",
        "legal_doc_type": "DNI",
        "phone_code": "51",
        "phone_number": "912345678",
        "email": "customer@example.com",
        "full_name": "Carlos Rodriguez"
    }
}'

PAGOEFECTIVO

Generates a cash voucher (PagoEfectivo) for the customer to pay at authorized locations or via online banking. The payment link will show the code and instructions.

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": "pe-pagoefectivo-001",
    "amount": 2500,
    "currency": "PEN",
    "country": "PE",
    "payment_method": "PAGOEFECTIVO",
    "description": "PagoEfectivo deposit",
    "redirect_url": "https://www.tumipay.pe/success",
    "ipn_url": "https://your-server.com/webhook",
    "expiration_time": 720,
    "customer_data": {
        "legal_doc": "12345678",
        "legal_doc_type": "DNI",
        "phone_code": "51",
        "phone_number": "912345678",
        "email": "customer@example.com",
        "full_name": "Carlos Rodriguez"
    }
}'

Examples for Mexico

SPEI

The payment link opens a SPEI transfer form where the customer authorizes an interbank transfer.

Mexico SPEI uses Hybrid mode in v2: payment_information includes CLABE and expiration; payment_url is also returned. See Mexico PayIn.

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": "mx-spei-ref-001",
    "amount": 500.00,
    "currency": "MXN",
    "country": "MX",
    "payment_method": "SPEI",
    "description": "SPEI deposit",
    "redirect_url": "https://www.tumipay.mx/success",
    "ipn_url": "https://your-server.com/webhook",
    "expiration_time": 720,
    "customer_data": {
        "legal_doc": "CURP12345678901234",
        "legal_doc_type": "INE",
        "phone_code": "52",
        "phone_number": "5512345678",
        "email": "customer@example.com",
        "full_name": "Juan Pérez"
    }
}'

OXXO

Generates a cash voucher the customer can present and pay at any OXXO convenience store.

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": "mx-oxxo-ref-001",
    "amount": 200.00,
    "currency": "MXN",
    "country": "MX",
    "payment_method": "OXXO",
    "description": "OXXO cash deposit",
    "redirect_url": "https://www.tumipay.mx/success",
    "ipn_url": "https://your-server.com/webhook",
    "expiration_time": 720,
    "customer_data": {
        "legal_doc": "CURP12345678901234",
        "legal_doc_type": "INE",
        "phone_code": "52",
        "phone_number": "5512345678",
        "email": "customer@example.com",
        "full_name": "Juan Pérez"
    }
}'

CASH

Generates a cash payment reference for authorized collection points. customer_address is required for this method.

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": "mx-cash-ref-001",
    "amount": 300.00,
    "currency": "MXN",
    "country": "MX",
    "payment_method": "CASH",
    "description": "Cash deposit",
    "redirect_url": "https://www.tumipay.mx/success",
    "ipn_url": "https://your-server.com/webhook",
    "expiration_time": 720,
    "customer_data": {
        "legal_doc": "CURP12345678901234",
        "legal_doc_type": "INE",
        "phone_code": "52",
        "phone_number": "5512345678",
        "email": "customer@example.com",
        "full_name": "Juan Pérez",
        "customer_address": "Av. Insurgentes Sur 1602, Col. Crédito Constructor, CDMX"
    }
}'

CARD (Mexico)

The payment link opens a secure card form for credit and debit card payments.

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": "mx-card-ref-001",
    "amount": 750.00,
    "currency": "MXN",
    "country": "MX",
    "payment_method": "CARD",
    "description": "Card payment",
    "redirect_url": "https://www.tumipay.mx/success",
    "ipn_url": "https://your-server.com/webhook",
    "expiration_time": 720,
    "customer_data": {
        "legal_doc": "CURP12345678901234",
        "legal_doc_type": "INE",
        "phone_code": "52",
        "phone_number": "5512345678",
        "email": "customer@example.com",
        "full_name": "Juan Pérez"
    }
}'

Error Codes

Code	Meaning
01	Operation successful
00	Validation error or processing failed

Examples by Payment Method

These examples use the same endpoint but change the payment_method field. The returned payment_url directs the customer to the appropriate interface for each method.

PSE — TumiPay checkout

Without bank / person_type: returns payment_url for hosted bank selection.

PSE — Direct

With customer_data.bank and customer_data.person_type: returns payment_information.payment_url (PSE redirect). List banks via GET /api/v1/pse/banks.

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-ref-001",
    "amount": 50000,
    "currency": "COP",
    "country": "CO",
    "payment_method": "PSE",
    "description": "PSE direct",
    "redirect_url": "https://www.tumipay.co/success",
    "ipn_url": "https://your-server.com/webhook",
    "customer_data": {
        "person_type": "NATURAL",
        "bank": "1007",
        "legal_doc": "1234567890",
        "legal_doc_type": "CC",
        "phone_code": "57",
        "phone_number": "3121234567",
        "email": "customer@example.com",
        "full_name": "John Doe"
    }
}'

{
  "code": "01",
  "status": "SUCCESS",
  "data": {
    "ticket": "pse-ticket-id",
    "payment_information": {
      "payment_url": "https://registro.pse.com.co/PSENF/index.html?enc=..."
    },
    "transaction": { "payment_method": "PSE", "currency": "COP" }
  }
}

PSE — Checkout (hosted)

The payment link opens the bank selection screen on TumiPay checkout.

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-ref-001",
    "amount": 5000,
    "currency": "COP",
    "country": "CO",
    "payment_method": "PSE",
    "description": "PSE deposit",
    "redirect_url": "https://www.tumipay.co/success",
    "ipn_url": "https://your-server.com/webhook",
    "expiration_time": 720,
    "customer_data": {
        "legal_doc": "1234567890",
        "legal_doc_type": "CC",
        "phone_code": "57",
        "phone_number": "3121234567",
        "email": "customer@example.com",
        "full_name": "John Doe"
    }
}'

const response = await fetch('https://api-empresas.staging.topup.com.co/production/api/v2/payin', {
  method: 'POST',
  headers: {
    'Token-Top': 'your_auth_token',
    'Authorization': 'Basic your_auth_key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    reference: 'pse-ref-001',
    amount: 5000,
    currency: 'COP',
    country: 'CO',
    payment_method: 'PSE',
    description: 'PSE deposit',
    redirect_url: 'https://www.tumipay.co/success',
    ipn_url: 'https://your-server.com/webhook',
    expiration_time: 720,
    customer_data: {
      legal_doc: '1234567890',
      legal_doc_type: 'CC',
      phone_code: '57',
      phone_number: '3121234567',
      email: 'customer@example.com',
      full_name: 'John Doe'
    }
  })
});
const data = await response.json();

EFECTY

The payment link generates a cash voucher that must be presented at an Efecty location.

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": "efecty-ref-001",
    "amount": 20000,
    "currency": "COP",
    "country": "CO",
    "payment_method": "EFECTY",
    "description": "Cash deposit",
    "redirect_url": "https://www.tumipay.co/success",
    "ipn_url": "https://your-server.com/webhook",
    "expiration_time": 720,
    "customer_data": {
        "legal_doc": "1234567890",
        "legal_doc_type": "CC",
        "phone_code": "57",
        "phone_number": "3121234567",
        "email": "customer@example.com",
        "full_name": "John Doe"
    }
}'

const response = await fetch('https://api-empresas.staging.topup.com.co/production/api/v2/payin', {
  method: 'POST',
  headers: {
    'Token-Top': 'your_auth_token',
    'Authorization': 'Basic your_auth_key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    reference: 'efecty-ref-001',
    amount: 20000,
    currency: 'COP',
    country: 'CO',
    payment_method: 'EFECTY',
    description: 'Cash deposit',
    redirect_url: 'https://www.tumipay.co/success',
    ipn_url: 'https://your-server.com/webhook',
    expiration_time: 720,
    customer_data: {
      legal_doc: '1234567890',
      legal_doc_type: 'CC',
      phone_code: '57',
      phone_number: '3121234567',
      email: 'customer@example.com',
      full_name: 'John Doe'
    }
  })
});
const data = await response.json();

{
  "code": "01",
  "status": "SUCCESS",
  "message": "Operation successful",
  "data": {
    "ticket": "efecty-ticket-id",
    "date": "2024-12-27 14:35:00",
    "payment_url": "https://link.staging.topup.com.co/efecty-confirmation?s=efecty-ticket-id",
    "payment_information": {
      "reference": "9876543210",
      "convenio": "12345",
      "expiration_date": "2024-12-28 02:35:00"
    },
    "transaction": {
      "reference": "efecty-ref-001",
      "amount": 20000,
      "currency": "COP",
      "payment_method": "EFECTY"
    }
  }
}

CARD

The payment link opens a secure card form. The webhook payload includes a top_card object with details of the card used.

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": "card-ref-001",
    "amount": 5000,
    "currency": "COP",
    "country": "CO",
    "payment_method": "CARD",
    "description": "Card payment",
    "redirect_url": "https://www.tumipay.co/success",
    "ipn_url": "https://your-server.com/webhook",
    "expiration_time": 720,
    "customer_data": {
        "legal_doc": "1234567890",
        "legal_doc_type": "CC",
        "phone_code": "57",
        "phone_number": "3121234567",
        "email": "customer@example.com",
        "full_name": "John Doe"
    }
}'

const response = await fetch('https://api-empresas.staging.topup.com.co/production/api/v2/payin', {
  method: 'POST',
  headers: {
    'Token-Top': 'your_auth_token',
    'Authorization': 'Basic your_auth_key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    reference: 'card-ref-001',
    amount: 5000,
    currency: 'COP',
    country: 'CO',
    payment_method: 'CARD',
    description: 'Card payment',
    redirect_url: 'https://www.tumipay.co/success',
    ipn_url: 'https://your-server.com/webhook',
    expiration_time: 720,
    customer_data: {
      legal_doc: '1234567890',
      legal_doc_type: 'CC',
      phone_code: '57',
      phone_number: '3121234567',
      email: 'customer@example.com',
      full_name: 'John Doe'
    }
  })
});
const data = await response.json();

{
  "code": "01",
  "status": "SUCCESS",
  "message": "Operation successful",
  "data": {
    "ticket": "card-ticket-id",
    "date": "2024-12-27 14:35:00",
    "payment_url": "https://example.com/payment/card",
    "transaction": {
      "reference": "card-ref-001",
      "amount": 5000,
      "currency": "COP",
      "payment_method": "CARD"
    }
  }
}

Response Examples

{
  "code": "01",
  "status": "SUCCESS",
  "message": "Operation successful",
  "data": {
    "ticket": "1fb500ad-feb4-409d-95ba-c10b708abf05",
    "date": "2024-12-27 14:35:00",
    "payment_url": "https://example.com/payment/12345",
    "transaction": {
      "reference": "3cNPNGbX7meiMppXzVz7g781ysektqq5X",
      "amount": 5000,
      "currency": "COP",
      "payment_method": "PSE"
    }
  }
}

{
  "code": "00",
  "status": "ERROR",
  "error": "VALIDATION_ERROR",
  "message": "The payment method is invalid."
}

​PayIn API (v2)

​Payment experiences

​Response structure

​Checkout (hosted)

​Direct (provider data only)

​Hybrid (hosted + instructions)

​Transaction Limits

​Transaction Flow

​Card Payments (Colombia Only)

​3D Secure

​Sandbox test cards

​Endpoints

​POST Initiate a PayIn Transaction

/api/v2/payin

/api/v1/payin (deprecated)

​Request Headers

​Request Body

​Response

​Error Response

​Examples for Peru

​BANK_TRANSFER

​QR

​PAGOEFECTIVO

​Examples for Mexico

​SPEI

​OXXO

​CASH

​CARD (Mexico)

​Error Codes

​Examples by Payment Method

​PSE — TumiPay checkout

​PSE — Direct

​PSE — Checkout (hosted)

​EFECTY

​CARD

​Response Examples

PayIn API (v2)

Payment experiences

Response structure

Checkout (hosted)

Direct (provider data only)

Hybrid (hosted + instructions)

Transaction Limits

Transaction Flow

Card Payments (Colombia Only)

3D Secure

Sandbox test cards

Endpoints

POST Initiate a PayIn Transaction

Request Headers

Request Body

Response

Error Response

Examples for Peru

BANK_TRANSFER

QR

PAGOEFECTIVO

Examples for Mexico

SPEI

OXXO

CASH

CARD (Mexico)

Error Codes

Examples by Payment Method

PSE — TumiPay checkout

PSE — Direct

PSE — Checkout (hosted)

EFECTY

CARD

Response Examples