Skip to main content
POST
Process a Transfer

Authorizations

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 unique business identifier. 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

Body

application/json
initiationId
string<uuid>
required

The initiation ID returned by the Initiate Transfer endpoint. Expires after 24 hours.

Example:

"019c96a0-aa10-7abc-d1e2-8c9d0e1f2a3b"

signingArtifactId
string<uuid>

Identifier of the frozen signing artifact returned by Prepare Transfer Signature.

Example:

"019c96a0-bb10-7def-a1b2-3c4d5e6f7a8b"

payloadHash
string

SHA-256 hash of the canonical payload that was signed.

Example:

"8f0c7f5c1c7b4d9f2f5c7d1a0d4c9a2b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f"

signature
string

Base64-encoded signature for tenants that sign outside the plugin.

Example:

"base64-signature-here"

Response

Indicates that the transfer was confirmed and processing has started.

Repeated calls with the same X-Idempotency key replay the cached response.

See Retries and idempotency for more details.

transferId
string<uuid>
required

The unique transfer ID. Use this value to track the transfer status.

Example:

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

confirmationNumber
string
required

A human-readable confirmation number. Format is YYYYMMDD followed by a short hex suffix derived from the transfer ID (e.g. 20260201aa10bc3d4e5f).

Maximum string length: 20
Example:

"20260201001"

status
enum<string>
required

The current transfer status. For TED_OUT transfers, the status immediately after processing is always PROCESSING.

Available options:
CREATED,
PENDING,
PROCESSING,
COMPLETED,
REJECTED,
FAILED,
CANCELLED,
RECEIVED
Example:

"COMPLETED"

feeAmount
number<decimal>
required

The fee amount as calculated during initiation.

Example:

1.5

totalAmount
number<decimal>
required

The total amount held or transferred, including the fee.

Example:

1002

packageAppliedId
string<uuid> | null

ID of the fee package applied to this transfer, if any.

Example:

"019c96a0-ad10-7fab-c1d2-3b4c5d6e7f8a"