Get a PIX transaction status

curl --request GET \
  --url https://api.example.com/v1/transactions/{transactionId} \
  --header 'Authorization: Bearer <token>'

package main

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

func main() {

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

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

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

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

	fmt.Println(string(body))

}

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

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

{
  "amount": 10050,
  "id": "d1f9c0a2-...",
  "status": "EXECUTED",
  "description": "Invoice 42",
  "endToEndId": "E1234567890",
  "errorCode": "",
  "errorMessage": "",
  "feeContext": "pix_salario",
  "flow": 2,
  "internalSettlementReport": {
    "settledAt": "2026-10-22T12:00:00Z",
    "status": "CONFIRMED",
    "confirmedAt": "2026-10-22T12:00:20Z",
    "errorCode": "ED05",
    "errorDetail": "Valor invalido",
    "idReqJdPi": "70F945C1-9024-4123-1001-A1DE2A0000D1",
    "sentAt": "2026-10-22T12:00:05Z"
  },
  "jdpiRequestId": "REQ-123",
  "jdpiStatus": 9,
  "payee": {
    "personType": 0,
    "accountDigit": "7",
    "accountId": "@pagador",
    "accountNumber": "123456",
    "branch": "0001",
    "document": "12345678909",
    "ispb": "12345678",
    "key": "foo@bar.com",
    "keyType": 2,
    "name": "Jane Doe"
  },
  "payer": {
    "personType": 0,
    "accountDigit": "7",
    "accountId": "@pagador",
    "accountNumber": "123456",
    "branch": "0001",
    "document": "12345678909",
    "ispb": "12345678",
    "key": "foo@bar.com",
    "keyType": 2,
    "name": "Jane Doe"
  },
  "pendingReason": "BALANCE_NOT_RECEIVING"
}

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

Get a PIX transaction status

Resolves one transaction’s status. This is the operation that closes the loop after a payment: an outbound SPI order answers 201 or 202 with nothing settled, and the verdict arrives here.

The path id is resolved in three steps, in order: by JDPI request id (idReqJdPi), then — only when the value parses as a UUID — by local transaction id, and finally, when neither matched, by a LIVE lookup at JDPI (§8.4.2). Those branches do not answer the same thing. A local hit returns the status the reconciler last persisted; a live hit is a projection of JD’s own processing status, is the only branch that populates jdpiStatus, and projects JD status 9 to EXECUTED. So a transaction this plugin never persisted can still answer 200 here, and a status read live is not evidence that a local row exists.

Read-only: it neither commits nor releases the held amount — the background reconciler does that on its own tick, so a PENDING answer means “not decided yet”, not “stuck”. Optional ispb and indirectId name who the transaction is read as: named, it has to be held by that direct participant or indirect, or the answer is 404 PIX-0147 and nothing about it is returned — a token confined to one participant or indirect has to name it. Refusals: 400 PIX-0061 when transactionId is empty; 404 PIX-0147 when the transaction is held by another participant or indirect than the one named; 422 PIX-0128 for an ispb this deployment does not act as; and on the live branch, JDPI’s own outcome — 404 PIX-1027 when JD does not know the id either, 503 PIX-1050 when JDPI is unreachable — so a failure here names the dependency instead of hiding behind a generic error.

GET

transactions

{transactionId}

Get a PIX transaction status

curl --request GET \
  --url https://api.example.com/v1/transactions/{transactionId} \
  --header 'Authorization: Bearer <token>'

package main

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

func main() {

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

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

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

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

	fmt.Println(string(body))

}

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

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

{
  "amount": 10050,
  "id": "d1f9c0a2-...",
  "status": "EXECUTED",
  "description": "Invoice 42",
  "endToEndId": "E1234567890",
  "errorCode": "",
  "errorMessage": "",
  "feeContext": "pix_salario",
  "flow": 2,
  "internalSettlementReport": {
    "settledAt": "2026-10-22T12:00:00Z",
    "status": "CONFIRMED",
    "confirmedAt": "2026-10-22T12:00:20Z",
    "errorCode": "ED05",
    "errorDetail": "Valor invalido",
    "idReqJdPi": "70F945C1-9024-4123-1001-A1DE2A0000D1",
    "sentAt": "2026-10-22T12:00:05Z"
  },
  "jdpiRequestId": "REQ-123",
  "jdpiStatus": 9,
  "payee": {
    "personType": 0,
    "accountDigit": "7",
    "accountId": "@pagador",
    "accountNumber": "123456",
    "branch": "0001",
    "document": "12345678909",
    "ispb": "12345678",
    "key": "foo@bar.com",
    "keyType": 2,
    "name": "Jane Doe"
  },
  "payer": {
    "personType": 0,
    "accountDigit": "7",
    "accountId": "@pagador",
    "accountNumber": "123456",
    "branch": "0001",
    "document": "12345678909",
    "ispb": "12345678",
    "key": "foo@bar.com",
    "keyType": 2,
    "name": "Jane Doe"
  },
  "pendingReason": "BALANCE_NOT_RECEIVING"
}

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

