Resolve Transfer Reconciliation

Use this endpoint to resolve by hand one transfer that reconciliation parked in manual review.

On an outbound TED whose hold is preserved:

• SETTLE commits the hold and completes the transfer.
• REVERT cancels the hold and fails the transfer.

On an inbound credit whose STR0010R2 chargeback refund the automatic path could not finish:

• RE_POST pays the refund again. Before it pays anything, it asks the ledger what became of the compensation already on file. Only a compensation that moved nothing licenses a posting. One that already moved the gross closes the row where it stands, with nothing posted. One that moved any other amount is refused for good. Even the licensed case first searches the ledger for this chargeback’s own refunds and adopts a live one already paying the gross instead of filing a second, so a refund that was paid can never be paid twice. A compensation on file that the ledger prices as live enters that same search as one of its members, so while a second live refund stands beside it, the row is not closed on it and no difference is quoted against it.
• SETTLED_BY_HAND posts nothing and records that the refund was arranged outside this platform, so it requires an evidenceReference that names the outside movement. Because this record also takes the row off the pending list, it is filed only over a ledger reading that completed and priced every posting it saw. A scan that the ledger truncated, a scan that it could not answer, and a scan holding a posting in a status this service cannot price are each refused as not confirmed instead of closed. Send the same request again under a new X-Idempotency key.

On an outbound TED that a return (STR0010R2) reached before it completed:

• REFUND pays the payer the refund of that return. The plugin does not refund such a return on its own. It parks the return, and List Pending Reconciliation lists the TED OUT with failureCode TED_OUT_DEVOLUTION_PARKED. REFUND needs a COMPLETED TED OUT and answers 409 BTF-0110 for any other. It posts the refund that a return on a completed TED OUT gets automatically, with the same posting, the same fee rule, and the same ledger key, and it answers refundTransferId and refundStatus. The fee follows the decision that devolution_notified announced when the return arrived. A repeat answers the same refund and posts nothing. A REFUND that answered 5xx left its refund unfinished and the TED OUT on the list: send it again under a new X-Idempotency key. When the ledger shows no credit for the refund, which does not prove that none landed, the repeat posts nothing and answers 409 BTF-0110 with the refund in transferId. Search the ledger for a transaction whose aggregateId is that transferId. If there is none, send REFUND with an evidenceReference that names the search, and the plugin posts the refund again under the same ledger key. Two REFUND requests at the same time post one refund, and the other answers 409 BTF-0110. When the ledger refused the refund, the TED OUT leaves the list and that money follows the path of any refused inbound credit.

When the ledger holds more than one live refund for a chargeback, this platform debited the beneficiary more than once, and no action here takes a posting back: RE_POST is refused, and SETTLED_BY_HAND closes the row with every one of those transactions named on the closing record.

On every action except RE_POST, the ledger moves first, and the row is written only once the ledger reaches the state that the resolution claims, so a failure midway leaves the transfer exactly as it was found. RE_POST runs in the other order, because it is the one action that pays: the new compensation is stamped on the transfer the moment the ledger returns its ID, before anything judges what it paid. Every later failure leaves the row parked and naming the money, and repeating the identical request under a new X-Idempotency key (the key that earned the failure is fenced) converges on that stamp instead of paying a second time. A stamped compensation that the ledger cannot find is undecided, not absent, and is refused: wait, repeat the identical request under a new X-Idempotency key, and close the row with SETTLED_BY_HAND if it never clears. A refund that the ledger prices at anything other than the gross is a verdict that no retry changes, whether it is the compensation on file, one that the ledger scan found, or the one that this request filed: the row stays parked, the remaining difference is settled outside this platform, and the row is closed with SETTLED_BY_HAND.

On a voluntary return of a TED IN (a TED_OUT that names the TED IN in originalTransferId), the reason code on the row (reconciliationReasonCode) decides which actions resolve it:

• return_settlement_unknown and return_settlement_unknown_exhausted: SETTLE or REVERT. SETTLE requires clearingControlNumber, the STR control number read from the clearing house.
• return_hold_release_pending: REVERT.
• return_already_returned_at_str: SETTLE or REVERT.
• return_settled_revert_pending: SETTLE.
• return_revert_failed and return_settled_after_rejection: SETTLE or SETTLED_BY_HAND.
• return_duplicate_settlement and return_returned_by_payer: SETTLED_BY_HAND.

A TED IN whose chargeback arrived after its voluntary return is parked under chargeback_after_return and closes with SETTLED_BY_HAND. Any other pair of reason code and action, and a pair that the state of the row does not allow, is refused with 409 BTF-0110. On a return that already carries a settlement proof, a clearingControlNumber that differs from that proof is also refused with 409 BTF-0110. Everywhere else the plugin ignores clearingControlNumber and does not store it.

