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": "",
  "flow": 2,
  "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"
  }
}

{
  "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": "",
  "flow": 2,
  "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"
  }
}

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

Path Parameters

transactionId

string

required

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

Example:

"d1f9c0a2-..."

Query Parameters

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-9]{8}$

Example:

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

Example:

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

Response

amount

integer<int64>

required

Transaction amount in centavos.

Example:

10050

string

required

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

Example:

"d1f9c0a2-..."

status

string

required

eTransactionStatus name.

Example:

"EXECUTED"

description

string

Payment description.

Example:

"Invoice 42"

endToEndId

string

The SPI end-to-end id.

Example:

"E1234567890"

errorCode

string

JDPI error code (live branch).

Example:

""

errorMessage

string

JDPI error message (live branch).

Example:

""

flow

integer<int64>

Numeric eTransactionFlow.

Example:

2

jdpiRequestId

string

The JDPI request id.

Example:

"REQ-123"

jdpiStatus

integer<int64>

Raw JDPI eProcessingStatus (live branch only).

Example:

9

payee

object

The payee party.

Show child attributes

payer

object

The payer party.

Show child attributes

Direct participant APIs

Indirect participant APIs

Get a PIX transaction status

Authorizations

Path Parameters

Query Parameters

Response