Onboarding via API

Overview

Before an organization can receive or make payments via Tesouro, this organization must be onboarded. If the partner previously stored the organization onboarding requirements (the information required to use the Tesouro payment rails) in the Tesouro system, then you can onboard the organization via API. By onboarding via API, you can streamline the organization onboarding process and reduce the time and effort required to onboard new organizations. These are the required steps to onboard an organization for payment acceptance via API:

Create an organization.
Assign payment methods.
Check for missing requirements.
Provide the missing requirements
Track the payments onboarding status changes.

Roles and permissions

Unless mentioned otherwise, the endpoints used in this guide can be called with both the partner access token and organization user tokens. In the latter case, the organization user needs a role with the following permissions:

onboarding: create, update
person: create, update, delete

1. Create an organization

An organization is a party (person or business) that can receive payments via Tesouro partner’s payment rails. To learn how to create and manage organizations that represent your customers, see Organizations.

Required information for onboarding

Providing as much information as possible during the organization’s registration process will make the onboarding process smoother. Here is the list of the information necessary for onboarding that should be provided in advance, and the related endpoints:

Object	Example	Endpoint
`bank_account`	`bank_account`	`POST /bank-accounts`
`entities.x`	`entities.phone`	`PATCH /entities/{entity_id}`
`persons.x`	`persons.representative.phone`	`POST /persons`
`persons.documents`	`persons.documents.additional_document` `persons.documents.verification_document` See Manage documents for more information about these document types.	`POST /persons/{person_id}/onboarding-documents`
`entities.onboarding_data.x`	`entities.onboarding_data.business_profile.mcc`	`PATCH /entities/{entity_id}/onboarding-data`
`entities.documents`	`entities.documents.additional_document` `entities.documents.verification_document` `entities.documents.proof_of_registration` See Manage documents for more information about these document types.	`POST /onboarding-documents`

Important

Organization name must be no longer than 100 characters.
An organization must have at least one bank account in order to receive payments. The bank account currency should match the payment currency. If an organization has several bank accounts (whether for the same currency or different currencies), it must set the default bank account for each currency.
To use the sepa_credit payment method, the organization’s default bank account must be in a country in the SEPA zone.
Organizations of the type organization must register the information of the legally responsible individuals associated with their organization. See Persons for further information.
To complete the onboarding, the organizations and persons must also provide the onboarding data and onboarding documents.

2. Assign payment methods

To specify the payment methods that an organization expects to be using, call PUT /entities/{entity_id}/payment-methods. In the request body, the payment_methods_receive list specifies the methods by which the organization can receive payments from its counterparts, and the payment_methods_send list specifies the methods that the organization can use to make payments to others.

curl -X PUT 'https://api.sandbox.tesouro.com/v1/entities/{entity_id}/payment-methods' \
     -H 'X-Finops-Version: 2025-06-23' \
     -H 'Authorization: Bearer YOUR_APP_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{
       "payment_methods_receive": [
         "card",
         "eps",
         "ideal",
         "sepa_credit",
         "sepa_debit"
       ],
       "payment_methods_send": [
         "sepa_credit"
       ]
     }'

Notes:

Some payment methods are limited to certain countries or currencies. For example, us_ach can only be used by US-based organizations.
Some payment methods can be used both to send and receive payments, while others can be used only to send or only to receive payments.
Currently, us_ach can only be used in payment_methods_receive and cannot be used in payment_methods_send.

The steps below are optional if the chosen payment methods do not require onboarding for payments.

3. Check for missing requirements

An organization may need to provide additional information or documents before it can use certain payment methods. To check if any additional information is required to complete the onboarding process, call GET /onboarding-requirements:

curl -X GET 'https://api.sandbox.tesouro.com/v1/onboarding-requirements' \
     -H 'X-Finops-Version: 2025-06-23' \
     -H 'X-Organization-Id: ORGANIZATION_ID' \
     -H 'Authorization: Bearer YOUR_APP_TOKEN'

The successful response lists the information that is still missing to complete the onboarding process:

{
  "verification_status": "disabled",
  "disabled_reason": "requirements.past_due",
  "requirements_errors": [],
  "verification_errors": [],
  "requirements": {
    "currently_due": [
      "bank_account",
      "organizations.onboarding_data.business_profile.mcc",
      "organizations.onboarding_data.ownership_declaration.date",
      "organizations.onboarding_data.ownership_declaration.ip",
      "organizations.organization.directors_provided",
      "organizations.phone",
      "persons.representative.phone",
      "persons.123e4567-e89b-12d3-a456-426614174000.first_name"
    ],
    "eventually_due": [
      "bank_account",
      "organizations.onboarding_data.business_profile.mcc",
      "organizations.onboarding_data.ownership_declaration.date",
      "organizations.onboarding_data.ownership_declaration.ip",
      "organizations.organization.directors_provided",
      "organizations.phone",
      "persons.representative.phone",
      "persons.123e4567-e89b-12d3-a456-426614174000.first_name"
    ],
    "current_deadline": null,
    "pending_verification": []
  }
}

Some fields are explained below:

