BRL Ramp Migration Guide

Action required by June 15th, 2026. All existing BRL pix endorsements must be updated with additional KYC. Existing pix endorsements that have not completed the migration will transition to incomplete on June 15th.

Background

New Brazilian Central Bank (BCB) regulations under the DECRYPTO framework require that all BRL on/off-ramp activity be attributable to an identified end user. To comply, Bridge must collect additional KYC data for customers using BRL on/offramps services and pass it to our banking partner.

What’s new

Most existing BRL customers already have the KYC data needed for this migration. Our standard KYC flow collects government photo ID, and your customers’ national_id likely already serves as their CPF or CNPJ. Any missing fields can be updated either via our Customers API or by Hosted KYC Link. The fields that may be missing are as follows:

Phone number (phone): required for all customers. For business customers, phone number is also required for each UBO.
Tax ID country(identifying_information.issuing_country): the issuing country of the customer’s tax ID. Brazilian customers must enter their CPF/CNPJ; non-Brazilian customers must enter their passport number and its issuing country.
Selfie (liveness_check_selfies): required for individual customers. Developers can submit these images either via our Customers API or their customers can submit via our Hosted KYC Link.
Date of incorporation (incorporation_date): required for business customers.

If your customers already have a pix endorsement, when attempting to apply a new pix endorsement the response will surface any missing fields as errors codes (listed below) for the endorsement.

Non-Brazilian individual customers

All customers with a pix endorsement must complete the migration, including non-Brazilian individual customers. After migrating, non-Brazilian individual customers will retain access to BRL offramps (payouts) but will lose access to BRL onramps (virtual accounts / deposits). Non-Brazilian business customers will retain access to on and off ramps.

Directional endorsements (June 15, 2026)

Starting June 15, 2026, Bridge will replace the pix endorsement with two directional endorsements that reflect what BRL access a customer has:

Endorsement	Access	Residency required
`pix_onramp`	BRL deposits (virtual accounts / inbound PIX)	Yes — Brazilian residents only
`pix_offramp`	BRL payouts (outbound PIX)	No — all customers

You do not need to request these separately. When you request a pix endorsement for a customer, pix_onramp and pix_offramp are created automatically alongside it. After June 15, check these directional endorsements to determine a customer’s BRL capabilities. Non-Brazilian customers will have pix_onramp show endorsement_not_available_in_customers_region. This is expected and means they cannot receive BRL deposits. Their pix_offramp will be approved as long as they have completed the migration. The existing pix endorsement will continue to work through July 1, 2026, after which it will be deprecated. Migrate any endorsement-checking logic to use pix_onramp and pix_offramp before that date.

Requirements by Customer Type

Standard KYC Individual
Standard KYC Business
Reliance Individual
Reliance Business

Standard KYC individual customers can provide any missing data either using our Hosted KYC Link, or developers can submit directly via our Customers API.

Likely Missing	How to collect
Tax ID - For BR: Brazilian tax number (CPF) - For Non-BR: Passport ID	KYC link or `identifying_information` with `type: cpf, passport, or national_id`
Tax ID country	KYC link or `identifying_information` with `issuing_country`
Phone number	KYC link or`phone` field
Selfie	KYC link, or Customer API `liveness_check_selfies` field

Standard KYC business customers can provide any missing data either using our Hosted KYC Link, or developers can submit directly via our Customers API.

Likely missing	How to collect
Tax ID - For BR: Brazilian tax number (CNPJ) - For Non-BR: Any tax ID number	KYC link or `identifying_information` with `type: cnpj, ein or` other available options`.`
Tax ID country	KYC link or `identifying_information` with `issuing_country`
Phone number	KYC link or`phone` field
Date of incorporation	KYC link or `incorporation_date` field
UBO phone number (per UBO)	KYC link or `associated_persons.phone` field
Business Formation Document	Customer API`business_formation` field
Proof of Source of Funds Document	Customer API `proof_of_source_of_funds` field
Business Address	Customer API `registered_address` field with `street_line_1,city, country`
Proof of Address Document - Utility bill, bank statement	Customer API `proof_of_address` field

Reliance individual customers can provide any missing data either using our Hosted KYC Link, or developers can submit directly via our Customers API.

Required	How to collect
Tax ID - For BR: Brazilian tax number (CPF) - For Non-BR: Passport ID	Customer API `identifying_information` with `type: cpf, passport, or national_id`
Tax ID country	Customer API `identifying_information` with `issuing_country`
Phone number	Customer API `phone` field
Selfie	Customer API `liveness_check_selfies` field (array of base64 data URIs)
Government ID image	Customer API `identifying_information` with `image_front`

Images (gov ID and selfie) must be JPEG, PNG, or HEIC format, minimum 200x200px, maximum 15MB.

Reliance business customers can provide any missing data either using our Hosted KYC Link, or developers can submit directly via our Customers API.

Required	How to collect
Tax ID - For BR: Brazilian tax number (CNPJ) - For Non-BR: Any tax ID number	Customer API `identifying_information` with `type: cnpj, ein or` other available options`.`
Tax ID country	Customer API `identifying_information` with `issuing_country`
Phone number	Customer API `phone` field
Date of incorporation	Customer API `incorporation_date` field
UBO phone number (per UBO)	Associated Persons API`phone` field on each UBO
UBO government ID image (per UBO)	Associated Persons API`identifying_information` on each UBO with `image_front`
UBO tax number (per UBO)	Associated Persons API`identifying_information` on each UBO with type `cpf`
Business Formation Document	Customer API`business_formation` field
Proof of Source of Funds Document	Customer API `proof_of_source_of_funds` field
Business Address	Customer API `registered_address` field with `street_line_1,city, country`
Proof of Address Document - Utility bill, bank statement	Customer API `proof_of_address` field

