> ## 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 Honduras — checkout and hybrid payment experiences.

# Honduras - PayIn (v2)

The PayIn **v2** API (`POST /api/v2/payin`) creates deposit transactions for Honduras merchants. `CASH` and `BANK_TRANSFER` are **Hybrid**: the response includes `payment_url` and `payment_information`. `ALL_METHODS` and `CARD` are **Checkout**: the response includes `payment_url`.

### Quick Reference

| Parameter | Value | Description |
| - | - | - |
| **Endpoint** | `POST /api/v2/payin` | Initiate PayIn transaction |
| **Currency** | `HNL` | Honduran Lempira |
| **Country Code** | `HN` | Honduras |
| **Auth** | Token-Top + Basic Auth | Required |

***

## Transaction limits

| Limit | Value |
| - | - |
| Minimum | **50 HNL** |
| Maximum | **25,000 HNL** |

***

## Payment experiences (v2)

| `payment_method` | Mode | `payment_url` | `payment_information` |
| - | - | - | - |
| `ALL_METHODS` | Checkout | ✅ `payments/main` | **Not returned** |
| `CARD` | Checkout | ✅ `payments/main` | **Not returned** |
| `CASH` | **Hybrid** | ✅ `payment-process` | ✅ `reference`, `expiration_date` |
| `BANK_TRANSFER` | **Hybrid** | ✅ `bank-transfer-process` | ✅ `reference`, `expiration_date` |

***

## Payment networks

Customers can complete **CASH** and **BANK\_TRANSFER** PayIns through the networks below. The customer selects the network on the hosted page or at the payment point; you do not send a network code in the PayIn request.

### CASH

| Network | Channel |
| - | - |
| Ficohsa | Agente |
| Tigo Money | Agente |
| Dilo | Agente |
| Banco Atlántida | — |
| Banco de Occidente | — |

### BANK\_TRANSFER

| Network | Channel |
| - | - |
| Ficohsa | App |
| Dilo | App |
| Banco Atlántida | App |
| Banco de Occidente | App |

> [!NOTE]
>
> **All timestamps are UTC.** `data.date` uses `YYYY-MM-DD HH:MM:SS`. For **CASH** and **BANK\_TRANSFER**, `payment_information.expiration_date` is an ISO 8601 UTC timestamp (`YYYY-MM-DDTHH:MM:SSZ`).

***

## Request parameters

### Required fields