requirements - the list of required information that the organization needs to provide to finish the onboarding.
currently_due - the list of minimum fields required to keep the organization’s account enabled. This data must be provided by the current_deadline date.
current_deadline - date by which the fields in currently_due must be collected to keep the organization’s account enabled.
eventually_due - the list of fields that are not needed immediately, but will be needed at some point later.
business_profile.mcc - merchant category code (MCC) of the organization.
organizations.onboarding_data.ownership_declaration.* - a declaration, from the person submitting the organization information, that the business is appropriately registered and that the information provided is correct.
persons.representative.phone - means that the phone number of the organization’s representative must be provided.
persons.123e4567-e89b-12d3-a456-426614174000.first_name - when a UUID is found in a field name, it means that a resource with that ID is missing some information. the first_name must be provided for the person with ID 123e4567-e89b-12d3-a456-426614174000.

After an organization provides this additional information, you can call GET /onboarding-requirements again at any time to check the updated list.

4. Provide the missing requirements

Once you know which requirements are missing to finish the onboarding for payments, you can provide them via the API. The endpoint used to update the missing requirements and complete the onboarding process depends on the missing information’s object. See the complete list of the required information for onboarding and its related endpoints.

Depending on the payment provider and the inconsistencies found in the information sent, you may need to provide the ownership_declaration at this stage.To provide the information about the ownership_declaration, call PATCH /entities/{entity_id}/onboarding-data passing ownership_declaration.ip and ownership_declaration.date in the body.

5. Track the payments onboarding status

You can be notified of every change in the organization onboarding requirements by subscribing to these webhooks:

organization.onboarding_requirements.updated - triggered every time an organization makes a change to the list of requirements.
organization.onboarding_requirements.status_updated - triggered every time the verification_status of an organization’s onboarding process changes.

To subscribe to these webhooks, call POST /webhook-subscriptions with the following request body, replacing the url with the URL of your webhook listener endpoint:

curl -X POST 'https://api.sandbox.tesouro.com/v1/webhook-subscriptions' \
     -H 'X-Finops-Version: 2025-06-23' \
     -H 'Authorization: Bearer YOUR_APP_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{
       "object_type": "entity",
       "event_types": [
         "onboarding_requirements.updated",
         "onboarding_requirements.status_updated"
       ],
       "url": "https://yourcompany.com/webhook-listener"
     }'

Webhook events sent by Tesouro contain the entity_id, which you can use to identify the affected organization:

onboarding_requirements.updated
onboarding_requirements.status_updated

{
  "id": "8cac4aa7-09c0-40e7-94a3-54adb9cc744e",
  "created_at": "2024-03-04T20:08:16.097467+00:00",
  "action": "organization.onboarding_requirements.updated",
  "api_version": "2025-06-23",
  "entity_id": "ce0e9fc7-b3e7-4f12-ad86-bfb0725a99f0",
  "description": "entity_onboarding_requirements_updated",
  "object": {
    "id": "ce0e9fc7-b3e7-4f12-ad86-bfb0725a99f0"
  },
  "object_type": "entity",
  "webhook_subscription_id": "c7f37127-44e5-494a-833a-21e60585f187"
}

{
  "id": "90cc1b23-9681-40f4-a54b-4c059cd4397d",
  "created_at": "2024-03-04T20:12:48.399442+00:00",
  "action": "organization.onboarding_requirements.status_updated",
  "api_version": "2025-06-23",
  "entity_id": "ce0e9fc7-b3e7-4f12-ad86-bfb0725a99f0",
  "description": "entity_onboarding_requirements_status_updated",
  "object": {
    "id": "ce0e9fc7-b3e7-4f12-ad86-bfb0725a99f0"
  },
  "object_type": "entity",
  "webhook_subscription_id": "c7f37127-44e5-494a-833a-21e60585f187"
}

The organization ID received from a webhook event can be used to check the progress of organization onboarding by calling GET /onboarding-requirements. Once all the requirements are provided, the response will look like this:

{
  "verification_status": "enabled",
  "disabled_reason": null,
  "requirements_errors": [],
  "verification_errors": [],
  "requirements": {
    "currently_due": [],
    "eventually_due": [],
    "current_deadline": null,
    "pending_verification": []
  }
}

Getting started

Embedded components

Authentication

Manage organizations

Common objects

Accounts payable

Accounts receivable

Payments

Advanced

Accounting integrations

Expense management

Onboarding via API

Overview

Roles and permissions

1. Create an organization

Required information for onboarding

2. Assign payment methods

3. Check for missing requirements

4. Provide the missing requirements

5. Track the payments onboarding status

Getting started

Embedded components

Authentication

Manage organizations

Common objects

Accounts payable

Accounts receivable

Payments

Advanced

Accounting integrations

Expense management

​Overview

​Roles and permissions

​1. Create an organization

​Required information for onboarding

​2. Assign payment methods

​3. Check for missing requirements

​4. Provide the missing requirements

​5. Track the payments onboarding status

Overview

Roles and permissions

1. Create an organization

Required information for onboarding

2. Assign payment methods

3. Check for missing requirements

4. Provide the missing requirements

5. Track the payments onboarding status