Create a PIX transaction

curl --request POST \
  --url https://api.example.com/v1/transactions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "accountId": "acc-123",
  "amount": 10050,
  "payee": {
    "accountDigit": "7",
    "accountNumber": "123456",
    "accountType": 0,
    "document": "12345678909",
    "ispb": "12345678",
    "branch": "0001",
    "key": "foo@bar.com",
    "name": "Jane Doe"
  },
  "clientRequestId": "req-2025-01-01-abc123",
  "description": "Invoice 42",
  "endToEndId": "E1234567890",
  "indirectId": "3f2504e0-4f89-41d3-9a0c-0305e82c3301",
  "key": "payer@bar.com",
  "priority": 1
}
'

package main

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

func main() {

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

	payload := strings.NewReader("{\n  \"accountId\": \"acc-123\",\n  \"amount\": 10050,\n  \"payee\": {\n    \"accountDigit\": \"7\",\n    \"accountNumber\": \"123456\",\n    \"accountType\": 0,\n    \"document\": \"12345678909\",\n    \"ispb\": \"12345678\",\n    \"branch\": \"0001\",\n    \"key\": \"foo@bar.com\",\n    \"name\": \"Jane Doe\"\n  },\n  \"clientRequestId\": \"req-2025-01-01-abc123\",\n  \"description\": \"Invoice 42\",\n  \"endToEndId\": \"E1234567890\",\n  \"indirectId\": \"3f2504e0-4f89-41d3-9a0c-0305e82c3301\",\n  \"key\": \"payer@bar.com\",\n  \"priority\": 1\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({
    accountId: 'acc-123',
    amount: 10050,
    payee: {
      accountDigit: '7',
      accountNumber: '123456',
      accountType: 0,
      document: '12345678909',
      ispb: '12345678',
      branch: '0001',
      key: 'foo@bar.com',
      name: 'Jane Doe'
    },
    clientRequestId: 'req-2025-01-01-abc123',
    description: 'Invoice 42',
    endToEndId: 'E1234567890',
    indirectId: '3f2504e0-4f89-41d3-9a0c-0305e82c3301',
    key: 'payer@bar.com',
    priority: 1
  })
};

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

import requests

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

payload = {
    "accountId": "acc-123",
    "amount": 10050,
    "payee": {
        "accountDigit": "7",
        "accountNumber": "123456",
        "accountType": 0,
        "document": "12345678909",
        "ispb": "12345678",
        "branch": "0001",
        "key": "foo@bar.com",
        "name": "Jane Doe"
    },
    "clientRequestId": "req-2025-01-01-abc123",
    "description": "Invoice 42",
    "endToEndId": "E1234567890",
    "indirectId": "3f2504e0-4f89-41d3-9a0c-0305e82c3301",
    "key": "payer@bar.com",
    "priority": 1
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

{
  "amount": 10050,
  "id": "d1f9c0a2-...",
  "status": "PENDING",
  "description": "Invoice 42",
  "endToEndId": "E1234567890",
  "flow": 2,
  "jdpiRequestId": "REQ-123",
  "priority": 1
}

{
  "dtHrReqJdPi": "2026-01-01T00:00:00.000Z",
  "endToEndId": "E1234567890",
  "idReqJdPi": "45F763C6-7487-4363-9406-A1DE2A9636D3",
  "idReqSistemaCliente": "9F4C2A10-0000-4000-8000-000000000001",
  "tpCanal": 2
}

{
  "code": "ERR-0001",
  "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": "ERR-0001",
  "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": "ERR-0001",
  "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"
  }
}

Create a PIX transaction

Creates an outbound PIX payment. What happens next depends on where the payee is, and the two branches answer with different statuses and different bodies — a client has to handle both.

An on-us payee (payee.ispb equal to this participant’s own ISPB, on a direct order) settles SYNCHRONOUSLY as an INTRA_PSP ledger transfer and answers 201 with the transaction already EXECUTED. Any other payee settles over SPI in TWO PHASES: the amount is first HELD on the paying position as a pending ledger debit, and only then is the order submitted to JDPI (§8.4.1), which is asynchronous by design — nothing has settled when the call returns. A direct order answers 201 with the transaction PENDING; an order routed through a registered indirect (indirectId in the body) answers 202 carrying JD’s own §8.4.1 acknowledgement byte-for-byte, whose idReqJdPi is the handle the outcome is read with. Either way, poll GET /v1/transactions/: a background reconciler consults JDPI §8.4.2 and then commits or cancels the hold, and the money is not settled until the status says so.

