# Use cases

Common integration flows that combine the catalog endpoints. All assume a valid token (see [Authentication](/en/authentication)).

## 1. Onboard a customer with an account

Create the customer and open the account in a single call.

1. `POST /api/partner/v1/customers` with `document`, `name` and `password` (scope `customer:create`).
2. The response returns the customer, the opened account and the compliance verification result.
3. Check the status later with `GET /api/partner/v1/customers/{id}` (scope `customer:read`).

## 2. Balance and statement

1. `GET /api/partner/v1/accounts` to list your customers' accounts (scope `account:read`).
2. `GET /api/partner/v1/accounts/{id}/balance` for the current balance (scope `account:read`).
3. `GET /api/partner/v1/accounts/{id}/statement` for the statement by period (scope `statement:read`).

## 3. Send a PIX

1. (Optional) `GET /api/partner/v1/pix/dict/{key}` to resolve the destination key (scope `pix:read`).
2. `POST /api/partner/v1/pix/payments` with `account_id`, `amount` (in cents), `pixKey` and `recipientIspb` (scope `pix:write`). Send an `Idempotency-Key`.
3. Track it with `GET /api/partner/v1/pix/payments/{id}` (scope `pix:read`).

## 4. Receive via PIX charge (QR Code)

1. `POST /api/partner/v1/pix/charges` with `account_id` and `amount` (scope `pix:write`). The response returns the BR Code and the QR image.
2. Track the payment with `GET /api/partner/v1/pix/charges/{id}` (scope `pix:read`).
3. For automatic notification, register a [webhook](/en/endpoints/webhooks).

## 5. TED transfer to another bank

1. `POST /api/partner/v1/transfers/ted` with `account_id`, `amount`, `recipientBankCode` (destination bank ISPB) and the recipient details (scope `transfer:write`). Send an `Idempotency-Key`.
2. Track it with `GET /api/partner/v1/transfers/{id}` (scope `transfer:read`).

## 6. Webhook notifications

1. `POST /api/partner/v1/webhooks` with the public `url` and the list of `events` (scope `webhook:write`).
2. Validate each delivery with the signing secret returned on creation.
3. Use `POST /api/partner/v1/webhooks/{id}/test` for a test delivery. The `webhook.test` event goes only to the given webhook.