Update an indirect participant

Applies mutable-field changes and/or ONE lifecycle action to an indirect. Absent (null) body fields are left untouched, so a PATCH carrying only action moves the lifecycle and changes nothing else; a PATCH carrying neither a field nor an action is a no-op that returns the current row without writing anything, not an error.

The lifecycle actions are suspend, reactivate and close, and each one writes the LEDGER as well as the registry. suspend disables both sending and receiving on the indirect’s @pi account, so the ledger refuses that participant’s money even if another replica’s resolution cache is still stale; reactivate re-enables both. close is IRREVERSIBLE — CLOSED is terminal, nothing leaves it, and afterwards every field mutation on the row is refused too. close never deletes: the @pi account is permanently blocked but kept, so a later re-registration of the same ISPB reuses it. When a lifecycle action and field changes arrive together, the action is what the audit trail records.

Refusals: 409 PIX-0094 when the action is illegal from the current status (suspend on PENDING_PROVISIONING or CLOSED, reactivate on anything but SUSPENDED, close on PENDING_PROVISIONING, or any change to a CLOSED row) — re-issuing an action the row already reached is illegal too, not an idempotent success; 409 PIX-0096 when close is attempted while the @pi account still holds an available or on-hold balance, refused so the funds cannot be stranded (settle it to zero first); 409 PIX-0007 when another writer changed the row concurrently — reload and retry; 404 PIX-0095 for an unknown id; 422 PIX-0098 for an unknown action, a name over 120 characters, a delivery.endpointUrl that is not a valid https URL, or a qrCertificate.publicBaseUrl that is absent while ownCertificate is true, carries a scheme, is not a bare host with an optional path, or does not name a publicly resolvable host; 422 PIX-0111 when the body carries qrCertificate and this tenant’s indirect-participants feature is not enabled — the WHOLE patch is refused, including any name or delivery change riding alongside; 503 PIX-4002 when the ledger could not be reached to check the balance or move the account flags.

PATCH /v1/indirects/{indirectId}

Update an indirect participant

cURL

curl --request PATCH \
  --url https://api.example.com/v1/indirects/{indirectId} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "action": "suspend",
  "delivery": {
    "endpointUrl": "https://indirect.example.com/pix",
    "secret": "s3cr3t"
  },
  "name": "Indirect PSP Ltda",
  "qrCertificate": {
    "ownCertificate": true,
    "publicBaseUrl": "qr.indirect.example.com/pix"
  }
}
'

200

{
  "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.

Path Parameters

indirectId · string · required

The indirect participant id.

Example:

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

Body

application/json

action · string

Lifecycle transition; one of suspend, reactivate, close.

Example:

"suspend"

delivery · object

New delivery endpoint and/or secret.

Show child attributes

name · string

New display name (1..120 chars).

Example:

"Indirect PSP Ltda"

qrCertificate · object

New own-QR-code certificate configuration. Absent leaves it unchanged. Accepted only when the indirect participants feature is enabled for the tenant (422 PIX-0111 otherwise).

Show child attributes

Response

200

application/json

OK

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).