Skip to main content

​
Overview

The PayOut API for Guatemala enables disbursements to local bank accounts via BANK_TRANSFER. Transactions are processed asynchronously with webhook notifications for status updates.

​
Quick Reference

ParameterValueDescription
EndpointPOST /api/v1/payoutInitiate PayOut transaction
CurrencyGTQGuatemalan Quetzal
Country CodeGTGuatemala
Auth RequiredYesToken-Top + Basic Auth
ProcessingAsyncStatus updates via webhook

​
Request Parameters

​
Required Fields

FieldTypeDescriptionExample
payment_methodstringDisbursement method"BANK_TRANSFER"
referencestringUnique transaction identifier from your system"gt-payout-001"
amountfloatAmount in GTQ (min 50, max 500,000)500.00
currencystring"GTQ""GTQ"
countrystring"GT""GT"
ipn_urlstringWebhook URL"https://your-domain.com/webhook"
customer_dataobjectRecipient and account data (see below)—

​
Customer Data Object

FieldTypeRequiredDescriptionExample
legal_docstring✅Document number"1234567890123"
legal_doc_typestring✅DPI or NIT"DPI"
phone_codestring✅"502""502"
phone_numberstring✅8-digit number"51234567"
emailstring✅Recipient email"customer@example.com"
full_namestring✅Full name"John Doe"
bankstring✅Bank codePending catalog
account_numberstring✅Bank account number"1234567890"
account_typestring✅AHORRO or CORRIENTE"AHORRO"
Supported banks: the bank code list for Guatemala is pending publication. Contact soporte@tumipay.co for the current catalog before production.

​
Response Structure

{
  "code": "01",
  "status": "SUCCESS",
  "message": "Operacion exitosa",
  "data": {
    "ticket": "gt-payout-ticket",
    "date": "2025-10-15 15:44:57",
    "transaction": {
      "reference": "gt-payout-001",
      "amount": 500,
      "currency": "GTQ",
      "payment_method": "BANK_TRANSFER",
      "ipn_url": "https://your-domain.com/webhook"
    }
  }
}
FieldDescription
data.dateTransaction creation time in UTC (Y-m-d H:i:s)

​
Transaction Status Flow

StatusDescription
PENDINGTransaction created, processing initiated
APPROVEDFunds successfully transferred
REJECTEDTransaction rejected or validation failure

​
Example Request

curl --request POST 'https://api-empresas.staging.topup.com.co/production/api/v1/payout' \
--header 'Token-Top: your_auth_token' \
--header 'Authorization: Basic your_auth_key' \
--header 'Content-Type: application/json' \
--data-raw '{
  "payment_method": "BANK_TRANSFER",
  "reference": "gt-payout-001",
  "amount": 500,
  "currency": "GTQ",
  "country": "GT",
  "ipn_url": "https://your-domain.com/webhook",
  "customer_data": {
    "legal_doc": "1234567890123",
    "legal_doc_type": "DPI",
    "phone_code": "502",
    "phone_number": "51234567",
    "email": "customer@example.com",
    "full_name": "John Doe",
    "bank": "BANK_CODE_TBD",
    "account_number": "1234567890",
    "account_type": "AHORRO"
  }
}'