For Developers transacting with their Developer-Customer, all of the above KYB fields will be required to continue transacting.

Migration Steps

Step 1: Submit missing KYC data for existing customers

For each existing BRL customer, check their pix endorsement status via GET /v0/customers/:id. If any additional fields are needed, the pix endorsement will show as incomplete with issue codes indicating what’s missing. Regardless of your Bridge KYC mode (Standard or Reliance), developers can submit KYC via the Customers API (and Associated Persons API for business UBOs) or their customers can submit via our Hosted KYC Link.

KYC Hosted Link: Generate a new KYC Link for the customer. The Hosted KYC flow will automatically collect any missing data (tax ID, tax ID country, phone number, selfie, date of incorporation, UBO phone numbers). The customer does not need to redo steps they have already completed.
Customers API: You can also submit this information directly via the Customers API (no KYC Hosted Link required):

Individual
Business

Request

curl --location --request PUT 'https://api.bridge.xyz/v0/customers/<customer_id>' \
--header 'Content-Type: application/json' \
--header 'Api-Key: <API Key>' \
--data '
{
  "phone": "+5511999999999",
  "identifying_information": [
    {
      "type": "cpf",
      "issuing_country": "bra",
      "number": "12345678901"
    }
  ],
  "liveness_check_selfies": [
    "data:image/jpeg;base64,..."
  ]
}'

Update the customer directly for top-level fields:

Request

curl --location --request PUT 'https://api.bridge.xyz/v0/customers/<customer_id>' \
--header 'Content-Type: application/json' \
--header 'Api-Key: <API Key>' \
--data '
{
  "phone": "+5511999999999",
  "incorporation_date": "2018-06-15",
  "identifying_information": [
    {
      "type": "cnpj",
      "issuing_country": "bra",
      "number": "12345678000195"
    }
  ]
}'

Update each UBO individually using the Associated Persons API. You only need to send the missing fields — all fields are optional:

Request

curl --location --request PUT \
  'https://api.bridge.xyz/v0/customers/<customer_id>/associated_persons/<ubo_id>' \
--header 'Content-Type: application/json' \
--header 'Api-Key: <API Key>' \
--data '
{
  "phone": "+5511888888888"
}'

Step 2: Wait for endorsement approval

After all required data is submitted, Bridge verifies the data and approves the pix endorsement. This typically takes a few minutes. You can check the status via GET /v0/customers/:id.

Request

curl --location --request GET 'https://api.bridge.xyz/v0/customers/<customer_id>' \
--header 'Api-Key: <API Key>'

The pix endorsement status will be one of:

incomplete: missing required KYC data or verification in progress. Check requirements.issues for specific missing fields.
approved: customer is ready for new BR virtual accounts and onramp transfers.

Webhooks

During the migration, you will receive webhook events as endorsement statuses change. Expect approximately 3–5 webhook events per customer through the migration flow:

Event	When
`customer.updated.status_transitioned`	When the `pix` endorsement moves to `incomplete` with new requirements
`kyc_link.updated.status_transitioned`	When a KYC Link is generated or completed (regular customers only)
`customer.updated.status_transitioned`	When the `pix` endorsement moves back to `approved` after data is submitted
`virtual_account.created`	When a new virtual account is created
`customer.updated`	When customer data is updated (e.g., `phone_number`, selfie submitted)

No new webhook event types are introduced. These are the same events you already receive for customer and virtual account lifecycle changes.

Both the first and third rows emit customer.updated.status_transitioned. To distinguish them, check the pix endorsement status in the webhook payload: incomplete for the initial transition, approved for the post-submission transition.

Missing Object in Response

Available Early May: When the pix endorsement is incomplete, the requirements.issues array will contain issue codes indicating what’s missing or what failed. The most relevant codes for this migration are: Missing data (submit to resolve):

Issue code	Meaning
`selfie_missing`	Individual customer needs to submit a selfie
`phone_number_missing`	Customer or UBO needs a phone number
`incorporation_date_missing`	Business customer needs date of incorporation
`tax_identification_number_missing`	Customer needs a Brazilian tax number (CPF or CNPJ)
`government_id_document_missing`	Customer needs to submit a government ID image
`government_id_front_image_missing`	Government ID front image is missing
`control_persons_missing`	Business customer needs UBO information

Issue codes are still being finalized and may change. There is no permanent denial — customers can always resubmit corrected data.

Timeline

Date	What happens
Now	Start submitting additional KYC data for existing customers.
By June 15th, 2026	Existing `pix` endorsements that haven’t completed migration transition to `incomplete`. `pix_onramp` and `pix_offramp` endorsements go live.
By June 30th, 2026	Non-BR individual customers will no longer be able to complete BRL virtual account deposits and onramp transfers.
July 1, 2026	`pix` endorsement deprecated. Use `pix_onramp` and `pix_offramp` for all endorsement checks.

​Background

​What’s new

​Non-Brazilian individual customers

​Directional endorsements (June 15, 2026)

​Requirements by Customer Type

​Migration Steps

​Step 1: Submit missing KYC data for existing customers

​Step 2: Wait for endorsement approval

​Webhooks

​Missing Object in Response

​Timeline

Background

What’s new

Non-Brazilian individual customers

Directional endorsements (June 15, 2026)

Requirements by Customer Type

Migration Steps

Step 1: Submit missing KYC data for existing customers

Step 2: Wait for endorsement approval

Webhooks

Missing Object in Response

Timeline