Procesar una Transferencia

Utilice este endpoint para confirmar y ejecutar una transferencia previamente iniciada. El sistema valida el initiationId, verifica el saldo del remitente, retiene fondos en Midaz y enruta la transferencia a JD SPB (para TED OUT) o crea una transacción interna en Midaz (para P2P). Enviar el mismo initiationId devuelve el mismo transferId.

POST /v1/transfers/process

Procesar una Transferencia

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>' \
  --data '
{
  "initiationId": "019c96a0-aa10-7abc-d1e2-8c9d0e1f2a3b"
}
'

200

success

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

Autorizaciones

Authorization · string · header · requerido

Autenticación mediante token JWT Bearer. El tenantId se deriva del token bearer o del contexto autenticado de la solicitud y no se proporciona a través de X-Organization-Id.

Encabezados

X-Organization-Id · string<uuid>

Alcance de organización Midaz para la solicitud. En despliegues multi-tenant este header es obligatorio. Este no es el identificador del tenant; el tenantId se deriva del JWT bearer o del contexto autenticado. En despliegues single-tenant los valores de X-Organization-Id proporcionados por el llamador son rechazados y la organización es proporcionada por SINGLE_TENANT_ORGANIZATION_ID.

X-Idempotency · string · requerido

Clave de idempotencia requerida para reintentos seguros. Utilice un UUID v4 o un identificador de negocio único. Si se envía la misma clave nuevamente y la solicitud original ya fue procesada, se devuelve la respuesta almacenada en caché.

Consulte Reintentos e idempotencia para más detalles.

Maximum string length: 255

Cuerpo

application/json

Option 1

Option 2

initiationId · string<uuid> · requerido

El ID de iniciación devuelto por el endpoint Iniciar Transferencia. Expira después de 24 horas.

Ejemplo:

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

signingArtifactId · string<uuid>

Identificador del artefacto de firma congelado devuelto por Prepare Transfer Signature.

Ejemplo:

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

payloadHash · string

Hash SHA-256 del payload canónico que fue firmado.

Ejemplo:

"8f0c7f5c1c7b4d9f2f5c7d1a0d4c9a2b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f"

signature · string

Firma codificada en Base64 para tenants que firman fuera del plugin.

Ejemplo:

"base64-signature-here"

Respuesta

200

application/json

Indica que la transferencia fue confirmada y el procesamiento ha comenzado.

Las llamadas repetidas con la misma clave X-Idempotency reproducen la respuesta en caché.

Consulte Reintentos e idempotencia para más detalles.

transferId · string<uuid> · requerido

El ID único de la transferencia. Utilice este valor para rastrear el estado de la transferencia.

Ejemplo:

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

confirmationNumber · string · requerido

Un número de confirmación legible en formato AAAAMMDD+secuencia.

Maximum string length: 20

Ejemplo:

"20260201001"

status · enum<string> · requerido

El estado actual de la transferencia. Para transferencias TED_OUT, el estado inmediatamente después del procesamiento es siempre PROCESSING.

Opciones disponibles: CREATED, PENDING, PROCESSING, COMPLETED, REJECTED, FAILED, CANCELLED, RECEIVED

Ejemplo:

"COMPLETED"

feeAmount · number<decimal> · requerido

El monto de la tarifa calculada durante la iniciación.

Ejemplo:

1.5

totalAmount · number<decimal> · requerido

El monto total retenido o transferido, incluyendo la tarifa.

Ejemplo:

1002

packageAppliedId · string<uuid> | null

ID del paquete de comisiones aplicado a esta transferencia, si corresponde.

Ejemplo:

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