> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# Partners in Pix Lerian

> Confine a partner's Pix Lerian credentials to the accounts it acts for, name the account on every request, and read the refusals it receives.

A [partner](https://docs.lerian.studio/en/platform/access-manager/features/partners/overview) can call Pix Lerian with its own credential. You confine that credential to some accounts of your tenant. You need this when the partner acts for some of your clients and must not act on the accounts of the others.

Every Pix Lerian partner needs a scope.

## Step by step

***

**1. Choose the products the partner uses**

Pix Lerian is four products in Access Manager. Give the partner only the products it needs:

| Product | Product slug | What it serves |
| - | - | - |
| **SPI** | `plugin-br-pix-lerian-spi` | Cash-out and cash-in, refunds, Pix Agendado, and balance locks. |
| **DICT hub** | `plugin-br-pix-lerian-dict` | Keys, claims, and MED. |
| **COB hub** | `plugin-br-pix-lerian-cob` | Charges and BR Codes. |
| **Pix Automático** | `plugin-br-pix-lerian-pixauto` | The payer's mandates and their payments. |

The connectivity adapter does not accept partners. Only the Pix Lerian services call it.

**2. Choose the accounts the partner acts for**

Pix Lerian has one restriction, the same on the four products:

| Restriction | API field | What the partner reaches | What it is refused |
| - | - | - | - |
| **Account** | `accountId` | The Pix records of each account you list: the payer's or the client's Midaz account ID, the same ID your client sends in `X-Account-Id`. | Every other account, and the routes that carry no account (see [Routes that no partner reaches](#routes-that-no-partner-reaches)). |

Pix Lerian has no organization or ledger restriction. Each tenant runs one Midaz organization and one ledger. The tenant's configuration sets them, and no request names them. To confine a partner to a ledger, also give it a [Midaz scope](https://docs.lerian.studio/en/platform/access-manager/features/partners/midaz.md). See [The partner's Midaz rules apply to its calls](#the-partners-midaz-rules-apply-to-its-calls).

**3. Give the partner its permissions and scope**

Create the partner, or change it, in the [Console](https://docs.lerian.studio/en/platform/access-manager/features/partners/console.md) or with the [Identity API](https://docs.lerian.studio/en/platform/access-manager/features/partners/api.md). Use the product slugs from the first step. The restriction accepts several accounts.

* Add the `accountId` scope entry on each Pix Lerian product you give. Without it, Access Manager refuses the partner with `400` and `IDE-1060`.
* Check the resources and actions. The most you can give is what the editor role of each product holds in your tenant. Above that, Access Manager refuses with `IDE-1043`.

Some writes act on routes that carry no account:

* The balance locks.
* The notification outbox.
* The operator routes that run and recover work.
* The recovery of a transfer or a refund: `transfer-recovery` and `refund-recovery`, action `post`.
* The runtime settings.

Access Manager refuses them with `400` and `IDE-1056`, and the Console marks the line **Outside the scope**.

Access Manager also refuses, with the same code, the writes that change a key, open a funds recovery, or create a recurring payment. See [Routes that no partner reaches](#routes-that-no-partner-reaches).

**4. Create its Pix Lerian applications**

Create the partner's applications with the Pix Lerian products you gave it. See [Create the partner's applications](https://docs.lerian.studio/en/platform/access-manager/features/partners/api.md#create-the-partners-applications) in the API guide, or [in the Console](https://docs.lerian.studio/en/platform/access-manager/features/partners/console.md#create-the-partners-applications). Send the client ID and the client secret to the partner through a secure channel.

**5. Name the account on every request**

Every request names the account in a field that Pix Lerian already has. The value must be inside the partner's scope. A partner must send the account on every route in this table, also where the field is optional for other callers. A request without it is refused.

| Product | Routes | Where the account goes |
| - | - | - |
| SPI | Transfers: `POST /spi/v1/transfers/cashout/initiate`, `POST /spi/v1/transfers/cashout/process`, `GET /spi/v1/transfers`, `GET /spi/v1/transfers/{id}`, `POST /spi/v1/transfers/{id}/refunds` | Header `X-Account-Id` |
| SPI | Refunds: `GET /spi/v1/refunds`, `GET /spi/v1/refunds/{id}` | Header `X-Account-Id` |
| SPI | Pix Agendado writes: `POST /spi/v1/scheduled-payments`, `POST /spi/v1/scheduled-payment-recurrences` | Body `accountId` |
| SPI | Pix Agendado lists: `GET /spi/v1/scheduled-payments`, `GET /spi/v1/scheduled-payment-totals`, `GET /spi/v1/scheduled-payment-limit-impact`, `GET /spi/v1/scheduled-payment-recurrences` | Query `account_id` |
| DICT hub | Keys: `GET` and `POST /dict-hub/v1/entries`, `GET` and `DELETE /dict-hub/v1/entries/{entry_id}`, `GET /dict-hub/v1/keys/{key}` | Header `X-Account-Id` |
| DICT hub | Claims: `GET` and `POST /dict-hub/v1/claims`, `GET /dict-hub/v1/claims/{claim_id}`, `POST /dict-hub/v1/claims/{claim_id}/cancel`, `/complete`, and `/confirm` | Header `X-Account-Id` |
| DICT hub | MED funds recoveries: `GET /dict-hub/v1/dict/funds-recoveries` | Query `account_id` |
| COB hub | `POST /cob-hub/v1/brcodes/static`, `GET` and `POST /cob-hub/v1/collections/immediate`, `GET` and `DELETE /cob-hub/v1/collections/immediate/{id}`, `GET` and `POST /cob-hub/v1/collections/duedate`, `GET /cob-hub/v1/collections/duedate/provider-status`, `GET`, `PATCH`, and `DELETE /cob-hub/v1/collections/duedate/{id}` | Header `X-Account-Id` |
| Pix Automático | Authorization requests: `GET /pixauto/v1/payer/authorization-requests`, `GET /pixauto/v1/payer/authorization-requests/{authorization_request_id}`, `POST .../{authorization_request_id}/decide` | Header `X-Account-Id` |
| Pix Automático | Authorizations: `GET /pixauto/v1/payer/authorizations`, `GET` and `PATCH /pixauto/v1/payer/authorizations/{authorization_id}`, `GET .../{authorization_id}/history`, `POST .../{authorization_id}/cancel` | Header `X-Account-Id` |
| Pix Automático | Scheduled payments: `GET /pixauto/v1/payer/scheduled-payments`, `GET /pixauto/v1/payer/scheduled-payments/{scheduled_payment_id}`, `POST .../{scheduled_payment_id}/cancel`, `POST .../{scheduled_payment_id}/unblock` | Header `X-Account-Id` |
| Pix Automático | `POST /pixauto/v1/payer/authorization-requests/from-qr` | Body `payerAccountId` |

A request that names a record of another account answers `404`, as if the record did not exist. Nothing is read or changed.

**6. Confirm that it works**

This check assumes the partner has the `transfers` resource with the `get` action on `plugin-br-pix-lerian-spi`, and a scope with one or more accounts. Use the partner's credential. List the transfers of an account in the partner's scope. The answer is `200`:

```bash theme={null}
PIX_LERIAN_SPI_BASE_URL="https://pix.<your-domain>"          # your Pix Lerian SPI base URL
PIX_LERIAN_BEARER_TOKEN="paste-the-partner-access-token-here"
OWN_ACCOUNT_ID="paste-an-account-in-the-scope"

curl -s -o /dev/null -w '%{http_code}\n' \
  -H "Authorization: Bearer ${PIX_LERIAN_BEARER_TOKEN}" \
  -H "X-Account-Id: ${OWN_ACCOUNT_ID}" \
  "${PIX_LERIAN_SPI_BASE_URL}/spi/v1/transfers"
```

Send the same request with an account outside the partner's scope. The answer is `403` with `PIX-0010`.

## The partner's Midaz rules apply to its calls

***

Some Pix Lerian products call Midaz while they serve the partner's request:

* SPI posts the debits and credits to the ledger, and reads the account and its holder.
* DICT hub and Pix Automático read the holder and the account in the CRM embedded in Midaz.

When the partner also has Midaz permissions, Midaz applies the partner's Midaz scope to these calls. For example, take a partner restricted in Midaz to the tenant's organization and one ledger. It can initiate and process a cash-out from an account of that ledger. With the same partner restricted in Midaz to another ledger, Pix Lerian refuses the initiation and the processing with `403` and `PIX-0005`, and the account balance does not change.

* A partner with no Midaz permissions is decided by its Pix Lerian permissions and scope only.
* You can give the partner its Midaz rules in the same Console flow, or later on the Midaz product.
* The scheduled sweeps, the provider callbacks, and the other background work run without a partner. The partner's rules do not apply there.

> [!WARNING]
>
> Do not rely on the Midaz rules with a standalone CRM 3.x. If your deployment reads holders from a standalone CRM 3.x, that CRM does not apply the partner's rules. Only the CRM embedded in Midaz applies them.

## Routes that no partner reaches

***

A partner with a Pix Lerian scope is refused with `403` and `PIX-0010` on the routes that carry no account:

* SPI: every `/spi/v1/balance-locks` route, the routes of one scheduled payment or one recurrence (`/spi/v1/scheduled-payments/{schedule_id}` and `/spi/v1/scheduled-payment-recurrences/{recurrence_id}`, with the routes under them), and the operator routes.
* DICT hub: `POST /dict-hub/v1/claims/{claim_id}/acknowledge`, `POST /dict-hub/v1/keys/check`, the routes of one funds recovery, and the infraction reports, refunds, fraud markers, and VSync routes.
* COB hub: `POST /cob-hub/v1/brcodes/decode`, `GET /cob-hub/v1/brcodes/static`, and `GET /cob-hub/v1/brcodes/static/{id}`.
* Pix Automático: `POST /pixauto/v1/payer/recurring-consents` and `POST /pixauto/v1/payer/recurring-consents/{recurring_consent_id}/revoke`.

These routes act on records that no account names.

Pix Lerian also refuses a partner, with the same answer, on three routes where the account of the request does not bind what the route changes:

* `PATCH /dict-hub/v1/entries/{entry_id}`: the request can move the key to another account.
* `POST /dict-hub/v1/dict/funds-recoveries`: the route opens the recovery on a transaction that the account does not bind.
* `POST /pixauto/v1/payer/recurring-payments`: the route accepts the payment under a consent that the account does not bind.

Pix Lerian also refuses a partner, with the same answer, on the four recovery routes of SPI. This applies also when the request names an account in the partner's scope:

* `POST /spi/v1/transfers/{id}/unblock` and `POST /spi/v1/transfers/{id}/credit`.
* `POST /spi/v1/refunds/{id}/unblock` and `POST /spi/v1/refunds/{id}/credit`.

Your operations team uses these routes to correct a transaction stuck in processing, or a credit that failed in the ledger. They act for the whole tenant, so the account of the request does not confine them.

Use an application of your own institution for all these routes.

## If something fails

***

| Code | Status | What it means | What to do |
| - | - | - | - |
| `PIX-0010` | 403 | The request names an account outside the partner's scope, names none, or is outside the partner's permissions or IP allowlist. | Send the account in the field of that route, with an account in the partner's scope. Check also the partner's permissions and IP allowlist. |
| `PIX-0010` | 401 | The partner is suspended, or the request is outside its validity window. | Reactivate the partner, or change its validity window. |
| `PIX-0005` | 403 | Midaz refused the partner on a call that Pix Lerian made for it: the call is outside the partner's Midaz permissions or scope. Nothing is moved. | Check the partner's Midaz permissions and scope. |
| `PIX-0320` | 404 | The initiation belongs to another account. Nothing is read or changed. | Check the initiation ID and the account. |
| `PIX-0340` | 404 | The transfer belongs to another account. Nothing is read or changed. | Check the transfer ID and the account. |

`PIX-0010` does not say whether the permissions or the scope refused the request. This is on purpose: a partner cannot use a refusal to learn which accounts exist outside its scope.

A change to a partner, such as a suspension or a new scope, applies on its next request, also with a token it already has.

For every other code, see the [Pix Lerian error list](https://docs.lerian.studio/en/reference/interfaces/pix-lerian/pix-lerian-error-list.md). For the refusals when you create or change a partner, see [Error codes](https://docs.lerian.studio/en/platform/access-manager/features/partners/api.md#error-codes) in the API guide.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.