> For the complete documentation index, see [llms.txt](https://docs.tupayonline.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tupayonline.com/documentacion-de-la-api/tu-recaudo/lote-de-ordenes.md).

# Lote de Ordenes

## Endpoint Creación Lote Individual

<mark style="color:orange;">`STAGING POST`</mark> [<mark style="color:orange;">https://turecaudo-api-stg.tupaypagos.com/v1/payment-orders</mark>](https://turecaudo-api-stg.tupaypagos.com/v1/payment-orders)

<mark style="color:orange;">`PRODUCTION POST`</mark> [<mark style="color:orange;">https://turecaudo-api.tupaypagos.com/v1/payment-orders</mark>](https://turecaudo-api-stg.tupaypagos.com/v1/payment-orders)

#### Headers

| Name                                      | Type   | Description                                                                             |
| ----------------------------------------- | ------ | --------------------------------------------------------------------------------------- |
| Content-Type                              | string | `application/json`                                                                      |
| X-Date<mark style="color:red;">\*</mark>  | string | <p>Fecha según el estándar ISO8601 formato: <br><code>yyyy-MM-dd'T'HH:mm:ssZ</code></p> |
| X-Login<mark style="color:red;">\*</mark> | string | X-Login API Key del Comercio                                                            |
| Authorization                             | string | Hash de control de autorización                                                         |
| X-Idempotency-Key                         | string | Idempotency key única                                                                   |

#### Request Body

| Name                                                   | Type                       | Description                                                                            |
| ------------------------------------------------------ | -------------------------- | -------------------------------------------------------------------------------------- |
| `payment_reference` <mark style="color:red;">\*</mark> | String                     | Identificador único de la orden definido por el merchant. Debe ser único por merchant. |
| `concept` <mark style="color:red;">\*</mark>           | String                     | Concepto o título del pago.                                                            |
| `description` <mark style="color:red;">\*</mark>       | String                     | Descripción detallada del pago.                                                        |
| `currency` <mark style="color:red;">\*</mark>          | String (ISO 4217)          | Código de moneda en formato de 3 caracteres (ej: USD, PEN).                            |
| `amount` <mark style="color:red;">\*</mark>            | Number (Decimal)           | Monto principal del pago.                                                              |
| `late_payment_amount`                                  | Number (Decimal)           | Recargo aplicable por pago tardío.                                                     |
| `expiration` <mark style="color:red;">\*</mark>        | String (Date - dd/MM/yyyy) | Fecha de expiración de la orden.                                                       |
| `due_date` <mark style="color:red;">\*</mark>          | String (Date - dd/MM/yyyy) | Fecha de vencimiento del pago.                                                         |
| `type` <mark style="color:red;">\*</mark>              | String                     | Tipo de orden de pago.                                                                 |
| `client_name` <mark style="color:red;">\*</mark>       | String                     | Nombre del cliente.                                                                    |
| `client_last_name` <mark style="color:red;">\*</mark>  | String                     | Apellido del cliente.                                                                  |
| `document_type` <mark style="color:red;">\*</mark>     | String                     | Tipo de documento del cliente (DNI, RUC, CE, PASS).                                    |
| `client_document` <mark style="color:red;">\*</mark>   | String                     | Número de documento del cliente.                                                       |
| `client_email` <mark style="color:red;">\*</mark>      | String (Email)             | Correo electrónico del cliente.                                                        |
| `phone`                                                | String                     | Teléfono del cliente.                                                                  |
| `merchant_id` <mark style="color:red;">\*</mark>       | Integer                    | Identificador del merchant autenticado.                                                |
| `notification_url`                                     | String (URL)               | URL para recibir notificaciones webhook.                                               |

{% tabs %}
{% tab title="201 Solicitud de depósito creada exitosamente" %}
{% code overflow="wrap" fullWidth="false" %}

```json
{
  "id": 1234,
  "payment_reference": "INV-2024-001",
  "creation_date": "2026-02-04T10:30:00",
  "concept": "Monthly service fee",
  "description": "Payment for January services",
  "currency": "USD",
  "amount": 150.00,
  "late_payment_amount": 10.00,
  "expiration": "31/12/2026",
  "due_date": "15/12/2026",
  "client_name": "Juan",
  "client_last_name": "Perez",
  "document_type": "DNI",
  "client_document": "12345678",
  "client_email": "juan.perez@email.com",
  "phone": "+51987654321",
  "status": 2,
  "deposit_id": null,
  "redirect_url": null,
  "pay_order_batch": {
    "id": 500,
    "submission_date": "2026-02-04T10:30:00",
    "total_transactions": 1,
    "source_type": "API",
    "status": 1,
    "merchant_id": 18297
  }
}
```

{% endcode %}
{% endtab %}

{% tab title="401: Unauthorized Invalid signature" %}

```json
{
    "code": 102,
    "description": "Invalid signature",
    "type": "INVALID_SIGNATURE"
}
```

{% endtab %}

{% tab title="400: Bad Request La solictud de deposito fallo" %}

````json
**Referencia duplicada (409):**
```json
{
  "code": 18,
  "description": "Payment reference already exists for this merchant: INV2026001.",
  "details": [],
  "type": "DUPLICATE_PAYMENT_REFERENCE"
}
```

**Campo excede longitud maxima (400):**
```json
{
  "code": 19,
  "description": "Field payment_reference exceeds maximum allowed length of 255 characters.",
  "details": [],
  "type": "INVALID_FIELD_LENGTH"
}
```

**Campos requeridos faltantes (400):**
```json
{
  "code": 1,
  "description": "Field validation error. Check details",
  "details": [
    "amount: must not be null",
    "clientName: must not be blank"
  ],
  "type": "GENERIC_ERROR"
}
```

**Formato de referencia invalido (400):**
```json
{
  "code": 20,
  "description": "Payment reference must be alphanumeric and between 6 and 14 characters: INV-001.",
  "details": [],
  "type": "INVALID_PAYMENT_REFERENCE_FORMAT"
}
```

**Campo requerido faltante - expiration/due_date (400):**
```json
{
  "code": 21,
  "description": "Field expiration is required.",
  "details": [],
  "type": "REQUIRED_FIELD_MISSING"
}
```

**Tipo de documento invalido (400):**
```json
{
  "code": 24,
  "description": "Invalid document type: CEDULA. Allowed values: DNI, RUC, CE, PASS.",
  "details": [],
  "type": "INVALID_DOCUMENT_TYPE"
}
```

**Formato de documento invalido (400):**
```json
{
  "code": 25,
  "description": "Invalid document format for document type DNI: ABC123.",
  "details": [],
  "type": "INVALID_DOCUMENT_FORMAT"
}
```

**Formato de email invalido (400):**
```json
{
  "code": 26,
  "description": "Invalid email format: not-an-email.",
  "details": [],
  "type": "INVALID_EMAIL_FORMAT"
}
```

**Longitud exacta invalida (400):**
```json
{
  "code": 27,
  "description": "Field currency must be exactly 3 characters.",
  "details": [],
  "type": "INVALID_FIELD_EXACT_LENGTH"
}
```

**Fecha de expiracion anterior a fecha de pago (400):**
```json
{
  "code": 28,
  "description": "Expiration date must be on or after due date: expiration=01/01/2026, due_date=15/01/2026.",
  "details": [],
  "type": "INVALID_DATE_ORDER"
}
```

**Formato de fecha invalido (400):**
```json
{
  "code": 22,
  "description": "Field expiration must be a valid date in dd/MM/yyyy format: 32/13/2026.",
  "details": [],
  "type": "INVALID_DATE_FORMAT"
}
```

**Monto de recargo excede limite (400):**
```json
{
  "code": 23,
  "description": "Late payment amount exceeds maximum allowed limit of 1000.",
  "details": [],
  "type": "LATE_PAYMENT_AMOUNT_EXCEEDS_LIMIT"
}
```

**Merchant no autorizado (403):**
```json
{
  "code": 15,
  "description": "Merchant unauthorized.",
  "details": [],
  "type": "MERCHANT_UNAUTHORIZED"
}
```
````

{% endtab %}
{% endtabs %}

{% hint style="success" %}
Los parámetros del body que se encuentren con marcas \*  son campos obligatorios.
{% endhint %}

## <mark style="color:blue;">Request de Ejemplo</mark>

{% code overflow="wrap" %}

```json
{
  "payment_reference": "INV-2024-001",
  "concept": "Monthly service fee",
  "description": "Payment for January services",
  "currency": "USD",
  "amount": 150.00,
  "late_payment_amount": 10.00,
  "expiration": "31/12/2026",
  "due_date": "15/12/2026",
  "type": "invoice",
  "client_name": "Juan",
  "client_last_name": "Perez",
  "document_type": "DNI",
  "client_document": "12345678",
  "client_email": "juan.perez@email.com",
  "phone": "+51987654321",
  "merchant_id": 18297,
  "notification_url": "https://merchant.com/webhooks/payment"
}
```

{% endcode %}

## <mark style="color:blue;">Validación de Tipo de Documento de Identidad</mark>

Dentro de la API de Tupay, será posible encontrar distintos tipo de documento de identidad, para ello se tiene una validación por la cantidad de dígitos. [<mark style="color:blue;">**"document\_type":"DNI"**</mark>](#user-content-fn-1)[^1] <mark style="color:blue;">**,"**</mark><mark style="color:blue;">**`document`**</mark><mark style="color:blue;">**":"86970864"**</mark>

<table><thead><tr><th width="353">document_type (valores)</th><th>document (Longitud de caracteres)</th></tr></thead><tbody><tr><td>PASS</td><td>Min 9 Max 12 dígitos Alfanumerico</td></tr><tr><td>RUC</td><td>Numérico 11 dígitos</td></tr><tr><td>CE</td><td>Min 9 Max 12 dígitos Alfanumerico</td></tr><tr><td>DNI</td><td>Numérico 8 dígitos</td></tr></tbody></table>

## <mark style="color:green;">**Códigos de Errores**</mark>

Agrupamos los códigos de error en diferentes categorías para un mejor entendimiento.

* `1xx` - Errores de encabezado
* `2xx` - Error en la llamada o de configuración del comercio
* `3xx` - Errores del usuario
* `4xx` - Errores en la creación del depósito
* `5xx` - Otros errores
* `7xx` -  Errores internos

<table><thead><tr><th width="104">Código</th><th width="139">Código HTTP</th><th width="185">Tipo</th><th width="275">Mensaje</th><th width="350">Descripción</th></tr></thead><tbody><tr><td>100</td><td>401</td><td><code>INVALID_CREDENTIALS</code></td><td>Invalid Credentials</td><td>El <code>X-Login</code> enviado es incorrecto o no está activo aún.</td></tr><tr><td>101</td><td>400</td><td><code>MISSING_REQUIRED_HEADER</code></td><td>Missing or invalid format for required header {headerName}</td><td>Asegúrese de que todos los <a href="/pages/JRRfEU5bs2gZnQGC5Gv7#encabezados">encabezados</a> sean correctos.​</td></tr><tr><td>102</td><td>400</td><td><code>INVALID_SIGNATURE</code></td><td>Invalid signature</td><td>Invalid <code>Authorization</code> signature. <a href="https://docs.tupayonline.com/v/english/api-documentation/api-codes">Click here for instructions</a><br>Firma de <code>Authorization</code> inválida​. Revise <a href="/pages/hiL5qW5GiyMp935wclwm">aquí</a>.</td></tr><tr><td>103</td><td>400</td><td><code>INVALID_DATE_RANGE</code></td><td>X-Date header value out of valid range</td><td>The <code>X-Date</code> value you sent in the header is outside the allowed time-frame. <a href="https://docs.tupayonline.com/v/english/api-documentation/api-codes">Click here for details</a><br>El valor <code>X-Date</code> ​enviado en el encabezado está por fuera del marco temporal permitido. Revise <a href="/pages/JRRfEU5bs2gZnQGC5Gv7#x-date">aquí</a>.</td></tr><tr><td>104</td><td>400</td><td><code>IDEMPOTENCY_KEY_ALREADY_USED</code></td><td>Idempotency key {key} has been already used</td><td>La <code>X-Idempotency-Key</code> enviada ya ha sido usada.</td></tr><tr><td>105</td><td>400</td><td><code>EMPTY_HEADER_VALUE</code></td><td>Optional header {headerName} must not be blank</td><td>Si un encabezado opcional es enviado, puede venir vacío.</td></tr><tr><td>201</td><td>400</td><td><code>BEAN_VALIDATION_ERROR</code></td><td>Field validation error. Check details</td><td>Uno o más campos son incorrectos.</td></tr><tr><td>202</td><td>401</td><td><code>INVALID_IP</code></td><td>Unregistered IP address</td><td>Debes whitelistear la dirección IP. Revise <a href="/pages/JRRfEU5bs2gZnQGC5Gv7#ip-whitelisting">aquí</a>.​</td></tr><tr><td>203</td><td>429</td><td><code>VELOCITY_CHECK</code></td><td>Too many consecutive attempts for user (Velocity Check)</td><td>El usuario ha creado muchos depósitos en un corto periodo de tiempo.</td></tr><tr><td>204</td><td>400</td><td><code>INVALID_MEDIA_TYPE</code></td><td>Invalid media type</td><td>El formato de la llamada no es soportado. Asegúrse de que el encabezado <code>Content-Type</code> sea <code>application/json</code></td></tr><tr><td>205</td><td>400</td><td><code>MISSING_REQUEST_PARAMETER</code></td><td>Missing request parameter</td><td>La llamada carece de un parámetro importante.</td></tr><tr><td>206</td><td>400</td><td><code>MISSING_PATH_VARIABLE</code></td><td>Missing path variable</td><td>La llamada carece de una variable importante en la ruta.</td></tr><tr><td>207</td><td>400</td><td><code>INVALID_REQUEST_PARAMETER_TYPE</code></td><td>Invalid request parameter type</td><td>Se ha enviado un tipo de parametro incorrecto.</td></tr><tr><td>208</td><td>404</td><td><code>RESOURCE_NOT_FOUND</code></td><td>Resource not found</td><td>El <code>deposit_id</code> no existe.</td></tr><tr><td>209</td><td>400</td><td><code>INVALID_REQUEST_BODY</code></td><td>Invalid request body: {details}</td><td>Hay un error de sintaxis en el JSON.</td></tr><tr><td>217</td><td>403</td><td><code>FORBIDDEN_MERCHANT</code></td><td>Merchant has no authorization to use this API</td><td>Su comercio no está habilitado a utilizar esa API. Póngase en contacto con su Account Manager.</td></tr><tr><td>300</td><td>400</td><td><code>USER_BLACKLISTED</code></td><td>User blacklisted</td><td>El usuario ha cometido fraude previamente y el depósito fue declinado.</td></tr><tr><td>301</td><td>400</td><td><code>USER_GREYLISTED</code></td><td>User greylisted</td><td>Se ha detectado actividad inusual y hemos bloqueado al usuario.</td></tr><tr><td>302</td><td>400</td><td><code>USER_UNAUTHORIZED</code></td><td>User unauthorized</td><td>El usuario está bloqueado. Para más información acceda a la sección Clients del Tupay Panel.</td></tr><tr><td>303</td><td>400</td><td><code>USER_UNAUTHORIZED_REG_STATUS</code></td><td>User unauthorized due to cadastral situation</td><td>Revise la situación cadastral del usuario.</td></tr><tr><td>304</td><td>400</td><td><code>USER_LIMIT_EXCEEDED</code></td><td>The user limit has been exceeded: {TRANSACTION|DAILY|WEEKLY|MONTHLY}</td><td>Revise los limites del usuario en el Tupay Panel bajo la sección Clients.</td></tr><tr><td>305</td><td>400</td><td><code>PAYMENT_METHOD_RESTRICTED</code></td><td>Restricted payment method type</td><td>El tipo de pago se ha deshabilitado al usuario.</td></tr><tr><td>400</td><td>400</td><td><code>INVALID_AMOUNT</code></td><td>Invalid amount. The minimum is USD 2 or equivalent in local currency</td><td>El monto no ha a alcanzado el mínimo.</td></tr><tr><td>401</td><td>400</td><td><code>PAYMENT_METHOD_NOT_FOUND</code></td><td>Payment method not found</td><td>El <code>payment_method</code> enviado es incorrecto.</td></tr><tr><td>402</td><td>400</td><td><code>INVOICE_ALREADY_USED</code></td><td>Invoice already used</td><td>El <code>invoice_id</code> enviado ya ha sido usado previamente.</td></tr><tr><td>404</td><td>400</td><td><code>ERROR_CREATING_PAYMENT</code></td><td>Payment method provider unavailable</td><td>Nuestro proveedor no está disponible temporalmente, por favor intente nuevamente.</td></tr><tr><td>406</td><td>400</td><td><code>INVALID_ADDRESS</code></td><td>Invalid address</td><td>El valor <code>address</code> enviado es inválido.</td></tr><tr><td>407</td><td>400</td><td><code>INVALID_CITY</code></td><td>Invalid city</td><td>El valor <code>city</code> enviado es inválido.</td></tr><tr><td>408</td><td>400</td><td><code>PAYMENT_METHOD_LIMIT_EXCEEDED</code></td><td>Payment method limit exceeded</td><td>El <code>amount</code> excede el máximo permitido por nuestro proveedor. Intente nuevamente con un monto inferior.</td></tr><tr><td>410</td><td>400</td><td><code>PAYMENT_METHOD_MINIMUM_REQUIRED</code></td><td>Payment method minimum required</td><td>El <code>amount</code> es menor al mínimo permitido por nuestro proveedor. Intente nuevamente con un monto superior.</td></tr><tr><td>411</td><td>400</td><td><code>INVALID_USER_DOCUMENT</code></td><td>Invalid user document ID</td><td>El <code>document</code> enviado fue rechazado por nuestro proveedor. Por favor verifique su validez.</td></tr><tr><td>412</td><td>400</td><td><code>PAYMENT_METHOD_UNAVAILABLE</code></td><td>Payment Method Unavailable</td><td>El método de pago no está disponible temporalmente </td></tr><tr><td>418</td><td>400</td><td><code>MISSING_REQUIRED_FIELDS</code></td><td>Missing required fields in order to generate Deposit</td><td>La llamada carece de un campo requerido.</td></tr><tr><td>419</td><td>400</td><td><code>MISSING_PAYER_ID_OR_DOCUMENT</code></td><td>payer.id or payer.document field is missing</td><td>La llamada carece de <code>payer.id</code> o de <code>payer.document</code>.</td></tr><tr><td>500</td><td>500</td><td><code>GENERIC_ERROR</code></td><td>Oh no! Something has gone wrong. Please contact a system administrator</td><td>Error interno, por favor contacte a soporte.</td></tr><tr><td>720</td><td>400</td><td><code>MISSING_CONFIGURATION</code></td><td>Missing configuration for merchant account</td><td>Hay una configuración faltante, póngase en contacto con su Account Manager.</td></tr></tbody></table>

[^1]:


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.tupayonline.com/documentacion-de-la-api/tu-recaudo/lote-de-ordenes.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.