Get a Transfer

curl --request GET \
  --url https://api.example.com/v1/transfers/{transferId} \
  --header 'Authorization: Bearer <token>' \
  --header 'X-Organization-Id: <x-organization-id>'

package main

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

func main() {

	url := "https://api.example.com/v1/transfers/{transferId}"

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

	req.Header.Add("X-Organization-Id", "<x-organization-id>")
	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: {'X-Organization-Id': '<x-organization-id>', Authorization: 'Bearer <token>'}
};

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

import requests

url = "https://api.example.com/v1/transfers/{transferId}"

headers = {
    "X-Organization-Id": "<x-organization-id>",
    "Authorization": "Bearer <token>"
}

response = requests.get(url, headers=headers)

print(response.text)

{
  "transferId": "019c96a0-ab10-7cde-f1a2-0e1f2a3b4c5d",
  "type": "TED_OUT",
  "status": "COMPLETED",
  "organizationId": "019c96a0-0a98-7287-9a31-786e0809c769",
  "ledgerId": "019c96a0-0b10-7c2d-8e3f-4a5b6c7d8e9f",
  "senderAccountId": "019c96a0-0c0c-7221-8cf3-13313fb60081",
  "recipient": {
    "ispb": "00000000",
    "branch": "0001",
    "account": "1234567890",
    "accountType": "CACC",
    "holderName": "Maria Santos",
    "holderDocument": "98765432100"
  },
  "amount": 1000.5,
  "feeAmount": 1.5,
  "totalAmount": 1002,
  "confirmationNumber": "20260201001",
  "controlNumber": "202602010001",
  "createdAt": "2026-02-01T18:30:00Z",
  "updatedAt": "2026-02-01T18:35:00Z",
  "completedAt": "2026-02-01T18:35:00Z",
  "statusHistory": [
    {
      "status": "CREATED",
      "timestamp": "2026-02-01T18:30:00Z"
    },
    {
      "previousStatus": "CREATED",
      "status": "PENDING",
      "timestamp": "2026-02-01T18:30:05Z"
    },
    {
      "previousStatus": "PENDING",
      "status": "PROCESSING",
      "timestamp": "2026-02-01T18:30:10Z"
    },
    {
      "previousStatus": "PROCESSING",
      "status": "COMPLETED",
      "timestamp": "2026-02-01T18:35:00Z"
    }
  ],
  "reconciliationAttempts": 0
}

GET

transfers

{transferId}

Get a Transfer

curl --request GET \
  --url https://api.example.com/v1/transfers/{transferId} \
  --header 'Authorization: Bearer <token>' \
  --header 'X-Organization-Id: <x-organization-id>'

package main

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

func main() {

	url := "https://api.example.com/v1/transfers/{transferId}"

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

	req.Header.Add("X-Organization-Id", "<x-organization-id>")
	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: {'X-Organization-Id': '<x-organization-id>', Authorization: 'Bearer <token>'}
};

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

import requests

url = "https://api.example.com/v1/transfers/{transferId}"

headers = {
    "X-Organization-Id": "<x-organization-id>",
    "Authorization": "Bearer <token>"
}

response = requests.get(url, headers=headers)

print(response.text)

{
  "transferId": "019c96a0-ab10-7cde-f1a2-0e1f2a3b4c5d",
  "type": "TED_OUT",
  "status": "COMPLETED",
  "organizationId": "019c96a0-0a98-7287-9a31-786e0809c769",
  "ledgerId": "019c96a0-0b10-7c2d-8e3f-4a5b6c7d8e9f",
  "senderAccountId": "019c96a0-0c0c-7221-8cf3-13313fb60081",
  "recipient": {
    "ispb": "00000000",
    "branch": "0001",
    "account": "1234567890",
    "accountType": "CACC",
    "holderName": "Maria Santos",
    "holderDocument": "98765432100"
  },
  "amount": 1000.5,
  "feeAmount": 1.5,
  "totalAmount": 1002,
  "confirmationNumber": "20260201001",
  "controlNumber": "202602010001",
  "createdAt": "2026-02-01T18:30:00Z",
  "updatedAt": "2026-02-01T18:35:00Z",
  "completedAt": "2026-02-01T18:35:00Z",
  "statusHistory": [
    {
      "status": "CREATED",
      "timestamp": "2026-02-01T18:30:00Z"
    },
    {
      "previousStatus": "CREATED",
      "status": "PENDING",
      "timestamp": "2026-02-01T18:30:05Z"
    },
    {
      "previousStatus": "PENDING",
      "status": "PROCESSING",
      "timestamp": "2026-02-01T18:30:10Z"
    },
    {
      "previousStatus": "PROCESSING",
      "status": "COMPLETED",
      "timestamp": "2026-02-01T18:35:00Z"
    }
  ],
  "reconciliationAttempts": 0
}

