curl --request POST 'https://api-empresas.uat.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.uat.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"
}
}
}
PayIn API
POST Initiate PayIn (v1 — deprecated)
deprecated
Legacy PayIn endpoint. Always returns a hosted payment_url. Deprecated — use POST /api/v2/payin for new integrations.
POST
/
api
/
v1
/
payin
curl --request POST 'https://api-empresas.uat.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.uat.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.payment_url for the customer to complete payment (traditional checkout). With the merchant BackToBack flag, some methods return a different B2B shape instead. Direct and hybrid flows without that flag are available only in PayIn v2.
curl --request POST 'https://api-empresas.uat.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.uat.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 behavior | v2 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 configuration | Not required in v2 |
Required Headers
Request Body Parameters
Payment method. See Country-Specific Information.
Customer identification and contact details (
legal_doc, legal_doc_type, phone_code, phone_number, email, full_name).Response
Authorizations
Body
application/json