| Field | Type | Description |
| - | - | - |
| `reference` | string | Unique id from your system |
| `amount` | number | Amount in HNL (min **50**, max **25,000**) |
| `currency` | string | `"HNL"` |
| `country` | string | `"HN"` |
| `payment_method` | string | `ALL_METHODS`, `CARD`, `CASH`, or `BANK_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 | ✅ | `DNI` or `TI` |
| `phone_code` | string | ✅ | `"504"` |
| `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`) |

***

## CASH — Hybrid

**Mode:** Hybrid · **You get:** `payment_url` + `payment_information`.

Hosted page: `payment-process`. Show `payment_information.reference` so the customer can complete the cash payment, and keep `payment_url` as a hosted fallback.

```bash theme={null}
curl --request POST 'https://api-empresas.uat.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": "hn-cash-001",
  "amount": 500,
  "currency": "HNL",
  "country": "HN",
  "payment_method": "CASH",
  "description": "Honduras PayIn test",
  "customer_data": {
    "legal_doc": "1234567890123",
    "legal_doc_type": "DNI",
    "phone_code": "504",
    "phone_number": "91234567",
    "email": "customer@example.com",
    "full_name": "John Doe"
  },
  "ipn_url": "https://your-domain.com/webhook",
  "redirect_url": "https://your-domain.com/payment/ok"
}'
```

```json theme={null}
{
  "code": "01",
  "status": "SUCCESS",
  "message": "Operacion exitosa",
  "data": {
    "ticket": "hn-cash-ticket",
    "date": "2025-10-15 15:44:57",
    "payment_url": "https://link.uat.topup.com.co/payment-process?s=hn-cash-ticket",
    "transaction": {
      "reference": "hn-cash-001",
      "amount": 500,
      "currency": "HNL",
      "payment_method": "CASH",
      "redirect_url": "https://your-domain.com/payment/ok",
      "ipn_url": "https://your-domain.com/webhook",
      "description": "Honduras PayIn test"
    },
    "payment_information": {
      "reference": "4200000000000001",
      "expiration_date": "2025-10-17T04:59:59Z"
    }
  }
}
```

| `payment_information` field | Description |
| - | - |
| `reference` | Payment reference the customer uses to complete the payment |
| `expiration_date` | UTC expiration (`YYYY-MM-DDTHH:MM:SSZ`) |

***

## BANK\_TRANSFER — Hybrid

**Mode:** Hybrid · **You get:** `payment_url` + `payment_information`.

Hosted page: `bank-transfer-process`. The `payment_information` object uses the same fields as `CASH`.

```bash theme={null}
curl --request POST 'https://api-empresas.uat.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": "hn-transfer-001",
  "amount": 500,
  "currency": "HNL",
  "country": "HN",
  "payment_method": "BANK_TRANSFER",
  "description": "Honduras PayIn test",
  "customer_data": {
    "legal_doc": "1234567890123",
    "legal_doc_type": "DNI",
    "phone_code": "504",
    "phone_number": "91234567",
    "email": "customer@example.com",
    "full_name": "John Doe"
  },
  "ipn_url": "https://your-domain.com/webhook",
  "redirect_url": "https://your-domain.com/payment/ok"
}'
```

```json theme={null}
{
  "code": "01",
  "status": "SUCCESS",
  "message": "Operacion exitosa",
  "data": {
    "ticket": "hn-transfer-ticket",
    "date": "2025-10-15 15:44:57",
    "payment_url": "https://link.uat.topup.com.co/bank-transfer-process?s=hn-transfer-ticket",
    "transaction": {
      "reference": "hn-transfer-001",
      "amount": 500,
      "currency": "HNL",
      "payment_method": "BANK_TRANSFER",
      "redirect_url": "https://your-domain.com/payment/ok",
      "ipn_url": "https://your-domain.com/webhook",
      "description": "Honduras PayIn test"
    },
    "payment_information": {
      "reference": "4400000000000001",
      "expiration_date": "2025-10-17T04:59:59Z"
    }
  }
}
```

***

## ALL\_METHODS / CARD — Checkout

**Mode:** Checkout · **You get:** `payment_url` only.

Redirect the customer to `data.payment_url` (path `payments/main`).

```bash theme={null}
curl --request POST 'https://api-empresas.uat.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": "hn-ref-001",
  "amount": 500,
  "currency": "HNL",
  "country": "HN",
  "payment_method": "ALL_METHODS",
  "description": "Honduras PayIn test",
  "customer_data": {
    "legal_doc": "1234567890123",
    "legal_doc_type": "DNI",
    "phone_code": "504",
    "phone_number": "91234567",
    "email": "customer@example.com",
    "full_name": "John Doe"
  },
  "ipn_url": "https://your-domain.com/webhook",
  "redirect_url": "https://your-domain.com/payment/ok"
}'
```

```json theme={null}
{
  "code": "01",
  "status": "SUCCESS",
  "message": "Operacion exitosa",
  "data": {
    "ticket": "hn-payin-ticket",
    "date": "2025-10-15 15:44:57",
    "payment_url": "https://link.uat.topup.com.co/payments/main?s=hn-payin-ticket",
    "transaction": {
      "reference": "hn-ref-001",
      "amount": 500,
      "currency": "HNL",
      "payment_method": "ALL_METHODS",
      "redirect_url": "https://your-domain.com/payment/ok",
      "ipn_url": "https://your-domain.com/webhook",
      "description": "Honduras PayIn test"
    }
  }
}
```

***

## Related

* [Honduras introduction](https://docs.v2.topup.com.co/docs/hn/introduction.md) — document types, limits, payout methods
* [PayIn API reference](https://docs.v2.topup.com.co/api-reference/payin.md) — global v2 reference


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.