POST Initiate PayIn Transaction

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": "13cNPNGbX7meiMppXzVz7g781ysektqq5X",
            "amount": 5000,
            "currency": "PEN",
            "payment_method": "ALL_METHODS",
            "redirect_url": "https://your-domain.com/payment/success",
            "ipn_url": "https://your-domain.com/webhook",
            "description": "Test PayIn"
        }
    }
}

POST

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": "13cNPNGbX7meiMppXzVz7g781ysektqq5X",
            "amount": 5000,
            "currency": "PEN",
            "payment_method": "ALL_METHODS",
            "redirect_url": "https://your-domain.com/payment/success",
            "ipn_url": "https://your-domain.com/webhook",
            "description": "Test PayIn"
        }
    }
}

Initialize a new PayIn transaction for payment processing. This endpoint allows you to create a new payment request that your customers can pay through various payment methods.

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": "13cNPNGbX7meiMppXzVz7g781ysektqq5X",
            "amount": 5000,
            "currency": "PEN",
            "payment_method": "ALL_METHODS",
            "redirect_url": "https://your-domain.com/payment/success",
            "ipn_url": "https://your-domain.com/webhook",
            "description": "Test PayIn"
        }
    }
}

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 code.

currency

string

required

Three-letter currency code following the ISO 4217 standard (e.g., COP, PEN).

payment_method

string

required

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

description

string

required

Transaction description or purpose.

customer_data

object

required

Show Customer data object

legal_doc

string

required

The customer’s legal document number

legal_doc_type

string

required

The type of legal document provided. See Country-Specific Information for available document types.

phone_code

string

required

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

phone_number

string

required

The customer’s phone number, excluding the country code

string

required

The customer’s email address

full_name

string

required

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

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 (UUID v4)

reference

string

Your provided transaction reference (must be unique)

status

string

Initial transaction status (will be PENDING)

payment_url

string

URL to redirect the customer for payment

expiration

string

Payment link expiration timestamp (UTC)

Authorizations

Token-Top

string

header

required

Merchant authentication token

Authorization

string

header

required

Basic authentication with username and password

Body

application/json

reference

string

required

Your unique transaction reference

amount

number

required

Transaction amount (in cents/minor currency unit)

currency

string

required

Three-letter currency code (ISO 4217)

Example:

"COP"

payment_method

enum<string>

required

Payment method to be used. Availability varies by country.

Available options:

ALL_METHODS,

PSE,

EFECTY,

TRANSFIYA,

CARD,

BANK_TRANSFER,

QR,

PAGOEFECTIVO

ipn_url

string<uri>

required

URL for receiving webhook notifications

redirect_url

string<uri>

required

URL to redirect after payment completion

country

string

required

Two-letter country code (ISO 3166-1 alpha-2). Possible values: CO, PE, MX

Example:

"CO"

description

string

Transaction description

customer_data

object

Show child attributes

metadata

object

Custom metadata managed entirely by your implementation. Include any fields you require.

expiration_time

integer

Payment link expiration time in minutes

Response

Successful response

ticket

string

Unique transaction identifier

reference

string

Your provided transaction reference

status

enum<string>

Initial transaction status

Available options:

PENDING

payment_url

string<uri>

URL to redirect the customer for payment

expiration

string<date-time>

Payment link expiration timestamp (UTC)

PayIn API PayOut API

​Required Headers

​Request Body Parameters

​Response

Authorizations

Body

Response

Required Headers

Request Body Parameters

Response