> ## Documentation Index
> Fetch the complete documentation index at: https://docs.v2.topup.com.co/llms.txt
> Use this file to discover all available pages before exploring further.

# PayIn

> PayIn v2 for Guatemala — hosted checkout payment experiences.

# 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**      |

<Note>
  **All timestamps are UTC.** `data.date` uses `YYYY-MM-DD HH:MM:SS` in UTC. In Checkout mode, `payment_information` is **not returned**.
</Note>

***

## 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.**

```json theme={null}
{
  "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

```bash theme={null}
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"
}'
```

***

## Related

* [Guatemala introduction](./introduction) — document types, limits, payout methods
* [PayIn API reference](/api-reference/payin) — global v2 reference