Process a Transfer

Use this endpoint to confirm and execute a previously initiated transfer. The system validates the initiationId, checks the sender’s balance, holds funds in Midaz, and routes the transfer to JD SPB (for TED OUT) or creates an internal Midaz transaction (for P2P). Submitting the same initiationId returns the same transferId.

POST /v1/transfers/process

Process a Transfer

cURL

curl --request POST \
  --url https://plugin-br-bank-transfer.sandbox.lerian.net/v1/transfers/process \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Idempotency: <x-idempotency>' \
  --header 'X-Organization-Id: <x-organization-id>' \
  --data '
{
  "initiationId": "019c96a0-aa10-7abc-d1e2-8c9d0e1f2a3b"
}
'

200

success

{
  "transferId": "019c96a0-ab10-7cde-f1a2-0e1f2a3b4c5d",
  "confirmationNumber": "20260201001",
  "status": "PROCESSING",
  "feeAmount": 1.5,
  "totalAmount": 1002
}

Authorizations

Authorization · string · header · required

JWT Bearer token authentication. The token must include a tenantId claim that matches the X-Organization-Id header.

Headers

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

Organization ID used as the tenant identifier. All data is scoped to this organization. Must match the JWT tenantId claim when authentication is enabled.

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

Option 1

Option 2

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

200

application/json

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 in YYYYMMDD+sequence format.

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"