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

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/v1/indirects"

	payload := strings.NewReader("{\n  \"name\": \"Indirect PSP Ltda\",\n  \"directIspb\": \"12345678\",\n  \"ispb\": \"12345678\",\n  \"messagingMode\": \"raw\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: 'Indirect PSP Ltda',
    directIspb: '12345678',
    ispb: '12345678',
    messagingMode: 'raw'
  })
};

fetch('https://api.example.com/v1/indirects', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.example.com/v1/indirects"

payload = {
    "name": "Indirect PSP Ltda",
    "directIspb": "12345678",
    "ispb": "12345678",
    "messagingMode": "raw"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "createdAt": "2023-11-07T05:31:56Z",
  "delivery": {
    "endpointUrl": "https://indirect.example.com/pix",
    "secret": "***"
  },
  "directIspb": "12345678",
  "indirectId": "018f2b7c-0000-7000-8000-000000000000",
  "ispb": "12345678",
  "ledgerId": "019fb9b6-8ed1-7964-86e6-b421f711e62a",
  "messagingMode": "raw",
  "name": "Indirect PSP Ltda",
  "organizationId": "019fb9b6-7593-7667-abe9-3b087192747b",
  "piAccountAlias": "@pi_12345678",
  "provisioning": {
    "failedStep": "createPIAccount"
  },
  "qrCertificate": {
    "ownCertificate": true,
    "publicBaseUrl": "qr.indirect.example.com/pix"
  },
  "status": "ACTIVE",
  "updatedAt": "2023-11-07T05:31:56Z"
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

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.

POST

indirects

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

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/v1/indirects"

	payload := strings.NewReader("{\n  \"name\": \"Indirect PSP Ltda\",\n  \"directIspb\": \"12345678\",\n  \"ispb\": \"12345678\",\n  \"messagingMode\": \"raw\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: 'Indirect PSP Ltda',
    directIspb: '12345678',
    ispb: '12345678',
    messagingMode: 'raw'
  })
};

fetch('https://api.example.com/v1/indirects', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.example.com/v1/indirects"

payload = {
    "name": "Indirect PSP Ltda",
    "directIspb": "12345678",
    "ispb": "12345678",
    "messagingMode": "raw"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "createdAt": "2023-11-07T05:31:56Z",
  "delivery": {
    "endpointUrl": "https://indirect.example.com/pix",
    "secret": "***"
  },
  "directIspb": "12345678",
  "indirectId": "018f2b7c-0000-7000-8000-000000000000",
  "ispb": "12345678",
  "ledgerId": "019fb9b6-8ed1-7964-86e6-b421f711e62a",
  "messagingMode": "raw",
  "name": "Indirect PSP Ltda",
  "organizationId": "019fb9b6-7593-7667-abe9-3b087192747b",
  "piAccountAlias": "@pi_12345678",
  "provisioning": {
    "failedStep": "createPIAccount"
  },
  "qrCertificate": {
    "ownCertificate": true,
    "publicBaseUrl": "qr.indirect.example.com/pix"
  },
  "status": "ACTIVE",
  "updatedAt": "2023-11-07T05:31:56Z"
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

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

directIspb

string

ISPB of the DIRECT participant of this tenant the indirect mounts on — the institution whose ISPB and credential its Pix travels on, and in whose books its @pi position account is created. OPTIONAL: omit it and the tenant's default participant is used, which is where every indirect lived before this deployment could act as several. Must be a participant this deployment actually acts as (422 PIX-0128 otherwise). It is ROUTING DATA you supply and guarantee, never a credential. IMMUTABLE after registration: the @pi account exists in exactly one ledger, so PATCH cannot re-point it. Send it as an absent key, not an empty string; an empty value is refused 400 PIX-0061.

Pattern: ^[0-9]{8}$

Example:

"12345678"

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

Created

createdAt

string<date-time>

required

Creation timestamp (UTC).

delivery

object

required

Delivery endpoint (secret redacted).

Show child attributes

directIspb

string

required

ISPB of the direct participant this indirect mounts on — recorded at registration and never changed.

Example:

"12345678"

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"

ledgerId

string

required

The Midaz ledger inside that organization the @pi account was created in. Read-only.

Example:

"019fb9b6-8ed1-7964-86e6-b421f711e62a"

messagingMode

string

required

Delivery mode.

Example:

"raw"

name

string

required

Display name.

Example:

"Indirect PSP Ltda"

organizationId

string

required

The Midaz organization of that direct participant: the books this indirect's @pi account lives in. Read-only.

Example:

"019fb9b6-7593-7667-abe9-3b087192747b"

piAccountAlias

string

required

The derived @pi_{ispb} Midaz account alias.

Example:

"@pi_12345678"

provisioning

object

required

Legacy provisioning state. Always present as an object; its failedStep is always null for a row registered by this service.

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

Direct participant APIs

Indirect participant APIs

Register an indirect participant

Authorizations

Body

Response