Autorizaciones

Authorization

string

header

requerido

JWT bearer token issued by the identity provider.

Parámetros de ruta

transactionId

string

requerido

The transaction id (local UUID or JDPI request id).

Ejemplo:

"d1f9c0a2-..."

Parámetros de consulta

ispb

string

The ISPB of the direct participant this transaction is read as. OPTIONAL: omit it and the transaction is read whoever holds it, exactly as before. Named, the transaction has to be booked in that participant's books, or the answer is 404 PIX-0147 - the same id named under another participant is not served. When this deployment holds no such transaction, the live lookup at JDPI is made with that participant's credential, so JD answers only for what that participant holds. An ISPB this deployment does not act as is 422 PIX-0128. It is ROUTING DATA you supply, never a credential, and a token confined to one participant has to name it here. Sending it empty (ispb=) reads the same as omitting it.

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

Ejemplo:

"12345678"

indirectId

string<uuid>

The registered indirect participant (UUID) this transaction is read as. OPTIONAL. Named, the transaction has to be recorded for that indirect, or the answer is 404 PIX-0147 - a direct participant's own transaction is not the indirect's. A transaction this deployment does not hold is 404 PIX-0147 too: an indirect's movements are always booked here, so JDPI is not asked. A token confined to one indirect has to name it here.

Ejemplo:

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

Respuesta

amount

integer<int64>

requerido

Transaction amount in centavos.

Ejemplo:

10050

string

requerido

The transaction id (or JDPI tx id on the live branch).

Ejemplo:

"d1f9c0a2-..."

status

string

requerido

eTransactionStatus name.

Ejemplo:

"EXECUTED"

description

string

Payment description.

Ejemplo:

"Invoice 42"

endToEndId

string

The SPI end-to-end id.

Ejemplo:

"E1234567890"

errorCode

string

JDPI error code (live branch).

Ejemplo:

""

errorMessage

string

JDPI error message (live branch).

Ejemplo:

""

feeContext

string

The fee label the order was accepted with (local branch). Absent when it carried none.

Ejemplo:

"pix_salario"

flow

integer<int64>

Numeric eTransactionFlow.

Ejemplo:

2

internalSettlementReport

object

Where the TRCK.002 report to Bacen (JDPI §8.4.17/§8.4.18) of a Pix this participant settled internally stands. Present only for an on-us Pix that reached EXECUTED; absent for every other transaction, on the live branch, and when the report could not be read (the status is still answered).

Show child attributes

jdpiRequestId

string

The JDPI request id.

Ejemplo:

"REQ-123"

jdpiStatus

integer<int64>

Raw JDPI eProcessingStatus (live branch only).

Ejemplo:

9

payee

object

The payee party.

Show child attributes

payer

object

The payer party.

Show child attributes

pendingReason

enum<string>

Why a PENDING transaction is waiting, or how a received Pix was closed. BALANCE_NOT_RECEIVING: a received Pix, or the return of a Pix this participant sent, from another bank, that the ledger refused because the receiving balance does not accept credits; it stays PENDING and is credited by itself on a later redelivery or reconcile pass once the balance accepts credits: a received Pix until 7 days less an hour after it arrived, or sooner by an operator (POST /v1/parked-credits/{transactionId}/credit or /return); a return the same, though an operator only credits it (/credit). TRACER_DENIED: the same, for a credit the client's Tracer refused (a rule, a limit or a review); it is credited once the Tracer lets it through, and returned only while the Tracer still refuses it. CREDITING and RETURNING: its own credit or one of those actions holds it; a received Pix or return is CREDITING while its first credit runs. RETURN_REFUSED: SPI refused its return; it waits for either action again. RETURNED (status ERROR): it was returned to the payer and never credited. Absent when no reason is known.

Opciones disponibles:

BALANCE_NOT_RECEIVING,

TRACER_DENIED,

CREDITING,

RETURNING,

RETURN_REFUSED,

RETURNED

Ejemplo:

"BALANCE_NOT_RECEIVING"

APIs del participante directo

APIs de participantes indirectos

Get a PIX transaction status

Autorizaciones

Parámetros de ruta

Parámetros de consulta

Respuesta