File-based payments (PayOut)

Welcome to Orkestral's File-based Payments guide.

Follow the instructions below to prepare, validate, and upload files containing multiple outgoing payments (PayOuts) by PIX or bank transfer.

Objective

Guide clients through making batch payments in the Orkestral portal, including:

• preparing the file;
• using the available templates;
• uploading through the portal;
• correcting validation errors;
• monitoring processed transactions.

Overview

The File-based Payments feature lets you submit several PayOuts in a single operation.

Each row in the file represents an independent payment. After upload:

• Orkestral validates the structure and content of every row;
• a valid file is accepted for processing;
• each row becomes a PayOut transaction;
• the payment is sent to the PSP specified in that row;
• the result can be monitored in the Transaction Report.

Two templates are available:

• PIX;
• Bank Transfer.

:::warning Important

The “File uploaded successfully!” message confirms that the file was validated and accepted. It does not mean that every payment has already been completed.

:::

Before you begin

To use this feature, you must:

• have an active Orkestral account;
• be linked to the merchant responsible for the payments;
• have access to Reports > Payout upload;
• have an active, contracted PayOut PSP with valid credentials;
• have sufficient balance and limits available at the PSP;
• have the correct beneficiary information;
• use the template for the intended payment type.

The PSP and currency specified in the file must be enabled for the merchant.

Formats and limits

Characteristic	Rule
Accepted formats	.csv, .xls, and .xlsx
Size	Less than 15 MB
Files per upload	One file
Payment types	PIX or bank transfer
Header	Must be on the first row
Minimum content	Header and at least one payment row
Excel files	Only the first worksheet is processed
CSV files	Must use a comma as the delimiter

UTF-8 encoding is recommended for CSV files.

The platform does not publish a row limit. For very large batches, contact Orkestral about the recommended volume.

Important rules

• Use the template available on the upload page.
• Do not rename, remove, add, or reorder columns.
• Do not mix PIX payments and bank transfers in the same file.
• Do not leave blank rows between payments.
• Do not use merged cells.
• Do not use formulas in cells.
• Do not submit password-protected or encrypted files.
• Enter amounts as integers, without currency symbols or separators.
• Keep documents, accounts, and keys unformatted when the template requires digits only.
• Do not include passwords, tokens, or other credentials in the file.

Download the template

1. Sign in to the Orkestral platform.
2. Open Reports in the side menu.
3. Select Payout upload.
4. Find the instructions displayed at the top of the page.
5. Select:
   • PIX template; or
   • bank transfer template.
6. Save a copy of the template.
7. Fill in only the rows intended for payments.

The template provided by the platform must be used as the primary layout reference.

PIX file

The PIX file must contain exactly the following header:

AMOUNT,CURRENCY,NAME,LAST NAME,DOCUMENT,DOCUMENT TYPE,PIX KEY,PSP

PIX file columns

Column	Required	Description
AMOUNT	Yes	Payment amount in cents, as an integer greater than zero. For example, 1000 represents BRL 10.00
CURRENCY	Yes	Uppercase currency code. Use BRL for the current PIX flow
NAME	Yes	Beneficiary's first name
LAST NAME	Yes	Beneficiary's last name
DOCUMENT	Yes	Beneficiary's document number, containing digits only
DOCUMENT TYPE	Yes	Document type enabled for the integration. The currently confirmed flow uses CPF
PIX KEY	Yes	Beneficiary's PIX key
PSP	Yes	PSP responsible for the payment. Use WEPAYMENTS for the current PIX flow

The PIX key must be active and recognized by the PSP. Its format may be a document number, phone number, email address, or random key.

PIX example

AMOUNT,CURRENCY,NAME,LAST NAME,DOCUMENT,DOCUMENT TYPE,PIX KEY,PSP
1000,BRL,Joao,Silva,51584112808,CPF,42362893855,WEPAYMENTS

This example is for illustration only. Use valid beneficiary information and the settings available for your merchant.

