Payer data & documents

Every payment method needs some data about the person who pays: name, email, phone, identity document and, for some methods, address or bank fields. This page explains how to know which fields to send and how they are validated.

Where the list of fields comes from

The authoritative list is always the option you chose in Get payment methods:

Option field	Use it to
required_fields	Know every field you must send for this method.
mandatory_fields	Get each field’s detail: type, fieldRegex (format), fieldLabel, and options when only some values are accepted (send one of the options[].key).
document_types	Build the document selector: send id as document_key, and check document_number against regex. A document_key outside this list is refused with 422.

Send every required field at the root of the Create a deposit body, as strings of up to 255 characters. Read the lists per option: the same country can require different fields, and accept different documents, on different methods.

The usual fields

Field	Rules
first_name, last_name	Letters, numbers, spaces, hyphens, apostrophes and periods. Example message: “The first name may only contain letters, numbers, spaces, hyphens, apostrophes and periods.”
middle_name, second_last_name	Same rules, when the method asks for them.
email	Valid format. In production the email’s domain must also be able to receive mail.
phone	A real phone number valid for the deposit’s country. A national number is read in the deposit’s country; send it in international format (+52…, +56…) to be safe. It is normalised to international (E.164) format.
document_key	One of the document_types[].id of the option.
document_number	The format of the document type and, where the country has one, a valid check digit (see below).
address, city, region	When the method asks for them. Plain text, no HTML.
zip_code	When the method asks for it. In production it must match the country’s postal code pattern.
Method-specific fields	For example cbu (Argentina, 22 digits). Follow the field’s fieldRegex.

Free-text fields must not contain HTML tags (“This field cannot contain HTML tags.”).

Real validation messages

These are 422 responses: nothing was created or charged.

{
  "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)."]
  }
}

Above: a United States phone number sent on a deposit in Mexico.

Field	Example of a refused value	Message
document_number	A passport number in the wrong format, Mexico	”The document number does not match the expected format for Passport (PASS, MX)“
document_number	12.345.678-0 as a Chilean RUT	”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.”

Documents by country

The table lists document types Cashela’s payment methods accept in each country, as a guide for your form. Each method accepts only some of them, so always use the option’s document_types.

Country	Document types (document_key)	Check digit validated
Argentina (ARG)	DNI, CUIL, CUIT	CUIL, CUIT
Bolivia (BOL)	CI	—
Brazil (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	—
Mexico (MEX)	CURP, RFC, IFE, PASS	—
Paraguay (PRY)	CIC	—
Peru (PER)	DNI, CE, RUC, PASS	RUC

For example, on one Argentine bank method only CUIT is accepted, and DNI or CUIL are refused with 422, even though other Argentine methods accept them.

Documents that need a manual review

When a document cannot be verified automatically (a type or country without a verified format or check digit), the deposit is not refused: it is created with status INREVIEW, without a payment link, and is not sent for payment until Cashela reviews it. Plan your flow for this status. See Get a deposit & statuses.

Use real data from the deposit’s country

The payer’s data must belong to the deposit’s country: a phone number, document and address of that country. Generic or test values (for example a generic tax id, such as Mexico’s XAXX010101000) can be refused by the payment network even when they pass format validation. In that case you receive 422 PARTNER_PAYIN_PROVIDER_REJECTED, sometimes with provider_reason.field naming the field to correct:

{
  "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."
  }
}

Do not retry the same data: correct it and create the deposit with a new external_identifier.

Production is stricter than sandbox

Production applies strict validation: phone valid for the deposit’s country, document format and check digit, deliverable email and postal code pattern. Sandbox may accept data that production rejects. Test in sandbox with realistic data in the format of each country, and handle every 422 in your form.