Integrating with Pix Lerian

Set up a Pix Lerian integration, apply request conventions, and follow public API flows without calling adapter-only callbacks.

Your application calls the public DICT, SPI, COB, and Pix Automático APIs. The plugin calls Midaz and a connectivity adapter: the Lerian connectivity adapter for Lerian SPI, or the mock provider for integration tests. The adapter returns asynchronous callbacks to the plugin.

The callback routes are adapter-only. Do not call them from a client application.

Build your integration path

1. Deploy the plugin dependencies, including Midaz and the connectivity adapter for your environment.
2. Obtain an access token when authentication is enabled and identify the account that owns each request.
3. Run a public flow: a key, a transfer, or a collection.
4. Keep the operation identifier returned by the create request. Read that operation until it reaches a terminal state after the adapter callback.
5. Record the Midaz posting and the operation result together.

Request conventions

Use the per-operation reference as the final authority. These conventions recur across the plugin:

Concern	Use
Authentication	Send a bearer token in Authorization when Access Manager authentication is enabled.
Account scope	Send X-Account-Id on account-scoped public operations. The plugin uses it to enforce account ownership.
Mutation replay	Send a new X-Idempotency value for each intended write, then reuse that exact value only to retry the same request. Most public POST operations require it.
Business justification	Send X-Reason where the DICT operation requires a reason, such as entry mutation.
Content type	Use application/json for JSON bodies. A JSON merge patch requires application/merge-patch+json.

A missing or invalid idempotency header is a client error. Reusing a key with a different payload is a precondition failure, except when you create an immediate or due-date collection: those two routes return the existing collection with 200.

Read state after an asynchronous write

A successful request can mean that the plugin accepted work, not that the external payment or collection completed. For SPI, use the returned transfer or refund identifier with the transfer or refund read endpoint. For collections, read the collection by its identifier.

Treat these results differently:

• Validation or authorization error: correct the request or token. Do not retry unchanged input.
• Replay response: keep the original result. Do not create a second business operation.
• Conflict: read the resource and choose the next legal transition.
• Temporary dependency error: preserve the idempotency value before retrying. A route that documents a fail-closed dependency will continue to refuse the write until that dependency is restored.

Keep boundaries clear

Your client owns public API calls and reads. The connectivity adapter owns provider outcomes. The plugin owns callback processing and Midaz posting. This separation prevents a client from manufacturing settlement states or bypassing the account and provider checks.

Continue with SPI flows for payment sequencing, DICT flows for keys and MED 2.0, or COB flows for BR Codes and collections.