PayOut - Tumipay API

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

Parameter	Value	Description
Endpoint	`POST /api/v1/payout`	Initiate PayOut transaction
Currency	`GTQ`	Guatemalan Quetzal
Country Code	`GT`	Guatemala
Auth Required	Yes	Token-Top + Basic Auth
Processing	Async	Status updates via webhook

Request Parameters

Required Fields

Field	Type	Description	Example
`payment_method`	string	Disbursement method	`"BANK_TRANSFER"`
`reference`	string	Unique transaction identifier from your system	`"gt-payout-001"`
`amount`	float	Amount in GTQ (min 50, max 500,000)	`500.00`
`currency`	string	`"GTQ"`	`"GTQ"`
`country`	string	`"GT"`	`"GT"`
`ipn_url`	string	Webhook URL	`"https://your-domain.com/webhook"`
`customer_data`	object	Recipient and account data (see below)	—

Customer Data Object

Field	Type	Required	Description	Example
`legal_doc`	string	✅	Document number	`"1234567890123"`
`legal_doc_type`	string	✅	`DPI` or `NIT`	`"DPI"`
`phone_code`	string	✅	`"502"`	`"502"`
`phone_number`	string	✅	8-digit number	`"51234567"`
`email`	string	✅	Recipient email	`"customer@example.com"`
`full_name`	string	✅	Full name	`"John Doe"`
`bank`	string	✅	Bank code — see Supported banks	`"BANCO_INDUSTRIAL"`
`account_number`	string	✅	Bank account number	`"1234567890"`
`account_type`	string	✅	`AHORRO` or `CORRIENTE`	`"AHORRO"`

Supported banks

See the full catalog in Guatemala — Banks. Account numbers must be numeric, 1–20 digits.

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

Field	Description
`data.date`	Transaction creation time in UTC (`Y-m-d H:i:s`)

Transaction Status Flow

Status	Description
`PENDING`	Transaction created, processing initiated
`APPROVED`	Funds successfully transferred
`REJECTED`	Transaction rejected or validation failure

Example Request

curl --request POST 'https://api-empresas.uat.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": "BANCO_INDUSTRIAL",
    "account_number": "1234567890",
    "account_type": "AHORRO"
  }
}'

Guatemala introduction — PayIn methods, document types, limits
PayOut API reference