Onboarding and sending documents via link

Using an easier onboarding process.

After creating a BaaS subaccount, check the required documents and direct the account holder to the onboardingUrl returned by Asaas when this submission method is available.

The link allows the documentation to be sent and, when applicable, the selfie to be taken for facial recognition. In this flow, the experience must follow the Asaas identification rules applicable to the BaaS model.

🚧
Remember:
The BaaS format must be aligned and deployed in advance by your account manager. Creating Asaas accounts using the methods listed below without prior definition of how they work in the BaaS format will result in subaccounts being created outside this structure.
In Sandbox, to test it, just contact Support and request that it be enabled.

How it works

The onboardingUrl attribute defines how each document must be sent.

%%{init: {"flowchart": {"nodeSpacing": 28,"rankSpacing": 32,"diagramPadding": 8,"padding": 10}}}%%
flowchart TD
    A["Create the subaccount"] --> B["Wait at least<br/>15 seconds"]
    B --> C["Check pending<br/>documents"]
    C --> D{"Has onboardingUrl?"}

    D --> DSim(("Yes"))
    D --> DNao(("No"))

    DSim --> E["Redirect the account holder<br/>to the link"]
    DNao --> F["Send the document<br/>via the API"]

    E --> G["Track the review<br/>via Webhooks"]
    F --> G
    G --> H["Account approved"]

    classDef inicio fill:#DBEAFE,stroke:#2563EB,color:#1E3A8A,stroke-width:3px,font-size:17px
    classDef decisao fill:#FEF3C7,stroke:#D97706,color:#78350F,stroke-width:3px,font-size:17px
    classDef validacao fill:#E0F2FE,stroke:#0284C7,color:#0C4A6E,stroke-width:2px,font-size:17px
    classDef sucesso fill:#DCFCE7,stroke:#16A34A,color:#14532D,stroke-width:3px,font-size:17px

    classDef respostaSim fill:#22C55E,stroke:#15803D,color:#FFFFFF,stroke-width:3px,font-size:16px
    classDef respostaNao fill:#EF4444,stroke:#B91C1C,color:#FFFFFF,stroke-width:3px,font-size:16px

    class A inicio
    class B,C,E,F,G validacao
    class D decisao
    class H sucesso

    class DSim respostaSim
    class DNao respostaNao

    linkStyle default stroke:#94A3B8,stroke-width:2px
    linkStyle 3 stroke:#22C55E,stroke-width:4px
    linkStyle 4 stroke:#EF4444,stroke-width:4px

1. Check the pending documents

After creating the subaccount, check which documents are required for approval.

GET /v3/myAccount/documents
See the full reference for this endpoint

🚧
Attention
After creating a subaccount, set a 15-second timeout before calling this endpoint.
If the call to check the subsequent documents is made right after the account is created, you will probably be told to send non-mandatory documents, because the account creation and validation with the Federal Revenue Service has not yet been completed.
The time is only needed for validation, collection of the required data, and account creation.

The response lists the documents or groups of documents related to the registration review. The main fields to define the next action are:

Field	How to use it
`id`	Identifies the document or group of documents.
`status`	Indicates the current status of the document.
`type`	Identifies the requested type.
`description`	Provides guidance on the required documentation.
`onboardingUrl`	Defines submission via an external link when present.
`documents`	Shows the file sent for the group.

2. Send each document using the indicated method

Document with `onboardingUrl`

When the document has an onboardingUrl, direct the account holder to that address.

This document must be sent via the external link. Do not replace this flow with POST /v3/myAccount/documents/{id}.

Example layout of the page for sending documents via link

For individuals and businesses, identification documents and a selfie of the account holder or legal representative may be requested. Associations may also require additional documents sent via the API.

📘
If one of the documents sent through the external link is rejected, a new link will be generated.

Depending on the conditions of the review, Asaas may request new additional documents. In this case, document groups will be opened with the type CUSTOM and their description in the description attribute.

Document without `onboardingUrl`

When the document does not have an onboardingUrl and allows submission via the API, use the group id:

POST /v3/myAccount/documents/{id}
See the full reference for this endpoint

🚧
One file per group
Each document group id accepts only one valid file at a time. When you send a new file for the same id, the previously sent file is replaced, expires, and is no longer considered in the review.

📘
After the document is sent, it will have its own specific id, and it is through this id that you can remove the sent document (not through the document group id).

The id returned for the file is also used in document management operations:

Action	Endpoint	Reference
View	`GET /v3/myAccount/documents/files/{id}`	View document sent
Update	`POST /v3/myAccount/documents/files/{id}`	Update sent document
Remove	`DELETE /v3/myAccount/documents/files/{id}`	Remove sent document

3. Track the review via Webhooks

After submission, the account goes under review, which can take up to 48 hours.

Use the account status Webhooks to track changes in the documentation and in the subaccount's general approval. This avoids recurring API queries just to check for status changes.

See the events to check account status.

When documentation is rejected or new information is required, update your onboarding journey according to the status received.

4. Check the registration status when needed

To retrieve the subaccount's current status on demand, use:

GET /v3/myAccount/status
See the full reference for this endpoint

{
  "id": "afb621a5-9030-4b4d-88e8-5b80306d13350",
  "commercialInfo": "AWAITING_APPROVAL",
  "bankAccountInfo": "APPROVED",
  "documentation": "APPROVED",
  "general": "APPROVED"
}

The API returns the status of the business data, bank data, documentation, and general approval separately.

To track changes automatically, keep using Webhooks instead of querying this endpoint repeatedly.

📘
The account will be 100% approved when the general attribute returns APPROVED.

The possible values and the full interpretation of each attribute are available in the registration status reference.

If you need to fix the business data

If the review indicates an inconsistency in the business data, use:

POST /v3/myAccount/commercialInfo
See the full reference for this endpoint

Send all the data required by the endpoint again. The incomeValue field is required, and certain changes may trigger a new review of the account.

Proof of life

In onboarding via link, proof of life is done by sending and approving the selfie.

Initially, the account is enabled to create charges and make transfers. In approximately 90% of cases, proof of life is approved within 5 minutes.

Next steps

Updated 18 days ago

Did this page help you?

Remember:

How it works

1. Check the pending documents

Attention

2. Send each document using the indicated method

Document with onboardingUrl

Document without onboardingUrl

One file per group

3. Track the review via Webhooks

4. Check the registration status when needed

If you need to fix the business data

Proof of life

Next steps

Document with `onboardingUrl`

Document without `onboardingUrl`