Skip to main content
POST
/
api
/
v1
/
payin
curl --request POST 'https://api-empresas.staging.topup.com.co/production/api/v1/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",
    "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": 5000,
            "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 endpoint is deprecated. Use POST /api/v2/payin for all new integrations. PayIn v2 supports checkout, direct, and hybrid payment experiences without separate backoffice configuration.
Initialize a PayIn transaction using the legacy v1 API. This version always returns a hosted payment_url for the customer to complete payment. Direct and hybrid flows (PSE without redirect, EFECTY instructions, BREB keys, etc.) are available only in PayIn v2. 
curl --request POST 'https://api-empresas.staging.topup.com.co/production/api/v1/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",
    "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": 5000,
            "currency": "COP",
            "payment_method": "ALL_METHODS",
            "redirect_url": "https://your-domain.com/payment/success",
            "ipn_url": "https://your-domain.com/webhook",
            "description": "Test PayIn"
        }
    }
}

​
Migration to v2

v1 behaviorv2 equivalent
Hosted checkout (payment_url)Same — use v2 without extra fields
Back-to-back PSE (backoffice flag)Send customer_data.bank + customer_data.person_type with payment_method: "PSE"
Back-to-back SPEI (Mexico, merchant flag)Send payment_method: "SPEI" — v2 returns hybrid payment_url + payment_information
Separate B2B configurationNot required in v2
See PayIn API (v2) and Colombia PayIn for method-specific v2 examples.

​
Required Headers

​
Token-Top
string
required
Your merchant authentication token
​
Authorization
string
required
Basic authentication key
​
Content-Type
string
required
Must be application/json

​
Request Body Parameters

​
reference
string
required
Your unique transaction reference
​
amount
number
required
Transaction amount in the specified currency.
​
currency
string
required
Three-letter currency code (ISO 4217), e.g. COP, PEN, MXN.
​
country
string
required
Two-letter country code (ISO 3166-1 alpha-2), e.g. CO, PE, MX.
​
payment_method
string
required
Payment method. See Country-Specific Information.
​
description
string
required
Transaction description or purpose.
​
customer_data
object
required
Customer identification and contact details (legal_doc, legal_doc_type, phone_code, phone_number, email, full_name).
​
expiration_time
integer
Payment link expiration time in minutes
​
ipn_url
string
required
URL for receiving webhook notifications
​
redirect_url
string
required
URL to redirect after payment completion

​
Response

​
ticket
string
Unique transaction identifier
​
payment_url
string
Hosted checkout URL to redirect the customer
​
transaction
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
string
required
Example:

"CO"

​
payment_method
string
required
​
description
string
required
​
customer_data
object
required
​
ipn_url
string<uri>
required
​
redirect_url
string<uri>
required
​
expiration_time
integer

Response

Transaction created

​
code
string
​
status
string
​
message
string
​
data
object