Brazil: BRL

Supported payment rails

Rail	Description	Settlement	Limit
`BR_PIX`	PIX — Brazil's instant payment platform. 24/7/365 availability.	Instant	No limit
`BR_TED`	TED — Brazil's same-day electronic funds transfer. Business days only. Cut-off ~5:00 PM BRT.	Same-day	No limit

For details on rail selection, see Payment rail reference.

Beneficiary identity

When creating a beneficiary identity for BRL payments, provide the following fields. See Create and manage identities for the API workflow.

The required fields depend on whether the beneficiary is a business or an individual.

Business beneficiary

Applies to B2B, B2B2B, and C2B2B use cases. Submit a business identity.

Field	Required	Type	Constraints
`businessName`	Required	STRING	1–140 characters.
`address.streetAddress`	Required	ARRAY of STRING	Each item 1–70 characters.
`address.city`	Required	STRING	1–140 characters.
`address.stateOrProvince`	Required	STRING	1–140 characters.
`address.postalCode`	Required	STRING	3–15 characters.
`address.country`	Required	STRING	Two-letter ISO 3166-1 alpha-2 country code.
`email`	Required	STRING	6–255 characters. Valid email format.
`phone`	Required	STRING	8–16 characters. Pattern: `^\+[1-9]\d+$` (E.164 format).
`registration`	Required	ARRAY of OBJECT	Each item: `number` (3–35 characters) and `type` (one of `INCORPORATION_CERTIFICATE`, `TAX_ID`). At least one registration entry is required.
`incorporationCountry`	Required	STRING	Two-letter ISO 3166-1 alpha-2 code of the country where the business was incorporated.

Individual beneficiary

Applies to B2C, B2B2C, and C2B2C use cases. Submit an individual identity.

Field	Required	Type	Constraints
`firstName`	Required	STRING	1–140 characters.
`lastName`	Required	STRING	1–140 characters.
`dateOfBirth`	Required	DATE	ISO 8601 date (YYYY-MM-DD).
`address.streetAddress`	Required	ARRAY of STRING	Each item 1–70 characters.
`address.city`	Required	STRING	1–140 characters.
`address.stateOrProvince`	Required	STRING	1–140 characters.
`address.postalCode`	Required	STRING	3–15 characters.
`address.country`	Required	STRING	Two-letter ISO 3166-1 alpha-2 country code.
`email`	Required	STRING	6–255 characters. Valid email format.
`phone`	Required	STRING	8–16 characters. Pattern: `^\+[1-9]\d+$` (E.164 format).
`identityDocuments`	Required	ARRAY of OBJECT	Each item: `idNumber` (3–35 characters) and `idType` (one of `ALIEN_REGISTRATION`, `CUSTOMER_ID`, `DRIVERS_LICENSE`, `EMPLOYEE_ID`, `NATIONAL_ID_NUMBER`, `PASSPORT`, `SSN`, `TAX_ID`).
`citizenship`	Required	STRING	Two-letter ISO 3166-1 alpha-2 country code of the individual's nationality.

Beneficiary financial instrument

When creating a financial instrument for BRL payouts, set currency: BRL and select the financial instrument type based on the rail. See Create and manage financial instruments for the API workflow.

PIX

Set financialInstrumentType: BR_PIX. Provide the following fields in the brPix payment rail object.

Field	Required	Type	Constraints
`bankName`	Required	STRING	2–140 characters.
`bankCode`	Required	STRING	8–11 characters. BICFI code.
`branchNumber`	Required	STRING	4–6 characters. Pattern: `^\d{4}(-?[0-9X])?$`
`pixKey`	Required	STRING	6–77 characters. A PIX key, which can be a CPF, CNPJ, email, phone number, or random EVP UUID.
`pixKeyType`	Required	ENUM	One of: `CPF` (individual taxpayer registry number), `CNPJ` (legal entity identification number), `EMAIL`, `PHONE`, `EVP` (random bank-issued key).

TED

Set financialInstrumentType: BR_TED. Provide the following fields in the brTed payment rail object.

