> ## 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 Payments BTG > Confine a partner's Payments credential to one Midaz organization, name the organization on every request, and read the refusals it receives. A [partner](https://docs.lerian.studio/en/platform/access-manager/features/partners/overview) 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: | Restriction | API field | What the partner reaches | What it is refused | | - | - | - | - | | **Midaz organization** | `organizationId` | The boletos, installments, and bill payments of the organization, and its two dashboards. | Every other organization, the administrative routes, and the cancellation of a payment (see [Routes that no partner reaches](#routes-that-no-partner-reaches)). | 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](#the-partners-midaz-scope-does-not-apply-to-payments). **2. 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). 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](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. **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. | Routes | What the partner does | | - | - | | Boletos: `/v1/boletos`, `/v1/boletos/{id}`, `/v1/boletos/{id}/pdf`, `/v1/boletos/{id}/cancel` | Issues, lists, reads, downloads the PDF of, and cancels a boleto. | | Batches: `/v1/boletos/batches`, `/v1/boletos/batches/{batch_id}`, `/v1/boletos/batches/{batch_id}/cancel` | Issues, lists, reads, and cancels a batch of boletos. | | Installments: `/v1/boletos/installments`, `/v1/boletos/installments/{series_id}` | Issues and reads a series of installments. | | Bill payments: `/v1/payments`, `/v1/payments/{id}`, `/v1/payments/darf`, `/v1/payments/consult` | Consults a bill, pays it, pays a DARF, lists payments, and reads one. | | Dashboards: `/v1/dashboards/boletos`, `/v1/dashboards/payments` | Reads the dashboards. | 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`: ```bash theme={null} PAYMENTS_BASE_URL="https://payments." # your Payments base URL PAYMENTS_BEARER_TOKEN="paste-the-partner-access-token-here" OWN_ORGANIZATION_ID="paste-the-organization-in-the-scope" curl -s -o /dev/null -w '%{http_code}\n' \ -H "Authorization: Bearer ${PAYMENTS_BEARER_TOKEN}" \ -H "X-Organization-Id: ${OWN_ORGANIZATION_ID}" \ "${PAYMENTS_BASE_URL}/v1/boletos" ``` 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 *** | Code | Status | What it means | What to do | | - | - | - | - | | `PBP-0004` | 403 | The request names no organization or one outside the partner's scope, or it is outside the partner's permissions. | Send `X-Organization-Id` with the organization in the partner's scope. Check also the partner's permissions. | | `PBP-0003` | 401 | The partner is suspended, or the request is outside its validity window. | Reactivate the partner, or change its validity window. | | `PBP-0005` | 404 | The item does not belong to the organization the request names, or does not exist. Nothing is read or changed. | Check the ID and the organization. | `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](https://docs.lerian.studio/en/platform/access-manager/features/partners/api.md#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](https://docs.lerian.studio/en/interfaces/payments-btg/boleto-environment-variables.md#permission-declaration). This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.