WHAT indirectId ACTUALLY MOVES, because it is more than a label. This participant may serve INDIRECT participants — other institutions registered here with POST /v1/indirects that reach SPI through this participant’s ISPB. Naming one on an order changes THREE things at once: the amount is held on that institution’s @pi_{ispb} settlement position instead of on the payer’s own, the persisted order is stamped with that institution so it appears in GET /v1/indirects//transactions, and the response shape changes from 201-plus-plugin-body to 202-plus-JD-body. The identifier is ROUTING DATA, not a credential: this participant authenticates you, and guaranteeing that the order really belongs to that institution is your responsibility, not this API’s.

⚠️ indirectId IS SILENTLY IGNORED WHILE THIS TENANT’S INDIRECT-PARTICIPANTS FEATURE IS SWITCHED OFF. With the feature off the value is not parsed, not resolved and not refused: the order runs as a DIRECT one, holding the amount on the direct participant’s own position and answering 201. Nothing in the response says the routing was dropped. Confirm the feature is on before sending the first order for an institution — an unknown id answering 404 PIX-0095 is the evidence that it is.

When the order settles, an indirect order ALSO pushes a NOTICE to the endpoint that registration carries (delivery.endpointUrl), once the background reconciler has JD’s terminal outcome — an HTTPS POST forwarding JD’s own result body verbatim, carrying X-Lerian-Signature (‘sha256=’ followed by the hex HMAC-SHA256 of the exact body bytes under the registration’s shared secret) and X-Lerian-Timestamp. Delivery is AT-LEAST-ONCE and can also fail permanently while the payment stands, so the institution must dedup on the end-to-end id and treat GET /v1/indirects//transactions, not the notice, as the record of truth. A direct order pushes no notice.

End-to-end ids: send endToEndId only when you already hold one (from a key lookup or a QR decode), and then payee.key is mandatory with it. Omit it on a manually typed order and SPI mints one — the response carries the minted value. Idempotency: the optional clientRequestId is the only identifier that exists BEFORE the JD call, so it is what makes a retry safe on every branch, and it is the ONLY protection a manually typed order has (that order’s end-to-end id does not exist yet when the retry arrives). Amounts are integer centavos.

Every refusal below is decided before the hold is taken, so it moves ZERO money; when JDPI rejects the order after the hold exists, the hold is released and nothing is persisted. Refusals: 409 PIX-0029 when this endToEndId or clientRequestId was already used; 409 PIX-0076 when the paying position lacks the amount; 409 PIX-0078 on a transfer to the same account; 409 PIX-0032 when the account’s period limit is exceeded; 422 PIX-0030 on a non-positive amount; 422 PIX-0037 when endToEndId arrives without payee.key; 422 PIX-0108 when the payer — or, on an indirect order, the indirect’s @pi — resolves in the CRM but is not bound to a ledger account; 404 PIX-0095 for an unknown or malformed indirectId and 422 PIX-0100 when the indirect it names is not ACTIVE; 422 PIX-0102 when a payer.ispb is supplied on an indirect order and disagrees with that indirect’s own ISPB; 400 PIX-0061 when accountId is empty or an accountType is outside the PIX domain 0..4. On an indirect order a JD business rejection is passed back with JD’s own status and body instead of a problem+json.

POST

transactions

Create a PIX transaction

curl --request POST \
  --url https://api.example.com/v1/transactions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "accountId": "acc-123",
  "amount": 10050,
  "payee": {
    "accountDigit": "7",
    "accountNumber": "123456",
    "accountType": 0,
    "document": "12345678909",
    "ispb": "12345678",
    "branch": "0001",
    "key": "foo@bar.com",
    "name": "Jane Doe"
  },
  "clientRequestId": "req-2025-01-01-abc123",
  "description": "Invoice 42",
  "endToEndId": "E1234567890",
  "indirectId": "3f2504e0-4f89-41d3-9a0c-0305e82c3301",
  "key": "payer@bar.com",
  "priority": 1
}
'

package main

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

func main() {

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

	payload := strings.NewReader("{\n  \"accountId\": \"acc-123\",\n  \"amount\": 10050,\n  \"payee\": {\n    \"accountDigit\": \"7\",\n    \"accountNumber\": \"123456\",\n    \"accountType\": 0,\n    \"document\": \"12345678909\",\n    \"ispb\": \"12345678\",\n    \"branch\": \"0001\",\n    \"key\": \"foo@bar.com\",\n    \"name\": \"Jane Doe\"\n  },\n  \"clientRequestId\": \"req-2025-01-01-abc123\",\n  \"description\": \"Invoice 42\",\n  \"endToEndId\": \"E1234567890\",\n  \"indirectId\": \"3f2504e0-4f89-41d3-9a0c-0305e82c3301\",\n  \"key\": \"payer@bar.com\",\n  \"priority\": 1\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({
    accountId: 'acc-123',
    amount: 10050,
    payee: {
      accountDigit: '7',
      accountNumber: '123456',
      accountType: 0,
      document: '12345678909',
      ispb: '12345678',
      branch: '0001',
      key: 'foo@bar.com',
      name: 'Jane Doe'
    },
    clientRequestId: 'req-2025-01-01-abc123',
    description: 'Invoice 42',
    endToEndId: 'E1234567890',
    indirectId: '3f2504e0-4f89-41d3-9a0c-0305e82c3301',
    key: 'payer@bar.com',
    priority: 1
  })
};

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

