Return a Transfer
Use this endpoint to return one completed transfer to the party that paid it. The return is a new transfer that names the original in originalTransferId. What happens depends on the type of the original.
TED IN. The original must be a COMPLETED TED_IN received as STR0008R2. The plugin places a hold of the credited amount on the recipient’s account. It then sends a voluntary STR0010, return reason code 70, which returns the gross amount of the TED IN to the paying bank. The return is a TED_OUT with no fee, and the answer is PROCESSING. The final outcome arrives later. When the STR settles the return, the plugin reverts the original credit in the ledger. When nothing proves whether the STR0010 left, the answer carries reconciliationStatus AWAITING, and reconciliation decides. A customer credit with a TED_IN_STR type cannot be returned.
A TED IN return runs only inside the operating window of the tenant. On 24 December and on the last business day of the year, the window for returns closes no later than 13:00. The return posts on the TED_OUT ledger routing of the ledger of the TED IN. It cannot be cancelled or sent back to the reconciliation queue by hand.
P2P. The original must be a COMPLETED P2P that is not a return itself. The ledger reverses the original transaction in this request: the return debits the account that received the original and credits the account that paid it. The answer is COMPLETED, and the original stays COMPLETED. A P2P return has no operating window, no hold, and no ledger routing. On a P2P inside one ledger, the plugin first checks the balance of the account that received the original. If the outcome in the ledger is unknown, the answer is 503 BTF-2000, and transferId names the return, still CREATED. Send the same request again under a new X-Idempotency key: it resumes that return and never creates a second one.
A return needs Midaz 4.1.3 or later, and 4.2.0 or later for a P2P between two ledgers. A transfer has one live return at most. The body is optional and accepts only externalReference. A request with an application token must send it.
This endpoint requires the transfers:return permission.
Autorizações
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
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.
Required idempotency key for safe retries. Use a UUID v4 or a unique business identifier, made of letters, digits, ., _, and -. If the same key is sent again and the original request was already processed, the cached response is returned.
See Retries and idempotency for details.
255^[a-zA-Z0-9._-]+$Parâmetros de caminho
The unique identifier of the TED IN or P2P to return.
Corpo
The reference of your system for this return. Required when the token belongs to an application.
The reference of your system for this return. The plugin records it on the return and in its audit, and sends it back in the answer. Required when the token belongs to an application. Do not put personal data in it.
128^[A-Za-z0-9._:/-]{1,128}$"crm-ticket-88231"
Resposta
Indicates that the return was created. The body depends on type: TED_OUT for the return of a TED IN, P2P for the return of a P2P.
- Option 1
- Option 2
The return of a TED IN.
The return, a new TED_OUT transfer.
"9b2f1c7e-4d3a-4f1e-9c2b-7a6d5e4f3a21"
The TED IN that this return sends back.
"660e8400-e29b-41d4-a716-446655440002"
TED_OUT "TED_OUT"
The final status arrives later.
PROCESSING "PROCESSING"
Present when nothing proves whether the STR0010 left. Reconciliation then decides.
AWAITING "AWAITING"
The gross amount of the TED IN, sent in the STR0010. It is not the net amount credited to the recipient.
1500
The return reason code sent in the STR0010. Always 70.
"70"
The control number (NumCtrlIF) of the STR0010 sent.
"20261014a1b2c3d4e5f6"
The STR control number (NumCtrlSTR) of the original STR0008.
"STR20261013033030760"
The channel that the token names.
user, application, unknown "application"
The externalReference of the request, when one was sent.
"crm-ticket-88231"
"2026-10-14T15:30:00Z"