curl --request POST 'https://api-empresas.uat.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.uat.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"
}
}
}
PayIn API
POST Initiate PayIn Transaction (v2)
Create a PayIn transaction. Returns payment_url, payment_information, or both depending on payment_method and request fields.
POST
/
api
/
v2
/
payin
curl --request POST 'https://api-empresas.uat.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.uat.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.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.uat.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.uat.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
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
Basic authentication header of the form Basic <encoded-value>, where <encoded-value> is the base64-encoded string username:password.
Body
application/json
Example:
"COP"
ISO 3166-1 alpha-2 country code
Available options:
CO, PE, MX, GT, HN Example:
"CO"
Show child attributes
Show child attributes