Register an indirect participant

Registers an indirect participant in this tenant’s registry and immediately runs the provisioning saga that makes it usable: the ISPB is checked for uniqueness (and, on a tenant with JD directory validation enabled, for existence as an SPI participant at JD), THE PLUGIN creates the participant’s @pi_{ispb} settlement account in Midaz — a client never creates it — and the row flips to ACTIVE. Call it once per indirect you onboard, before any inbound credit or outbound order names it: resolution is ACTIVE-gated, so a row still in PENDING_PROVISIONING is neither routable inbound nor usable as an outbound source.

THIS WRITE IS PERMANENT. 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.

The saga runs inline but does NOT gate the 201. When a step fails the response is still 201, carrying status PENDING_PROVISIONING and provisioning.failedStep (validateISPB, createPIAccount or markActive); re-run it with POST /v1/indirects//provisioning/retry. So read status off the response rather than assuming ACTIVE.

Refusals: 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, or an absent ispb (the @pi_{ispb} alias derives from it, so the MVP requires one); 503 PIX-0107 when the tenant’s delivery-secret encryption is unavailable — refused before the insert, so nothing was stored.

POST /v1/indirects

Register an indirect participant

cURL

curl --request POST \
  --url https://api.example.com/v1/indirects \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Indirect PSP Ltda",
  "ispb": "12345678",
  "messagingMode": "raw"
}
'

201

{
  "createdAt": "2023-11-07T05:31:56Z",
  "delivery": {
    "endpointUrl": "https://indirect.example.com/pix",
    "secret": "***"
  },
  "indirectId": "018f2b7c-0000-7000-8000-000000000000",
  "ispb": "12345678",
  "messagingMode": "raw",
  "name": "Indirect PSP Ltda",
  "piAccountAlias": "@pi_12345678",
  "provisioning": {
    "failedStep": "createPIAccount"
  },
  "qrCertificate": {
    "ownCertificate": true,
    "publicBaseUrl": "qr.indirect.example.com/pix"
  },
  "status": "ACTIVE",
  "updatedAt": "2023-11-07T05:31:56Z"
}

Authorizations

Authorization · string · header · required

JWT bearer token issued by the identity provider.

Body

application/json

name · string · required

Display name of the indirect participant (1..120 chars).

Example:

"Indirect PSP Ltda"

delivery · object

Delivery endpoint + signing secret.

Show child attributes

ispb · string

The indirect PSP's own ISPB (exactly 8 digits). Required for MVP flows.

Example:

"12345678"

messagingMode · string

Delivery mode; the MVP supports 'raw' (JD-pure passthrough).

Example:

"raw"

Response

201

application/json

Created

createdAt · string<date-time> · required

Creation timestamp (UTC).

delivery · object · required

Delivery endpoint (secret redacted).

Show child attributes

indirectId · string · required

The indirect participant id (routing identifier).

Example:

"018f2b7c-0000-7000-8000-000000000000"

ispb · string · required

The indirect PSP's ISPB.

Example:

"12345678"

messagingMode · string · required

Delivery mode.

Example:

"raw"

name · string · required

Display name.

Example:

"Indirect PSP Ltda"

piAccountAlias · string · required

The derived @pi_{ispb} Midaz account alias.

Example:

"@pi_12345678"

provisioning · object · required

Provisioning-saga state.

Show child attributes

qrCertificate · object · required

Own-QR-code certificate configuration.

Show child attributes

status · string · required

Lifecycle status.

Example:

"ACTIVE"

updatedAt · string<date-time> · required

Last-update timestamp (UTC).