import requests

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

payload = {
    "accountId": "acc-123",
    "amount": 10050,
    "payee": {
        "accountDigit": "7",
        "accountNumber": "123456",
        "accountType": 0,
        "document": "12345678909",
        "ispb": "12345678",
        "branch": "0001",
        "key": "foo@bar.com",
        "name": "Jane Doe"
    },
    "clientRequestId": "req-2025-01-01-abc123",
    "description": "Invoice 42",
    "endToEndId": "E1234567890",
    "indirectId": "3f2504e0-4f89-41d3-9a0c-0305e82c3301",
    "key": "payer@bar.com",
    "priority": 1
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

{
  "amount": 10050,
  "id": "d1f9c0a2-...",
  "status": "PENDING",
  "description": "Invoice 42",
  "endToEndId": "E1234567890",
  "flow": 2,
  "jdpiRequestId": "REQ-123",
  "priority": 1
}

{
  "dtHrReqJdPi": "2026-01-01T00:00:00.000Z",
  "endToEndId": "E1234567890",
  "idReqJdPi": "45F763C6-7487-4363-9406-A1DE2A9636D3",
  "idReqSistemaCliente": "9F4C2A10-0000-4000-8000-000000000001",
  "tpCanal": 2
}

{
  "code": "ERR-0001",
  "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": "ERR-0001",
  "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": "ERR-0001",
  "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

accountId

string

required

The CRM account id of the payer.

Example:

"acc-123"

amount

integer<int64>

required

Transaction amount in centavos (an integer, e.g. 10050 = R$ 100,50).

Example:

10050

payee

object

required

The recipient bank data.

Show child attributes

clientRequestId

string

Optional client idempotency token. A retry carrying the same value is rejected instead of moving money twice; it also seeds the Midaz hold key and the JDPI Chave-Idempotencia. Send it on a manually-typed order: that order has no endToEndId until SPI mints it, so this token is the only thing that can dedup a retry. Omit to opt out.

Example:

"req-2025-01-01-abc123"

description

string

Free-text payment description.

Example:

"Invoice 42"

endToEndId

string

SPI end-to-end id. Omit ONLY for a manually-typed payment order: per JDPI §8.4.1 the id does not exist yet and is generated by SPI on this call. If you obtained one from decode-QRCode (§8.3.3) or consultar-chave (§8.2.14) you MUST send it — omitting it makes SPI mint a DIFFERENT id, which will not match the payee's QR/txId conciliation.

Example:

"E1234567890"

indirectId

string<uuid>

Optional registered-indirect identifier (UUID) routing this outbound order through an indirect participant's PIX position. Omit for a direct order. Validated server-side before any money moves; unknown or inactive is rejected.

Example:

"3f2504e0-4f89-41d3-9a0c-0305e82c3301"

key

string

The payer's PIX key, when paying from a key.

Example:

"payer@bar.com"

priority

integer<int64>

Numeric eTransactionPriority (1=PRIMARY,2=SECONDARY).

Example:

1

Response

Created

amount

integer<int64>

required

Transaction amount in centavos.

Example:

10050

string

required

The created transaction id.

Example:

"d1f9c0a2-..."

status

string

required

eTransactionStatus name.

Example:

"PENDING"

description

string

Payment description.

Example:

"Invoice 42"

endToEndId

string

The SPI end-to-end id.

Example:

"E1234567890"

flow

integer<int64>

Numeric eTransactionFlow (2=CASH_OUT,3=INTRA_PSP).

Example:

2

jdpiRequestId

string

The JDPI request id (external CASH_OUT).

Example:

"REQ-123"

priority

integer<int64>

Numeric eTransactionPriority.

Example:

1

Key DICT API

Key Claims API

Banks API

Indirect participants API

Transactions API

Transaction Limits API

QR Codes API

Refunds API

Pix Automático · Authorization requests

Pix Automático · Authorization management

Pix Automático · Composite QR codes

Pix Automático · Authorization events

Pix Automático · Schedule events

Pix Automático · Schedules and payment instructions

Pix Automático · Settlement

MED · Refunds

MED · Fraud markers

MED · Infractions

MED · Value recovery

Webhooks API

Error handling

Events

Create a PIX transaction

Authorizations

Body

Response