Field	Required	Type	Constraints
`bankName`	Required	STRING	2–140 characters.
`bankCode`	Required	STRING	8–11 characters. BICFI code.
`branchNumber`	Required	STRING	4–6 characters. Pattern: `^\d{4}(-?[0-9X])?$`
`accountNumber`	Required	STRING	5–14 digits.
`accountType`	Required	ENUM	One of: `CHECKING`, `SAVINGS`.

Originator identity

When creating an originator identity for BRL payments, provide the following fields. The required fields depend on whether the originator is a business or an individual.

Business originator

Applies to B2B, B2B2B, B2B2C, and B2C use cases. Submit a business identity.

Field	Required	Type	Constraints
`businessName`	Required	STRING	1–140 characters.
`address.streetAddress`	Required	ARRAY of STRING	Each item 1–70 characters.
`address.city`	Required	STRING	1–140 characters.
`address.stateOrProvince`	Required	STRING	1–140 characters.
`address.postalCode`	Required	STRING	3–15 characters.
`address.country`	Required	STRING	Two-letter ISO 3166-1 alpha-2 country code.
`email`	Required	STRING	6–255 characters. Valid email format.
`phone`	Required	STRING	8–16 characters. Pattern: `^\+[1-9]\d+$` (E.164 format).
`registration`	Required	ARRAY of OBJECT	Each item: `number` (3–35 characters) and `type` (one of `INCORPORATION_CERTIFICATE`, `TAX_ID`). At least one registration entry is required.
`incorporationCountry`	Required	STRING	Two-letter ISO 3166-1 alpha-2 code.
`legalEntityType`	Required for `BR_PIX` only	ENUM	One of: `BANK_CENTRAL`, `BANK_COMMERCIAL`, `PAYMENT_INSTITUTION`, `CORPORATE_PRIVATE`, `CORPORATE_PUBLIC`, `GOVERNMENT_ENTITY`, `NON_PROFIT`, `SOLE_TRADER`.

Individual originator

Applies to C2B2B and C2B2C use cases. Submit an individual identity.

Field	Required	Type	Constraints
`firstName`	Required	STRING	1–140 characters.
`lastName`	Required	STRING	1–140 characters.
`dateOfBirth`	Required	DATE	ISO 8601 date (YYYY-MM-DD).
`countryOfBirth`	Required	STRING	Two-letter ISO 3166-1 alpha-2 country code.
`address.streetAddress`	Required	ARRAY of STRING	Each item 1–70 characters.
`address.city`	Required	STRING	1–140 characters.
`address.stateOrProvince`	Required	STRING	1–140 characters.
`address.postalCode`	Required	STRING	3–15 characters.
`address.country`	Required	STRING	Two-letter ISO 3166-1 alpha-2 country code.
`email`	Required for `BR_PIX` only	STRING	6–255 characters. Valid email format.
`phone`	Required for `BR_PIX` only	STRING	8–16 characters. Pattern: `^\+[1-9]\d+$` (E.164 format).
`identityDocuments`	Required	ARRAY of OBJECT	Each item: `idNumber` (3–35 characters) and `idType` (one of `ALIEN_REGISTRATION`, `CUSTOMER_ID`, `DRIVERS_LICENSE`, `EMPLOYEE_ID`, `NATIONAL_ID_NUMBER`, `PASSPORT`, `SSN`, `TAX_ID`).
`citizenship`	Required	STRING	Two-letter ISO 3166-1 alpha-2 country code.

Transaction fields

When creating a payment, provide the following fields. See Create a payment for the API workflow.

Field	Required	Type	Constraints
`purposeCode`	Required	ENUM	See Purpose of payment codes below.
`paymentMemo`	Optional	STRING	0–120 characters.

Purpose of payment codes

Code	Description
`COMP`	Compensation payment
`FAMI`	Family maintenance
`INVS`	Investment and securities
`OTHR`	Other
`SUPP`	Supplier payment

Verifying requirements for your scenario

For the exact fields required for your specific use case and payment rail, use the Payload Schema Utility.