Marketplace Collection

Requesting Authorization for Bank Accounts

This feature is available upon agreement. The first step is to create an authorization for opening a pay-in (collections) account, choosing either if the owner of the account will be the customer or not. Then, the request will be analyzed by our payment desk (Backoffice).

For CPF subjects, the required fields include: document_type, document_number, social_name, fiscal_country, address_street, address_number, address_postal_code, address_city, address_state, address_country, net_monthly_average_income, website, and at least 2 document.

For Passport subjects, the required fields are the same as for CPF.

For CNPJ subjects, the required fields include: document_type, document_number, social_name, company_name, fiscal_country, address_street, address_number, address_postal_code, address_city, address_state, address_country, net_monthly_average_income, and at least 3 documents (or 4 if the website is null). For each partner with 25% or more percentage share, one additional document is needed. Partners must also provide document_type, document_number, name, and percentage_share.

For Tax ID subjects, the required fields are the same as for CNPJ, but there is no validation for the number of documents.

If approved, you will be able to send a request to open an account in the following endpoint, Requesting Bank Accounts. If reproved, you will also know the reason. In either case, you will receive a webhook with the updated status.

curl -X POST "https://api.facilitapay.com/api/v1/subject/:id/account_request" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9...." \
  -d '{
  "is_subject_account_owner": false
}'

{
  "data": {
    "updated_at": "2025-06-09T20:04:54.255186",
    "subject_id": "93de033d-78db-42f3-9fb6-d2b0abb9a95e",
    "status": "pending",
    "reason": null,
    "is_subject_account_owner": false,
    "inserted_at": "2025-06-09T20:04:54.255176",
    "id": "96abf5e5-3067-4f42-8626-7cc4eda0c05b"
  }
}

Solution: Ensure the subject has an approved authorization before requesting a bank account. Check the authorization status via the webhook or API.

HTTP Request

POST /subject/:id/account_request

Path Parameters

Parameter	Description	Type	Required
id	Your customer's UUID within Attrus. Must be from a subject that has either a cpf, passport, cnpj or tax_id as document_number	string	true

Body Parameters

Parameter	Description	Type	Required
is_subject_account_owner	Defines whether the subject is going to be the owner of the bank account. If true, payments to this bank account will be handled by this subject's document number. If false (default), the account will be registered under Attrus's name. You can set this parameter to true only if your customer has a CPF or CNPJ. Note that the payload is not necessary if there is no need for your subject to be the owner of the bank account as the default value is false	boolean	false

Webhook Notification

{
  "notification": {
    "type": "subject_account_authorization",
    "subject_id": "93de033d-78db-42f3-9fb6-d2b0abb9a95e",
    "status": "approved",
    "reason": null,
    "secret": "your_webhook_secret"
  }
}

This webhook is sent once the Backoffice approves or reproves the authorization request. If reproved, the reason field will contain the reason(s). Use the subject_id to associate with your customer.

warning

Common mistakes

Requesting Bank Accounts

Following the previous authorization, this second - and last - step is to request the opening of a bank account for the subject_id provided. Notice you should use the same id as in the previous endpoint.

The creation normally occurs in a matter of seconds and, once complete, you will receive a webhook with the updated information.

curl -X POST "https://api.facilitapay.com/api/v1/bank/accounts/request" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9...." \
  -d '{
  "subject_id": "93de033d-78db-42f3-9fb6-d2b0abb9a95e",
  "is_subject_account_owner": false
}'

200OK

{
  "data": {
    "user_id": "5e018c08-8a3f-43fd-93cf-11f27ba419e2",
    "subject_id": "93de033d-78db-42f3-9fb6-d2b0abb9a95e",
    "is_subject_account_owner": false,
    "status": "processing",
    "id": "a6a7a710-2bb6-4261-8d56-e7d1a95e6f2b",
    "errors": null
  }
}

HTTP Request

POST /bank/accounts/request

Body Parameters

Parameter	Description	Type	Required
subject_id	Where subject_id is your customer's UUID within Attrus, the same used on the previous endpoint	string	true
is_subject_account_owner	Defines whether the subject is going to be the owner of the bank account. If true, payments to this bank account will be handled by this subject's document number. If false (default), the account will be registered under Attrus's name	string	false

Webhook Notification

Once the account is created, you will receive a webhook notification:

{
  "notification": {
    "type": "account_request_status",
    "request_id": "a6a7a710-2bb6-4261-8d56-e7d1a95e6f2b",
    "status": "complete",
    "secret": "your_webhook_secret"
  }
}

The request_id corresponds to the id field returned in the POST response above. You can use this to query the account details.

Checking information for requested bank account

curl -X GET "https://api.facilitapay.com/api/v1/bank/accounts/request/:id" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9...."

To retrieve the created bank account details, use the id field returned from the POST /bank/accounts/request response (e.g., a6a7a710-2bb6-4261-8d56-e7d1a95e6f2b in the example above). This is the same request_id you receive in the webhook notification:

200OK

{
  "data": {
    "user_id": "5e018c08-8a3f-43fd-93cf-11f27ba419e2",
    "subject_id": "93de033d-78db-42f3-9fb6-d2b0abb9a95e",
    "is_subject_account_owner": false,
    "status": "complete",
    "id": "a6a7a710-2bb6-4261-8d56-e7d1a95e6f2b",
    "errors": null,
    "bank_account": {
      "pix_info": {
        "type": "EVP",
        "key": "e55eeo1d-01ef-016e-14d0-a1ea701ae17e"
      },
      "owner_name": "FACILITA INSTITUICAO DE PAGAMENTO S/A",
      "owner_document_type": "cnpj",
      "owner_document_number": "10789035000105",
      "id": "edfd9dd6-08c0-4ad7-88bc-dce3810d633e",
      "currency": "BRL",
      "branch_number": "0001",
      "branch_country": null,
      "bank": {
        "name": "FACILITA IP S/A",
        "ispb": "10789035"
      },
      "account_type": "conta-corrente",
      "account_number": "70017"
    }
  }
}

HTTP Request

GET /bank/accounts/request/:id

Path Parameters

Parameter	Description	Type	Required
id	The request ID returned from the POST call to create the bank account	string	true