Skip to main content
A partner can call the Payments plugin with its own credential. You confine that credential to one Midaz organization. You need this when one Payments deployment serves several organizations, or when one of your own customers issues boletos and pays bills for itself. Every Payments partner needs a scope.

Step by step

1

Choose the organization the partner acts for

Payments has one restriction:The restriction takes one organization. More than one value is refused with 400 and IDE-0002.The ledger and the accounts are not a Payments restriction. See The partner’s Midaz scope does not apply to Payments.
2

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-payments.
  • Add the scope entry for the organization. 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 Payments holds in your tenant. Above that, Access Manager refuses with IDE-1043.
You can give a partner these actions: read, create, and cancel on the resource boletos; read and create on the resource payments; and read on the resource dashboard.The resource admin acts on the whole tenant. Access Manager refuses every admin action with 400 and IDE-1056, and the Console marks the line Outside the scope.
3

Create its Payments application

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

Name the organization on every request

Every request names the organization in the X-Organization-Id header, which Payments already requires on these routes. The value must be the organization in the partner’s scope. A request without it is refused.A boleto, batch, series, or payment of another organization answers 404, the same answer as an ID that does not exist: name the organization the item belongs to.
5

Confirm that it works

Use the partner’s credential. List the boletos of the organization in the partner’s scope. The answer is 200:
Send the same request without the header, or with another organization. The answer is 403 with PBP-0004.

The partner’s Midaz scope does not apply to Payments

Payments posts to Midaz with its own machine credential, not with the partner’s token. A Midaz scope that you give the partner does not apply to those postings. The partner can use every ledger and account of its organization that Payments accepts.

Routes that no partner reaches

A partner is refused with 403 and PBP-0004 on these routes:
  • Every route under /v1/admin.
  • POST /v1/payments/{id}/cancel.
The administrative routes configure the integration of your whole tenant. Use an application of your own institution for them and for the cancellation of a payment.

If something fails

PBP-0004 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 organizations exist outside its scope. For the refusals when you create or change a partner, see Error codes in the API guide. On a BYOC install, Access Manager knows that Payments accepts partners only after Payments publishes its permission declaration. See Permission declaration.