Lote de Ordenes

Endpoint Creación Lote Individual

STAGING POST https://turecaudo-api-stg.tupaypagos.com/v1/payment-orders

PRODUCTION POST https://turecaudo-api.tupaypagos.com/v1/payment-orders

Headers

Name	Type	Description
Content-Type	string	application/json
X-Date*	string	Fecha según el estándar ISO8601 formato: yyyy-MM-dd'T'HH:mm:ssZ
X-Login*	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 *	String	Identificador único de la orden definido por el merchant. Debe ser único por merchant.
concept *	String	Concepto o título del pago.
description *	String	Descripción detallada del pago.
currency *	String (ISO 4217)	Código de moneda en formato de 3 caracteres (ej: USD, PEN).
amount *	Number (Decimal)	Monto principal del pago.
late_payment_amount	Number (Decimal)	Recargo aplicable por pago tardío.
expiration *	String (Date - dd/MM/yyyy)	Fecha de expiración de la orden.
due_date *	String (Date - dd/MM/yyyy)	Fecha de vencimiento del pago.
type *	String	Tipo de orden de pago.
client_name *	String	Nombre del cliente.
client_last_name *	String	Apellido del cliente.
document_type *	String	Tipo de documento del cliente (DNI, RUC, CE, PASS).
client_document *	String	Número de documento del cliente.
client_email *	String (Email)	Correo electrónico del cliente.
phone	String	Teléfono del cliente.
merchant_id *	Integer	Identificador del merchant autenticado.
notification_url	String (URL)	URL para recibir notificaciones webhook.

201 Solicitud de depósito creada exitosamente

{
  "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": "[email protected]",
  "phone": "[phone]",
  "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
  }
}

401: Unauthorized Invalid signature

400: Bad Request La solictud de deposito fallo

Los parámetros del body que se encuentren con marcas * son campos obligatorios.

Request de Ejemplo

{
  "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": "[email protected]",
  "phone": "[phone]",
  "merchant_id": 18297,
  "notification_url": "https://merchant.com/webhooks/payment"
}

Validación de Tipo de Documento de Identidad

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. "document_type":"DNI" ,"document":"86970864"

document_type (valores)	document (Longitud de caracteres)
PASS	Min 9 Max 12 dígitos Alfanumerico
RUC	Numérico 11 dígitos
CE	Min 9 Max 12 dígitos Alfanumerico
DNI	Numérico 8 dígitos

Códigos de Errores

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

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