Register an indirect participant
Registers an indirect participant in this tenant’s registry and makes it usable in one step. Call it once per indirect you onboard, before any inbound credit or outbound order names it.
REGISTRATION IS ATOMIC: a 201 means the participant is READY, and a failure means nothing was created. Before writing anything the service checks the ispb is not already held by a non-CLOSED indirect, optionally checks (on a tenant with JD directory validation enabled) that it exists as an SPI participant at JD, and creates the participant’s @pi_{ispb} settlement account in Midaz — THE PLUGIN creates that account, a client never does. Only then is the row written, and it is written ACTIVE, so there is no intermediate state to poll and no provisioning field to read on the response. If any of those steps fails you get a coded error naming the step, NO registry row exists, and the ispb is still free: fix the cause and POST again. There is no retry endpoint, because there is nothing half-written to resume.
THIS WRITE IS PERMANENT once it succeeds. There is no DELETE on /v1/indirects: the registry’s only exit is PATCH with action close, CLOSED is terminal (nothing leaves it), and even a close keeps the row and its @pi account — the account is blocked, never deleted. An indirect registered by mistake against a live tenant stays in that tenant’s registry, and its ispb is held against the open-uniqueness constraint until it is closed. Verify name, ispb and the delivery endpoint before calling.
Refusals, all of which leave the registry untouched: 409 PIX-0093 when a non-CLOSED indirect already holds this ispb — a CLOSED one may be re-registered and reuses its historical @pi account; 422 PIX-0098 for a missing or over-120-character name, an ispb that is not exactly 8 digits, a delivery.endpointUrl that is not a valid https URL, a missing delivery.secret, an unknown messagingMode, an absent ispb (the @pi_{ispb} alias derives from it, so the MVP requires one), or — on a tenant with JD directory validation enabled — an ispb JD does not know as an SPI participant; 502 PIX-0099 when a step failed on a retryable fault, naming the step (validateISPB or createPIAccount) so you know which dependency to check before re-POSTing; 503 PIX-4002 when the ledger could not be reached to create the settlement account; 503 PIX-0107 when the tenant’s delivery-secret encryption is unavailable.
Re-POSTing after a failure is safe: the settlement account is created by alias, so an attempt that got that far and then failed leaves an account the next attempt adopts rather than duplicating.
Authorizations
JWT bearer token issued by the identity provider.
Body
Display name of the indirect participant (1..120 chars).
"Indirect PSP Ltda"
Delivery endpoint + signing secret.
The indirect PSP's own ISPB (exactly 8 digits). Required for MVP flows.
"12345678"
Delivery mode; the MVP supports 'raw' (JD-pure passthrough).
"raw"
Response
Created
Creation timestamp (UTC).
Delivery endpoint (secret redacted).
The indirect participant id (routing identifier).
"018f2b7c-0000-7000-8000-000000000000"
The indirect PSP's ISPB.
"12345678"
Delivery mode.
"raw"
Display name.
"Indirect PSP Ltda"
The derived @pi_{ispb} Midaz account alias.
"@pi_12345678"
Legacy provisioning state. Always present as an object; its failedStep is always null for a row registered by this service.
Own-QR-code certificate configuration.
Lifecycle status.
"ACTIVE"
Last-update timestamp (UTC).

