Creating an application

Your backend creates the application server-to-server with a bearer token, regardless of whether a browser will be involved later. The response is the application as stored, plus a plaintext client secret you can hand to a browser if you need one. POST /embedded-banking/v1/bank-account-applications

Create Request

curl -X POST 'https://api.sandbox.tesouro.com/embedded-banking/v1/bank-account-applications' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "applicant": { ... },
    "businessDetails": { ... },
    "businessOwners": [ ... ]
  }'

Response (201 Created)

{
  "id": "550e8400-e29b-41d4-a716-446655440001",
  "applicant": { ... },
  "businessDetails": { ... },
  "businessOwners": [ ... ],
  "clientSecret": "cs_..."
}

clientSecret is returned on every create response, but you only need it if a browser is going to finish the application. If your backend is going to drive the entire flow with its bearer token — the server-to-server integration shape — ignore the field and keep calling per-application endpoints with Authorization: Bearer. The secret carries no extra capability the bearer doesn’t already have. When a browser does need it: hand it directly to that browser context once, and do not log or persist it server-side. The plaintext is not recoverable from a later GET; the service stores only a hash. Token shape, header, and PII-masking rules are covered in Application client secret. Pre-filling fields is optional — you can also create an empty application and PATCH everything in afterward, whether the PATCH calls come from your backend or a browser.

Acting on behalf of a child organization

Platform-level callers (a bank, ISO, or VSP parent) can create an application for a specific child organization in their hierarchy by setting the X-Organization-ID header on the create request:

Targeting a child org

curl -X POST 'https://api.sandbox.tesouro.com/embedded-banking/v1/bank-account-applications' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'X-Organization-ID: 0a8c3f4d-1b2e-4d7a-9c5b-2e8f6a1d3c4b' \
  -H 'Content-Type: application/json' \
  -d '{ ... }'

The header is optional. If omitted, the application is created against the authenticated caller’s own organization, which is the right behavior for a VSP creating an application for one of its own merchants. Set it when a platform credential needs to operate within a specific descendant org — for example, when Northfield Software’s parent bank uses its own credentials to create an application for a Northfield-owned sub-organization. The header is rejected if the target organization is not the caller’s own or a descendant of it. X-Organization-ID is accepted only on this endpoint. After creation, the application is addressed by its id and the organization is fixed.

Documentation Index

​Acting on behalf of a child organization

Acting on behalf of a child organization