Bank transfer file

The bank transfer file must contain exactly the following header:

AMOUNT,CURRENCY,NAME,LAST NAME,EMAIL,DATE OF BIRTH,DOCUMENT,DOCUMENT TYPE,BANK NAME,BANK CODE,AGENCY CODE,AGENCY DIGIT,ACCOUNT NUMBER,ACCOUNT DIGIT,ACCOUNT TYPE,PSP

Bank transfer file columns

Column	Required	Description
AMOUNT	Yes	Payment amount in cents, as an integer greater than zero
CURRENCY	Yes	Uppercase currency code enabled for the PSP. Example: COP
NAME	Yes	Beneficiary's first name
LAST NAME	Yes	Beneficiary's last name
EMAIL	Yes	Beneficiary's valid email address
DATE OF BIRTH	Yes	Beneficiary's date of birth
DOCUMENT	Yes	Beneficiary's document number
DOCUMENT TYPE	Yes	Document type accepted by the PSP and the country of operation. Currently confirmed examples: CC, TI, DNI, and CI
BANK NAME	Yes	Bank name as listed in the catalog accepted by Orkestral
BANK CODE	Yes	Numeric bank code
AGENCY CODE	Yes	Numeric branch code
AGENCY DIGIT	Yes	Numeric branch check digit
ACCOUNT NUMBER	Yes	Beneficiary's account number
ACCOUNT DIGIT	Yes	Numeric account check digit
ACCOUNT TYPE	Yes	Account type according to the PSP
PSP	Yes	PSP responsible for the payment. Use the PSP configured for the merchant, such as KUSHKI or PAYVALIDA

Accepted date formats

The DATE OF BIRTH field accepts:

• dd/MM/yyyy, for example 25/10/1990;
• yyyy-MM-dd, for example 1990-10-25;
• yyyyMMdd, for example 19901025;
• a native Excel date.

Account types

Values vary by PSP.

For Kushki, you can use:

• CC;
• CA;
• CB;
• TD;
• NC;
• CV;
• DE;
• CM.

For Payvalida, you can use:

• AHORRO;
• CORRIENTE;
• MONETARIA.

Use only an account type compatible with the PSP, country, and beneficiary's bank.

Bank transfer example

AMOUNT,CURRENCY,NAME,LAST NAME,EMAIL,DATE OF BIRTH,DOCUMENT,DOCUMENT TYPE,BANK NAME,BANK CODE,AGENCY CODE,AGENCY DIGIT,ACCOUNT NUMBER,ACCOUNT DIGIT,ACCOUNT TYPE,PSP
1000,COP,Ana,Souza,ana.souza@example.com,1990-10-25,43750860,CC,BANCO DE OCCIDENTE,1,1,7,987654321,0,CORRIENTE,PAYVALIDA

This example is for illustration only. The bank details, account type, currency, and PSP must match the merchant configuration.

Upload the file

1. Sign in to the Orkestral platform.
2. Open Reports in the side menu.
3. Select Payout upload.
4. Under Select the transaction type, choose:
   • PIX; or
   • Bank Transfer.
5. Drag the file to the indicated area or click to select it.
6. Confirm that the file name is displayed.
7. Select Import.
8. Wait for validation.

note

The platform identifies the payment type from the file header. Therefore, selecting a tab does not correct a file completed using the wrong template.

File validation

Orkestral validates every row before accepting the file.

If there is any structural or data entry error:

• the entire file is rejected;
• no payment is queued;
• errors are grouped by category;
• the page displays the cells that must be corrected.

A reference such as A2 indicates:

• column A;
• row 2.

After correcting the file, select Back, choose it again, and submit a new upload.

Structural errors

Message	Possible cause	How to correct
Choose a file to upload	No file was selected	Select a file before choosing Import
The file must be smaller than 15 MB	File exceeds the limit	Split the content into smaller files
This file has no content	Empty file or no payments	Include the header and at least one payment row
Invalid file. Use the template file as a base	Incorrect header or incompatible structure	Create a new copy from the template
Required columns are missing	One or more columns were removed	Restore every column from the template
Unsupported format	Extension other than CSV, XLS, or XLSX	Save the file in an accepted format

