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.

WHICH DIRECT PARTICIPANT THE INDIRECT RIDES IS DECIDED HERE AND NEVER AGAIN. This deployment may act as several direct SPI participants, and an indirect reaches SPI through exactly ONE of them: directIspb names it, and the registry records that participant together with the Midaz organization and default ledger its @pi settlement account belongs to. Omit directIspb and the deployment’s default participant is used, which is where every indirect lived before this deployment could act as several. An ISPB this deployment does not act as is 422 PIX-0128. The chosen participant, organization and ledger come back on the response as directIspb, organizationId and ledgerId, and PATCH cannot change them — an account exists in exactly one ledger, so re-pointing would orphan the position rather than move it.

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-0128 when directIspb names a direct participant this deployment does not act as; 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; 409 PIX-0107 when no delivery-secret encryption key is provisioned for this tenant — an operator has to provision it, so re-POSTing unchanged fails identically, and the response body names the knob; 503 PIX-0123 when that key could not be READ from its key source, which is a fault on our side rather than a missing value and is safe to repeat shortly.

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.