AI resources

Input format for migrating vaults

The input file format must be a CSV separated by commas (,), encoded in UTF-8 without BOM, and the file name must follow the convention defined in the File naming section.

Below, you can see an example:

csv
Filler,external_reference,customer_email,Filler,Filler,card_number,expiration_month,expiration_year,cardholder_name,Filler
,217307543,test1@gmail.com,,,4356141052114191,11,27,Mary Meir,
,485342254,test2@gmail.com,,,4356141052114192,02,28,Jhon Doe,

All fields are mandatory. Below are detailed descriptions of each field, its position in the CSV, and its particularities:

Position	Field	Description	Format	Example	Type
1	`filler`	Must be filled as an empty string (`""`) and not as `null` or `nil`. It is required for our internal processing.	—	`""`	Required
2	`external_reference`	Reference of the payer in the seller's system.	Alphanumeric	`ORD-123456`	Required
3	`customer_email`	Email of the paying user associated with the link.	Alphanumeric	`customer@email.com`	Required
4	`filler`	Must be filled as an empty string (`""`). It is required for our internal processing.	—	`""`	Required
5	`filler`	Must be filled as an empty string (`""`). It is required for our internal processing.	—	`""`	Required
6	`card_number`	Card number (PAN).	Numeric (between 13 and 19 digits)	`1234567812345678`	Required
7	`expiration_month`	Expiration month of the card.	Numeric (2 digits)	`01`	Required
8	`expiration_year`	Expiration year of the card, in 2-digit format (`YY`) corresponding to the 21st century (e.g.: `27` = 2027).	Numeric (2 digits)	`27`	Required
9	`cardholder_name`	Name that appears on the card.	Use only letters without accents and spaces, avoiding numbers and special characters such as `.` `,` `;` `:` `-` `_` `/` `\` `'` `"` `&` `@` `+` `(` `)` `ñ` and `ç`.	`ATILIO GARCIA`	Required
10	`filler`	Must be filled as an empty string (`""`). It is required for our internal processing.	—	`""`	Required

File naming

The .csv file name must contain only letters, numbers, hyphens (-), underscores (_), and dots (.).

Valid examples:

vault_migration_2027.csv
seller-123_customers.csv

Invalid examples:

vault migration.csv (spaces are not allowed)
file@customers.csv (the @ character is not allowed)

Validations for the input file

Below, we detail the validations that are performed during the processing of the input file:

The file must be encoded in UTF-8 without BOM.
The content limit is 400,000 lines per file. If the volume exceeds this limit, it is recommended to split it into multiple files.
The file size limit is 100 MB.
It is important to highlight that the limit to associate cards with a single email is 20 cards. If this limit is exceeded, the corresponding line will not be processed.
The card expiration date must be a future date.
The cardholder_name field must contain only letters without accents and spaces. Avoid numbers and special characters such as . , ; : - _ / \ ' " & @ + ( ) ñ ç or accented letters.
The customer_email field must have a valid email format.
The filler fields must be filled as an empty string (""), never as null or nil.

Common file errors

See the most common issues when preparing the file and how to fix them.

Problem	Invalid example	How to fix it
`cardholder_name` with not allowed characters	JOSE PEREZ S.A., MARÍA GÓMEZ, JOÃO SILVA, ANA-MARIA, CLIENTE & CIA	Use only letters without accents and spaces. For example: JOSE PEREZ, MARIA GOMEZ, JOAO SILVA.
Malformed CSV file	Entire row enclosed in quotes or different separator used	Export the file as comma-separated CSV and keep the exact header from the template.
Empty lines	A row with no data between records	Remove empty lines before sending the file.
Expired card	expiration_month=01, expiration_year=24	Send only cards with a future expiration date.
Incorrect `card_number`	Token, `card_id` or internal identifier instead of PAN	Send the plain PAN of the card, with 13 to 19 digits.
Invalid `customer_email` format	cliente@, cliente.com, cliente@@email.com	Use a standard email format, for example cliente@email.com.

PreviousEnrollment linksGenerate a secure link for the buyer to link their card to an automatic payments profile.

NextOutput format for vault migrationLearn how to generate an output for vault migrations.