Autorizações

Authorization

string

header

obrigatório

JWT Bearer token authentication. The tenantId is derived from the bearer token or authenticated request context and is not supplied through X-Organization-Id.

Cabeçalhos

X-Organization-Id

string<uuid>

obrigatório

Midaz organization scope for the request, used for downstream CRM, Fees, and Midaz calls. Required on org-scoped transfer routes in every deployment mode; a missing or non-UUID value returns 400. This is not the tenant identifier — tenantId is derived from the bearer JWT or authenticated context, never from this header. Background workers (TED IN poller, reconciliation) have no request header and, in single-tenant mode, fall back to the deployment's ORGANIZATION_ID env.

Parâmetros de caminho

transferId

string<uuid>

obrigatório

The unique identifier of the transfer.

Resposta

Indicates that the transfer was found and its details are returned.

transferId

string<uuid>

obrigatório

The unique identifier of the transfer.

Exemplo:

"019c96a0-ab10-7cde-f1a2-0e1f2a3b4c5d"

type

enum<string>

obrigatório

The type of transfer. TED_OUT is an outgoing transfer to an external bank via JD SPB; the voluntary return of a TED IN is also a TED_OUT. TED_IN is an incoming transfer from an external bank. Each TED_IN_STR type is an incoming customer credit received as that STR message, for example TED_IN_STR0041 for an INSS payroll loan received as STR0041R2. P2P is a peer-to-peer transfer within the same institution (same ISPB). CROSS_CORE is a TED to an account that the other core of your institution holds, sent through the JD Courier. CROSS_CORE_IN is a cross-core credit, or the return of a cross-core TED, received from the other core.

Opções disponíveis:

TED_OUT,

TED_IN,

TED_IN_STR0005,

TED_IN_STR0007,

TED_IN_STR0029,

TED_IN_STR0034,

TED_IN_STR0037,

TED_IN_STR0041,

TED_IN_STR0051,

P2P,

CROSS_CORE,

CROSS_CORE_IN

Exemplo:

"TED_OUT"

status

enum<string>

obrigatório

The current status of the transfer. For TED OUT: CREATED → PENDING → PROCESSING → COMPLETED, REJECTED, or FAILED. For P2P: CREATED → PROCESSING → COMPLETED or FAILED (PENDING is an SPB-specific state and does not apply to P2P). Transfers can be CANCELLED while in CREATED or PENDING status. For TED IN: RECEIVED → PROCESSING → COMPLETED or FAILED. A COMPLETED TED IN can also transition to FAILED in the event of a chargeback.

Opções disponíveis:

CREATED,

PENDING,

PROCESSING,

COMPLETED,

REJECTED,

FAILED,

CANCELLED,

RECEIVED

Exemplo:

"COMPLETED"

organizationId

string<uuid>

obrigatório

The Midaz organization that the transfer is filed under. It equals the X-Organization-Id of the request.

Exemplo:

"019c96a0-0a98-7287-9a31-786e0809c769"

ledgerId

string<uuid>

obrigatório

The Midaz ledger that the transfer is filed under. On a P2P between two ledgers, the payer's ledger. Always present. The all-zeroes UUID means that the scope is unrepaired. See Repair Transfer Ledger Scope.

Exemplo:

"019c96a0-0b10-7c2d-8e3f-4a5b6c7d8e9f"

senderAccountId

string<uuid>

obrigatório

UUID of the sender account. Always present. For TED IN, where the sender is an external bank with no local account, this is a synthetic identifier deterministically derived from the sender's document.

Exemplo:

"019c96a0-0c0c-7221-8cf3-13313fb60081"

recipient

object

obrigatório

Show child attributes

amount

number<decimal>

obrigatório

The transfer amount without the fee.

Exemplo:

1000.5

feeAmount

number<decimal>

obrigatório

The fee charged for this transfer.

Exemplo:

1.5

totalAmount

number<decimal>

obrigatório

The amount debited from the sender's account: the transfer amount plus any fee charged on top. For TED IN, the gross amount received.

Exemplo:

1002

createdAt

string<date-time>

obrigatório

