Datos del pagador y documentos

Cada método de pago necesita datos de la persona que paga: nombre, correo, teléfono, documento de identidad y, en algunos métodos, dirección o datos bancarios. Esta página explica cómo saber qué campos enviar y cómo se validan.

De dónde sale la lista de campos

La lista que manda es siempre la de la opción que elegiste en Obtener métodos de pago:

Campo de la opción	Para qué sirve
`required_fields`	Saber todos los campos que debes enviar para este método.
`mandatory_fields`	Obtener el detalle de cada campo: `type`, `fieldRegex` (formato), `fieldLabel` y `options` cuando solo se aceptan algunos valores (envía uno de los `options[].key`).
`document_types`	Construir el selector de documento: envía `id` como `document_key` y comprueba `document_number` con `regex`. Un `document_key` fuera de esta lista se rechaza con `422`.

Envía todos los campos obligatorios en la raíz del cuerpo de Crear un depósito, como strings de hasta 255 caracteres. Lee las listas por opción: un mismo país puede exigir campos distintos y aceptar documentos distintos según el método.

Los campos habituales

Campo	Reglas
`first_name`, `last_name`	Letras, números, espacios, guiones, apóstrofos y puntos. Mensaje de ejemplo: “The first name may only contain letters, numbers, spaces, hyphens, apostrophes and periods.”
`middle_name`, `second_last_name`	Mismas reglas, cuando el método los pide.
`email`	Formato válido. En producción, el dominio del correo también debe poder recibir correo.
`phone`	Un número de teléfono real y válido para el país del depósito. Un número nacional se interpreta en el país del depósito; envíalo en formato internacional (`+52…`, `+56…`) para ir sobre seguro. Se normaliza a formato internacional (E.164).
`document_key`	Uno de los `document_types[].id` de la opción.
`document_number`	El formato del tipo de documento y, cuando el país lo tiene, un dígito verificador válido (ver abajo).
`address`, `city`, `region`	Cuando el método los pide. Texto plano, sin HTML.
`zip_code`	Cuando el método lo pide. En producción debe cumplir el patrón de código postal del país.
Campos propios del método	Por ejemplo `cbu` (Argentina, 22 dígitos). Sigue el `fieldRegex` del campo.

Los campos de texto libre no pueden contener etiquetas HTML (“This field cannot contain HTML tags.”).

Mensajes de validación reales

Son respuestas 422: no se creó ni se cobró nada.

{
  "success": false,
  "status": false,
  "message": "Enter a valid phone number for the selected country (for example, +52 222 123 4567).",
  "errors": {
    "phone": ["Enter a valid phone number for the selected country (for example, +52 222 123 4567)."]
  }
}

Arriba: un teléfono de Estados Unidos enviado en un depósito en México.

Campo	Ejemplo de valor rechazado	Mensaje
`document_number`	Un pasaporte con formato incorrecto, México	”The document number does not match the expected format for Passport (PASS, MX)“
`document_number`	`12.345.678-0` como RUT chileno	”The document number is not a valid Tax Identification Number (RUT, CL): its length or check digit does not match.”
`email`	`maria.perez@`	”The email must be a valid email address.”
`zip_code`	`ABC`	”The zip code format is invalid.”

Documentos por país

La tabla lista los tipos de documento que aceptan los métodos de pago de Cashela en cada país, como guía para tu formulario. Cada método acepta solo algunos, así que usa siempre document_types de la opción.

País	Tipos de documento (`document_key`)	Con dígito verificador
Argentina (`ARG`)	`DNI`, `CUIL`, `CUIT`	`CUIL`, `CUIT`
Bolivia (`BOL`)	`CI`	—
Brasil (`BRA`)	`CPF`	`CPF`
Chile (`CHL`)	`RUT`, `RUN`, `ID`	`RUT`, `RUN`, `ID`
Colombia (`COL`)	`CC`, `CE`, `NIT`	`NIT`
Ecuador (`ECU`)	`CC`, `CI`, `RUC`	`CC`, `CI`, `RUC`
Guatemala (`GTM`)	`DPI`	—
México (`MEX`)	`CURP`, `RFC`, `IFE`, `PASS`	—
Paraguay (`PRY`)	`CIC`	—
Perú (`PER`)	`DNI`, `CE`, `RUC`, `PASS`	`RUC`

Por ejemplo, en un método bancario de Argentina solo se acepta CUIT, y DNI o CUIL se rechazan con 422, aunque otros métodos argentinos sí los aceptan.

Documentos que necesitan revisión manual

Cuando un documento no se puede verificar automáticamente (un tipo o país sin formato o dígito verificador comprobado), el depósito no se rechaza: se crea en estado INREVIEW, sin enlace de pago, y no se envía a cobro hasta que Cashela lo revise. Prepara tu flujo para este estado. Ver Consultar un depósito y estados.

Usa datos reales del país del depósito

Los datos del pagador deben ser del país del depósito: teléfono, documento y dirección de ese país. Los valores genéricos o de prueba (por ejemplo un RFC genérico, como XAXX010101000 en México) pueden ser rechazados por la red de pago aunque pasen la validación de formato. En ese caso recibes 422 PARTNER_PAYIN_PROVIDER_REJECTED, a veces con provider_reason.field indicando el campo a corregir:

{
  "success": false,
  "message": "The phone is not valid for this payment method.",
  "code": "PARTNER_PAYIN_PROVIDER_REJECTED",
  "provider_reason": {
    "code": "INVALID_FIELD",
    "field": "phone",
    "message": "The phone is not valid for this payment method."
  }
}

No reintentes con los mismos datos: corrígelos y crea el depósito con un external_identifier nuevo.