Partners in Pix JD

A partner can call Pix JD with its own credential. You confine that credential to the direct participants (ISPBs) or to the indirect participants it acts for. You need this when one Pix JD deployment serves several participants, and each customer’s system must see and move only its own Pix. Every Pix JD partner needs a scope. A partner with Pix JD permissions and no Pix JD restriction is refused.

Step by step

Choose who the partner acts for

Pix JD has two restrictions:

Restriction	API field	Values
Pix direct participant (ISPB)	`participantId`	The ISPB of each direct participant the partner acts for, 8 digits.
Indirect participant	`indirectId`	The `indirectId` of each indirect participant the partner acts for, as Pix JD returned it when you registered the indirect participant.

Use them in one of these two ways:

The partner acts for	Give it	What it reaches
A direct participant, with all its indirect participants	Only `participantId`, with the direct participant’s ISPB	All of that participant’s Pix: keys, claims, limits, payments, refunds, QR codes, Pix Automático, MED, fraud markers, and its indirect participants.
One indirect participant	Only `indirectId`, with that indirect participant	Payments and their reads, refunds, dynamic QR codes and the QR code list, MED infractions, refund requests, and recoveries, the key lookup, and the indirect participant’s own record and transactions. Nothing of the direct participant, and nothing of the other indirect participants.

To confine a partner to one indirect participant, give it only indirectId. Do not add the ISPB of the direct participant that settles for it. With both, the partner also reads the direct participant’s own data: its keys, claims, limits, fraud markers, and Pix Automático records.

A partner restricted by ISPB alone is the partner of the whole direct participant. It reaches every indirect participant of that direct participant.Do not put the ISPB of an indirect participant in participantId. Access Manager accepts it, but the partner is then refused on almost every route, and it is not confined to that indirect participant. Use indirectId.

Give the partner its permissions and scope

Create the partner, or change it, in the Console or with the Identity API. The product slug is plugin-br-pix-jd. Both restrictions accept several values.

Add at least one restriction for Pix JD. Without one, Access Manager refuses the partner with 400 and IDE-1060.
Check the resources and actions. The most you can give is what the plugin-br-pix-jd-editor-role role holds in your tenant. Above that, Access Manager refuses with IDE-1043.

Access Manager checks each write you give against the scope, and refuses with 400 and IDE-1056 a write wider than the partner’s scope. The Console marks the line Outside the scope:

A partner with an indirect participant in its scope can receive only these writes: create payments, create refunds, and create or change dynamic QR codes. Every other write acts on the whole direct participant: registering keys, claims, limits, static QR codes, Pix Automático, fraud markers, the actions on MED records, and registering or changing indirect participants.
Writes that act on the whole tenant, such as the operator actions and the callbacks of the rail, are never given to a partner.

Create its Pix JD application

Create the partner’s application with the product plugin-br-pix-jd. 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.

Name the participant on every request

Every request names who the partner acts for, in a field that Pix JD already has. The value must be inside the partner’s scope. A request that names nobody is refused.A partner of a direct participant names its ISPB:

Routes	Writes	Reads and routes by ID
Payments and refunds: `/v1/transactions`, `/v1/refunds`	Body `payerIspb`	Query `ispb`
Limits: `/v1/limits`	Body `payerIspb`	Query `payer_ispb`
Keys and claims: `/v1/entries`, `/v1/claims`, `/v1/account-closures`, `/v1/holder-removals`	Body `ispb`, also on `DELETE`	Query `ispb`
QR codes: `/v1/qrcodes`	Body `ispb`	Query `ispb`
Pix Automático: `/v1/pix-automatico`	Body `recipient.ispb` to create an authorization or a schedule, `recurrence.recipient.ispb` to create a composite QR code, `payer.ispb` to confirm an authorization, `requesterIspb` to cancel a schedule, and `ispb` to decode or to validate	Query `ispb`, also to respond to, cancel, or change the maximum value of an authorization
MED: `/v1/med`	Body `ispb` to create a recovery, a refund request, or a fraud marker, and to cancel a fraud marker. Query `ispb` for the actions on an infraction, a refund request, or a recovery	Query `ispb`. To list infractions, `creatorIspb` or `counterpartIspb`. To list refund requests, `requesterIspb` or `contestedIspb`
Indirect participants: `/v1/indirects`	Body `directIspb` to register one, query `directIspb` to change one	Query `directIspb`

