Guatemala - PayIn (v2)
The PayIn v2 API (POST /api/v2/payin) creates deposit transactions and returns a hosted payment link for Guatemala merchants.
Quick Reference
| Parameter | Value | Description |
|---|
| Endpoint | POST /api/v2/payin | Initiate PayIn transaction |
| Currency | GTQ | Guatemalan Quetzal |
| Country Code | GT | Guatemala |
| Auth | Token-Top + Basic Auth | Required |
Payment experiences (v2)
payment_method | Mode | payment_url | payment_information |
|---|
ALL_METHODS | Checkout | ✅ payments/main | Not returned |
CARD | Checkout | ✅ payments/main | Not returned |
CASH | Checkout | ✅ payments/main | Not returned |
TRANSFER | Checkout | ✅ payments/main | Not returned |
All timestamps are UTC. data.date uses YYYY-MM-DD HH:MM:SS in UTC. In Checkout mode, payment_information is not returned.
Request parameters
Required fields
| Field | Type | Description |
|---|
reference | string | Unique id from your system |
amount | number | Amount in GTQ (min 50, max 1,000,000) |
currency | string | "GTQ" |
country | string | "GT" |
payment_method | string | ALL_METHODS, CARD, CASH, or TRANSFER |
description | string | Transaction description |
customer_data | object | Customer identity and contact |
Customer data
| Field | Type | Required | Description |
|---|
legal_doc | string | ✅ | Document number |
legal_doc_type | string | ✅ | DPI or NIT |
phone_code | string | ✅ | "502" |
phone_number | string | ✅ | 8-digit mobile number |
email | string | ✅ | Customer email |
full_name | string | ✅ | Full name |
Optional fields
| Field | Type | Description |
|---|
ipn_url | string | Webhook URL for status updates |
redirect_url | string | Return URL after payment |
expiration_time | integer | Link validity in minutes (default 720) |
Response structure (Checkout)
Redirect the customer to data.payment_url. payment_information is not included.
{
"code": "01",
"status": "SUCCESS",
"message": "Operacion exitosa",
"data": {
"ticket": "gt-payin-ticket",
"date": "2025-10-15 15:44:57",
"payment_url": "https://link.staging.topup.com.co/payments/main?s=gt-payin-ticket",
"transaction": {
"reference": "gt-ref-001",
"amount": 500,
"currency": "GTQ",
"payment_method": "ALL_METHODS",
"redirect_url": "https://your-domain.com/ok",
"ipn_url": "https://your-domain.com/webhook",
"description": "Guatemala PayIn test"
}
}
}
Example request
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": "gt-ref-001",
"amount": 500,
"currency": "GTQ",
"country": "GT",
"payment_method": "ALL_METHODS",
"description": "Guatemala PayIn test",
"customer_data": {
"legal_doc": "1234567890123",
"legal_doc_type": "DPI",
"phone_code": "502",
"phone_number": "51234567",
"email": "customer@example.com",
"full_name": "John Doe"
},
"ipn_url": "https://your-domain.com/webhook",
"redirect_url": "https://your-domain.com/payment/ok"
}'
