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.

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",
  "resolvedAt": "2026-09-06T12:00:00Z",
  "midazTransactionId": "11111111-2222-3333-4444-555555555555",
  "compensationTransactionId": "66666666-7777-4888-9999-aaaaaaaaaaaa",
  "previousCompensationTransactionId": "33333333-4444-4555-8666-777777777777"
}

Authorizations

BearerAuthOAuth2ClientCredentialsOAuth2Password

Authorization · string · header · required

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

Headers

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

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 · required

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._-]+$

Path Parameters

transferId · string<uuid> · required

The unique identifier of the transfer.

Body

application/json

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

action · enum<string> · required

Available options: SETTLE, REVERT, RE_POST, SETTLED_BY_HAND

Example:

"SETTLE"

reason · string · required

Required string length: 10 - 500

Example:

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

evidenceReference · string

Required for SETTLED_BY_HAND.

Maximum string length: 200

Example:

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

Example:

"STR20261019000000001"

Response

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.

transferId · string<uuid>

Example:

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

status · string

Example:

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

Example:

"RESOLVED"

resolvedAt · string<date-time>

Example:

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

midazTransactionId · string<uuid>

Example:

"11111111-2222-3333-4444-555555555555"

compensationTransactionId · string<uuid>

Example:

"66666666-7777-4888-9999-aaaaaaaaaaaa"

previousCompensationTransactionId · string<uuid>

Example:

"33333333-4444-4555-8666-777777777777"