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"
}'

Guatemala introduction — document types, limits, payout methods
PayIn API reference — global v2 reference

Overview

Country Configuration

PayIn

Guatemala - PayIn (v2)

Quick Reference

Payment experiences (v2)

Request parameters

Required fields

Customer data

Optional fields

Response structure (Checkout)

Example request

​Guatemala - PayIn (v2)

​Quick Reference

​Payment experiences (v2)

​Request parameters

​Required fields

​Customer data

​Optional fields

​Response structure (Checkout)

​Example request

​Related

Guatemala - PayIn (v2)

Quick Reference

Payment experiences (v2)

Request parameters

Required fields

Customer data

Optional fields

Response structure (Checkout)

Example request

Related