The timestamp when the transfer was created.

Exemplo:

"2026-02-01T18:30:00Z"

updatedAt

string<date-time>

obrigatório

The timestamp of the last status update.

Exemplo:

"2026-02-01T18:35:00Z"

statusHistory

object[]

obrigatório

The history of status transitions for this transfer.

Show child attributes

reconciliationAttempts

integer

obrigatório

The number of settlement queries already sent for this transfer. Always present, zero included.

Exemplo:

0

recipientLedgerId

string<uuid>

The recipient's Midaz ledger on a P2P between two ledgers of one organization. Absent on a P2P inside one ledger and on every TED.

Exemplo:

"0190a0e2-7b1c-7d3e-9f40-5a6b7c8d9e03"

ledgerGroupId

string<uuid>

The Midaz ledger group that a P2P between two ledgers posted as. Absent before the posting, when the expiry recovery completed the transfer, and on a P2P return.

Exemplo:

"0190a0e2-7b1c-7d3e-9f40-5a6b7c8d9e10"

originalTransferId

string<uuid> | null

On a return, the transfer that it returns. A TED_IN devolution refund names the TED OUT that it compensates, a TED_OUT voluntary return names the TED IN that it sends back, and a P2P return names the P2P that it reverses. On a TED IN return and a P2P return, recipient carries only the ISPB. Read the counterparty from the original transfer.

Exemplo:

"019c96a0-ab10-7cde-f1a2-0e1f2a3b4c5d"

devolutionCode

string | null

BACEN devolution reason code, present only when the transfer is a devolution.

Exemplo:

"18"

feeContext

string

The fee label that the initiation carried. Absent when it carried none.

Exemplo:

"ted_salario"

recipientAccountId

string<uuid> | null

UUID of the recipient account, when the recipient is represented as a Midaz account.

Exemplo:

"019c96a0-ac10-7efa-b1c2-2a3b4c5d6e7f"

confirmationNumber

string | null

The human-readable confirmation code, if available.

Maximum string length: 20

Exemplo:

"20260201001"

controlNumber

string | null

The JD SPB control number, present for TED OUT and TED IN transfers.

Maximum string length: 20

Exemplo:

"202602010001"

midazTransactionId

string<uuid> | null

The corresponding Midaz ledger transaction ID.

Exemplo:

"019c96a0-ac10-7efa-b1c2-2a3b4c5d6e7f"

description

string | null

The purpose or description of the transfer.

Maximum string length: 140

Exemplo:

"Payment for services"

metadata

object

Metadata that this service records on the transfer, as key-value pairs. On a return, it also carries returnReasonCode (on a TED IN return) and reversalTransactionId, the ledger transaction that reverses the original, once they are recorded. The metadata that you sent on Initiate Transfer is in clientMetadata.

clientMetadata

object

The metadata that you sent on Initiate Transfer, as key-value pairs. Absent when the transfer carries none. A TED IN transfer carries none.

Exemplo:

{ "invoiceId": "INV-2024-001" }

completedAt

string<date-time> | null

The timestamp when the transfer was completed. Null if not yet completed.

Exemplo:

"2026-02-01T18:35:00Z"

reconciliationStatus

enum<string>

The reconciliation state of the transfer, as stored. EXHAUSTED has the same meaning as MANUAL_REVIEW. Absent on a transfer that never entered reconciliation.

Opções disponíveis:

AWAITING,

RESOLVED,

REVERSING,

REVERTED,

EXHAUSTED,

MANUAL_REVIEW

Exemplo:

"MANUAL_REVIEW"

lastReconciliationAttemptAt

string<date-time>

The time of the most recent settlement query, when one was sent.

Exemplo:

"2026-02-01T15:40:00Z"

reconciliationReasonCode

string

Why the transfer entered reconciliation, in the vocabulary of the system that decided it. Absent when no reason is recorded.

Exemplo:

"JD_UNAVAILABLE"

reconciliationReasonClass

string

The class of reconciliationReasonCode. Absent when no reason is recorded.

Exemplo:

"transient"

settlementRejectionCode

string

The rejection code of the clearing house, verbatim, for example AAC90 or ALN01. Absent when there is none.

Exemplo:

"ALN01"

API de Transferências

Painel e API de Conciliação

API de Operações TED In

API de Webhooks

API de Webhook DLQ

Tratamento de erros

Eventos

Get a Transfer

Autorizações

Cabeçalhos

Parâmetros de caminho

Resposta