Data entry errors

Technical code	Displayed message	How to correct
INVALID_NUMBER	Invalid number	Enter only a valid numeric value
BLANK_STRING	Empty cell	Complete the required field
INVALID_CURRENCY	Incorrect currency	Use the currency enabled for the PSP
INVALID_NUMBER_OR_BLANK_STRING	Invalid number or empty cell	Complete the field without incompatible characters
INVALID_PSP	Incorrect PSP	Use the configured PSP name
INVALID_EMAIL	Invalid email	Correct the email format
INVALID_DATE_OF_BIRTH	Invalid date of birth	Use one of the accepted formats
INVALID_ACCOUNT_TYPE	Invalid account type	Use an account type compatible with the PSP
INVALID_BANK	Invalid bank	Use a bank name recognized by the platform
INVALID_DOCUMENT_TYPE	Invalid document type	Use a type compatible with the country and PSP
FILE_ERROR	Error in the uploaded file	Check the number, order, and content of the columns

Payment processing

After the file is accepted, processing occurs asynchronously:

File uploaded
      ↓
Validation completed
      ↓
File accepted for processing
      ↓
One PayOut created per row
      ↓
Sent to the selected PSP
      ↓
Updated in the Transaction Report

Each row receives its own transaction identifier.

The PSP specified in the PSP column is used directly. This flow does not use Payment Flow to select another provider and has no automatic fallback between PSPs.

A failure in one row does not necessarily stop the remaining rows from being processed. A file may therefore produce both completed and failed payments.

Monitor payments

After the file is accepted, the platform redirects the user to the Transaction Report.

To monitor the payments:

1. Open Reports > Transactions.
2. In the Transaction type filter, select PayOut.
3. Use date, PSP, currency, or status to locate the transactions.
4. Open the details of each payment.

PayOut statuses

Status	Meaning
Processing	The PSP received the request, but the final result is still pending
Complete	The payment was settled. The detailed status may be displayed as Withdrawn
Failed	The payment was denied or an error occurred during processing

The status may be updated later by the PSP.

info

The portal currently does not display a batch identifier or a public page with the overall file status. Monitoring is performed through individual transactions.

Correction and resubmission

File rejected during validation

If the file does not display the successful upload message:

1. Correct every indicated cell.
2. Save the file.
3. Return to the upload page.
4. Upload the complete file again.

Because the file was rejected, no PayOut was queued.

File already accepted

danger

Do not upload the complete file again without first checking the Transaction Report. A new upload creates new identifiers and may duplicate payments that have already been executed.

If only some rows fail:

1. Identify the transactions that were already created.
2. Confirm which payments were not completed.
3. Create a new file containing only the payments that actually require another attempt.
4. If you are unsure, contact Orkestral support before resubmitting.

Security best practices

Files may contain beneficiaries' documents and banking information.

• Restrict access to the files.
• Do not send files through public or unauthorized channels.
• Do not include banking information in logs.
• Do not include passwords, tokens, or PSP credentials.
• Store files only for as long as necessary.
• Delete local copies when they are no longer needed.
• Confirm the source and integrity of the data before upload.
• Use only trusted devices and networks.
• Keep procedures aligned with applicable data protection rules.

Frequently asked questions

Does “File uploaded successfully” mean that every payment has been completed?

No. It confirms that the file was validated and accepted. Payments are processed afterward.

Can I mix PIX and bank transfers in the same file?

No. Use a separate file and template for each payment type.

Can I change the order or names of the columns?

No. The header must remain exactly as provided in the template.

Can I resubmit an accepted file?

Only after confirming which transactions have already been created. Resubmitting the entire file may create duplicate payments.

Where can I monitor the results?

Under Reports > Transactions, using the PayOut filter.