Skip to main content
A partner 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: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: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. See The partner’s Midaz rules apply to its calls.
3

Give the partner its permissions and scope

Create the partner, or change it, in the Console or with the Identity API. 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.
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 in the API guide, or in the Console. 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.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:
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.
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


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. For the refusals when you create or change a partner, see Error codes in the API guide.