POST Initiate PayIn Transaction (v2)

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

{
    "code": "01",
    "status": "SUCCESS",
    "message": "Operacion exitosa",
    "data": {
        "ticket": "8BNsCFva1NKPqy2",
        "date": "2025-10-15 17:58:36",
        "payment_url": "https://link.staging.topup.com.co/payments/main?s=8BNsCFva1NKPqy2",
        "transaction": {
            "reference": "3cNPNGbX7meiMppXzVz7g781ysektqq5X",
            "amount": 50000,
            "currency": "COP",
            "payment_method": "ALL_METHODS",
            "redirect_url": "https://your-domain.com/payment/success",
            "ipn_url": "https://your-domain.com/webhook",
            "description": "Test PayIn"
        }
    }
}

POST

api

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

{
    "code": "01",
    "status": "SUCCESS",
    "message": "Operacion exitosa",
    "data": {
        "ticket": "8BNsCFva1NKPqy2",
        "date": "2025-10-15 17:58:36",
        "payment_url": "https://link.staging.topup.com.co/payments/main?s=8BNsCFva1NKPqy2",
        "transaction": {
            "reference": "3cNPNGbX7meiMppXzVz7g781ysektqq5X",
            "amount": 50000,
            "currency": "COP",
            "payment_method": "ALL_METHODS",
            "redirect_url": "https://your-domain.com/payment/success",
            "ipn_url": "https://your-domain.com/webhook",
            "description": "Test PayIn"
        }
    }
}

This is the recommended PayIn endpoint. The legacy v1 endpoint (POST /api/v1/payin) is deprecated.

Initialize a PayIn transaction using API v2 (POST /api/v2/payin). The response includes payment_url, payment_information, or both depending on the payment method and request fields. See PayIn API and Colombia PayIn for method-specific examples (e.g. PSE checkout vs direct).

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

{
    "code": "01",
    "status": "SUCCESS",
    "message": "Operacion exitosa",
    "data": {
        "ticket": "8BNsCFva1NKPqy2",
        "date": "2025-10-15 17:58:36",
        "payment_url": "https://link.staging.topup.com.co/payments/main?s=8BNsCFva1NKPqy2",
        "transaction": {
            "reference": "3cNPNGbX7meiMppXzVz7g781ysektqq5X",
            "amount": 50000,
            "currency": "COP",
            "payment_method": "ALL_METHODS",
            "redirect_url": "https://your-domain.com/payment/success",
            "ipn_url": "https://your-domain.com/webhook",
            "description": "Test PayIn"
        }
    }
}

Required Headers

string

required

Your merchant authentication token

string

required

Basic authentication key

string

required

Must be “application/json”

Request Body Parameters

string

required

Your unique transaction reference

number

required

Transaction amount in the specified currency.

string

required

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

string

required

Two-letter country code (ISO 3166-1 alpha-2): CO, PE, MX, GT, or HN. Must match the merchant country and currency.

string

required

Payment method. See Country-Specific Information for available payment methods.

string

required

Transaction description or purpose.

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 Information for available document types.

string

required

Country code for the customer’s phone number (e.g., 57, 51)

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

string

PSE direct only — bank code from GET /api/v1/pse/banks. Required together with person_type.

string

PSE direct only — NATURAL or JURIDICA. Required together with bank.

integer

Payment link expiration time in minutes

string

URL for receiving webhook notifications

string

URL to redirect after payment completion

Response

string

Unique transaction identifier (TumiPay ticket)

string

Transaction creation timestamp

string

Hosted checkout URL when the method uses Checkout or Hybrid mode

object

Provider payment data when the method uses Direct or Hybrid mode

object

Echo of request metadata (reference, amount, currency, payment_method, urls)

Authorizations

Token-Top

string

header

required

Authorization

string

header

required

Basic authentication header of the form Basic <encoded-value>, where <encoded-value> is the base64-encoded string username:password.

Body

application/json

reference

string

required

amount

number

required

currency

string

required

Example:

"COP"

country

enum<string>

required

ISO 3166-1 alpha-2 country code

Available options:

CO,

PE,

MX,

GT,

HN

Example:

"CO"

payment_method

string

required

description

string

required

customer_data

object

required

Show child attributes

expiration_time

integer

ipn_url

string<uri>

redirect_url

string<uri>

Response

Transaction created

code

string

status

string

message

string

data

object

Show child attributes

Getting Started

Merchant API

PayIn API

PayOut API

Card Payment API

Integration

POST Initiate PayIn Transaction (v2)

Required Headers

Request Body Parameters

Response

Authorizations

Body

Response

​Required Headers

​Request Body Parameters

​Response

Authorizations

Body

Response

Required Headers

Request Body Parameters

Response