The callback routes are adapter-only. Do not call them from a client application. Native rail connectivity and production provider availability are outside this release’s supported integration path.
Build your test path
- Deploy the plugin dependencies, including Midaz and the mock provider, in a test environment.
- Obtain an access token when authentication is enabled and identify the account that owns each request.
- Test a public flow: a key, a transfer, or a collection.
- Keep the operation identifier returned by the create request. Read that operation until it reaches a terminal state after the mock callback.
- Record the Midaz posting and operation result together in your test evidence.
Request conventions
Use the per-operation reference as the final authority. These conventions recur across the plugin:
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.