To pay through one of its indirect participants, it sends its own ISPB in payerIspb and the indirect participant in indirectId.A partner of an indirect participant names its indirectId:

Routes	Where
Create a payment or a refund: `POST /v1/transactions`, `POST /v1/refunds`	Body `indirectId`. `payerIspb` is not needed.
Create or change a dynamic QR code: `/v1/qrcodes/dynamic`	Body `indirectId`
Read payments: `GET /v1/transactions`, `GET /v1/transactions/{transactionId}`	Query `indirectId`
List QR codes, look up a key: `GET /v1/qrcodes/list`, `GET /v1/entries/{entryId}/lookup`	Query `indirectId`
MED infractions, refund requests, and recoveries: `/v1/med`	Query `indirectId`
Its own record and transactions: `/v1/indirects/{indirectId}`	The path

A body field that takes one participant takes one value. Do not send a list in it.

Confirm that it works

Use the partner’s credential. Read one of the partner’s own payments, naming its own ISPB. The answer is 200:

PIX_JD_BASE_URL="https://pix.<your-domain>"            # your Pix JD base URL
PIX_JD_BEARER_TOKEN="paste-the-partner-access-token-here"
OWN_ISPB="12345678"                                    # an ISPB in the partner's scope
TRANSACTION_ID="paste-a-transaction-id-here"

curl -s -o /dev/null -w '%{http_code}\n' \
  -H "Authorization: Bearer ${PIX_JD_BEARER_TOKEN}" \
  "${PIX_JD_BASE_URL}/v1/transactions/${TRANSACTION_ID}?ispb=${OWN_ISPB}"

For a partner of an indirect participant, send indirectId in place of ispb, with its own value.Send the same request with an ISPB outside the partner’s scope. The answer is 403 with PIX-0005. Send it with the ID of a payment of another participant. The answer is 404 with PIX-0147.

Routes that no partner reaches

A partner with a Pix JD scope is refused with 403 on these routes:

The directories that name no participant: GET /v1/banks, GET /v1/banks/participants, and GET /v1/refunds/reasons.
The composite QR code updates: PUT /v1/pix-automatico/composite/cobv/{id}, PUT /v1/pix-automatico/composite/dynamic/{id}, and PUT /v1/pix-automatico/composite/recurrence/{id}.

Use an application of your own institution for these routes.

If something fails

Code	Status	What it means	What to do
`PIX-0005`	403	The request names a participant outside the partner’s scope, names none, or is outside the partner’s permissions. A list in a query with one value outside the scope is refused too.	Name the participant in the field of that route, with a value in the partner’s scope. Check also that the partner has the permission for that route.
`PIX-0002`	400	A body field received several participants, or two fields of the same request name different participants.	Send one participant, the same in every field.
`PIX-0147`	404	The record the request addresses belongs to another participant. Nothing is read or changed, and the answer does not say who holds the record.	Name the participant the record was created under, or check the ID.
`PIX-0061`	400	On a Pix Automático consultation by ID (an authorization, a schedule, or their cancellations), the record belongs to another participant.	Name the participant the authorization or schedule was created under.
`PIX-0128`	422	The ISPB is in the partner’s scope, but your institution does not operate it on Pix JD.	Check the ISPB.
`PIX-0004`	401	The partner is suspended, or the request is outside its validity window.	Reactivate the partner, or change its validity window.

PIX-0005 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 participants exist outside its scope. For every other code, see the Pix JD error list. For the refusals when you create or change a partner, see Error codes in the API guide.

Introduction

Access Manager

Console

Streaming Hub

Multi-tenancy

Observability

Narya

Lifecycle Management

Licensing

Partners in Pix JD

Step by step

Routes that no partner reaches

If something fails

​Step by step

​Routes that no partner reaches

​If something fails

Step by step

Routes that no partner reaches

If something fails