The operator reason is required on every action. It is recorded in the audit trail with the subject resolved from the bearer token. This endpoint requires the transfers:resolve permission and a user token.

POST /v1/transfers/{transferId}/reconciliation/resolve

Resolve Transfer Reconciliation

cURL

curl --request POST \
  --url https://api.example.com/v1/transfers/{transferId}/reconciliation/resolve \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Idempotency: <x-idempotency>' \
  --header 'X-Organization-Id: <x-organization-id>' \
  --data '
{
  "action": "SETTLE",
  "reason": "JD cabine ticket 4471 confirms settlement at 10:42",
  "evidenceReference": "STR0008 ctrl 202609061042",
  "clearingControlNumber": "STR20261019000000001"
}
'

200

{
  "transferId": "770e8400-e29b-41d4-a716-446655440003",
  "status": "COMPLETED",
  "reconciliationStatus": "RESOLVED",
  "refundTransferId": "88888888-9999-4aaa-8bbb-cccccccccccc",
  "refundStatus": "COMPLETED",
  "resolvedAt": "2026-09-06T12:00:00Z",
  "midazTransactionId": "11111111-2222-3333-4444-555555555555",
  "compensationTransactionId": "66666666-7777-4888-9999-aaaaaaaaaaaa",
  "previousCompensationTransactionId": "33333333-4444-4555-8666-777777777777"
}

Autorizaciones

BearerAuthOAuth2ClientCredentialsOAuth2Password

Authorization · string · header · requerido

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

Scopes

api · OAuth2ClientCredentials

TED transfer API access

api · OAuth2Password

TED transfer API access

Encabezados

X-Organization-Id · string<uuid> · requerido

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.

X-Idempotency · string · requerido

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.

Maximum string length: 255

Pattern: ^[a-zA-Z0-9._-]+$

Parámetros de ruta

transferId · string<uuid> · requerido

The unique identifier of the transfer.

Cuerpo

application/json

Operator decision, justification, and evidence reference (required for SETTLED_BY_HAND).

action · enum<string> · requerido

Opciones disponibles: SETTLE, REVERT, RE_POST, SETTLED_BY_HAND, REFUND

Ejemplo:

"SETTLE"

reason · string · requerido

Required string length: 10 - 500

Ejemplo:

"JD cabine ticket 4471 confirms settlement at 10:42"

evidenceReference · string

Required for SETTLED_BY_HAND.

Maximum string length: 200

Ejemplo:

"STR0008 ctrl 202609061042"

clearingControlNumber · string

The STR control number read from the clearing house. Required only on the SETTLE of a voluntary return of a TED IN parked under return_settlement_unknown or return_settlement_unknown_exhausted.

Maximum string length: 20

Pattern: ^[A-Za-z0-9]{1,20}$

Ejemplo:

"STR20261019000000001"

Respuesta

200

application/json

Indicates that the transfer was resolved. On a voluntary return of a TED IN, reconciliationStatus can also be AWAITING, when the row went back to the reconciliation worker, or MANUAL_REVIEW, when the row stays parked with the failure recorded on it. A ledger reference that names nothing is omitted instead of sent as the all-zeroes UUID: compensationTransactionId and previousCompensationTransactionId belong to the inbound actions, and midazTransactionId is absent on an inbound close of a row whose credit transaction was never proven. On a REFUND, refundTransferId and refundStatus name the refund.

transferId · string<uuid>

Ejemplo:

"770e8400-e29b-41d4-a716-446655440003"

status · string

Ejemplo:

"COMPLETED"

reconciliationStatus · string

The reconciliation status after the resolution. On a voluntary return of a TED IN, it can also be AWAITING or MANUAL_REVIEW. Empty on a REFUND of a TED OUT that carries none.

Ejemplo:

"RESOLVED"

refundTransferId · string<uuid>

The refund that a REFUND posted for the return parked on the TED OUT. Absent on the other actions.

Ejemplo:

"88888888-9999-4aaa-8bbb-cccccccccccc"

refundStatus · string

COMPLETED when the payer was credited. FAILED when the ledger refused the credit and the money took the undeliverable path. Absent on the other actions.

Ejemplo:

"COMPLETED"

resolvedAt · string<date-time>

Ejemplo:

"2026-09-06T12:00:00Z"

midazTransactionId · string<uuid>

Ejemplo:

"11111111-2222-3333-4444-555555555555"

compensationTransactionId · string<uuid>

Ejemplo:

"66666666-7777-4888-9999-aaaaaaaaaaaa"

previousCompensationTransactionId · string<uuid>

Ejemplo:

"33333333-4444-4555-8666-777777777777"