Transferencias, depósitos y retiros

Las tres operaciones de /api/v1/payments mueven dinero con doble partida contable y exigen la clave API con alcance payment:write y la cabecera Idempotency-Key.

Operación	Ruta	Cuentas
Transferencia interna	POST /api/v1/payments/transfer	Origen y destino del mismo banco, misma moneda.
Depósito	POST /api/v1/payments/deposit	Solo destino (el dinero viene de fuera).
Retiro	POST /api/v1/payments/withdrawal	Solo origen.

Transferir entre cuentas

curl -s -X POST https://api.banco.example/api/v1/payments/transfer \
  -H "X-Api-Key: $FINORA_API_KEY" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceAccountId": "3d0c4f0e-9c7f-4b8e-8c1a-0a5b5f1d2e11",
    "destinationAccountId": "8b7e6d5c-4a3f-4e2d-9c1b-0a9f8e7d6c5b",
    "amount": 500.00,
    "currency": "VES",
    "reference": "FACT-2026-001",
    "description": "Pago de factura 2026-001"
  }'

Campo	Obligatorio	Notas
sourceAccountId, destinationAccountId	sí	UUID de cuentas activas.
amount	sí	Mayor que cero, hasta 15 enteros y 4 decimales.
currency	sí	ISO 4217; debe coincidir con la de ambas cuentas.
reference	no	Hasta 100 caracteres. Una referencia ya usada en la cuenta responde 409 (duplicate-reference).
description	no	Hasta 250 caracteres.

Respuesta 201 (o 200 si es una repetición idempotente):

{
  "paymentId": "770e8400-e29b-41d4-a716-446655440222",
  "status": "COMPLETED",
  "amount": 500.00,
  "currency": "VES",
  "sourceAccountId": "3d0c4f0e-9c7f-4b8e-8c1a-0a5b5f1d2e11",
  "destinationAccountId": "8b7e6d5c-4a3f-4e2d-9c1b-0a9f8e7d6c5b",
  "reference": "FACT-2026-001",
  "ledgerRef": "VCH-20261013-00042",
  "executedAt": "2026-10-13T11:15:00-04:00",
  "idempotencyKey": "550e8400-e29b-41d4-a716-446655440000"
}

ledgerRef correlaciona el pago con su asiento contable. status puede ser COMPLETED, PENDING, FAILED o REVERSED.

Depositar en una cuenta

curl -s -X POST https://api.banco.example/api/v1/payments/deposit \
  -H "X-Api-Key: $FINORA_API_KEY" \
  -H "Idempotency-Key: 3e1b9d7f-0c5a-4f28-8b6e-2a4d6f8c0e13" \
  -H "Content-Type: application/json" \
  -d '{
    "destinationAccountId": "3d0c4f0e-9c7f-4b8e-8c1a-0a5b5f1d2e11",
    "amount": 1500.00,
    "currency": "VES",
    "externalReference": "CAJA-20261013-0042",
    "description": "Depósito en efectivo",
    "channel": "API"
  }'

channel admite AGENCIA, ATM, API o INTERBANKING. externalReference (hasta 100 caracteres) sirve para conciliar con tu sistema.

Retirar de una cuenta

curl -s -X POST https://api.banco.example/api/v1/payments/withdrawal \
  -H "X-Api-Key: $FINORA_API_KEY" \
  -H "Idempotency-Key: 8f2c4a6e-1b3d-4e5f-9a7c-0d2e4f6a8b19" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceAccountId": "3d0c4f0e-9c7f-4b8e-8c1a-0a5b5f1d2e11",
    "amount": 300.00,
    "currency": "VES",
    "reference": "RET-20261013-001",
    "description": "Retiro en ventanilla",
    "channel": "AGENCIA"
  }'

channel admite AGENCIA, ATM, API, WEB o MOBILE.

Reintentos seguros

Errores

HTTP	Sufijo de type	Cuándo
400	validation-error, invalid-idempotency-key	Campos inválidos o Idempotency-Key ausente.
404	account-not-found	La cuenta no existe. Hoy también cuando está bloqueada o cerrada.
409	idempotency-key-reused, duplicate-reference	Clave usada con otra petición, o referencia repetida en la cuenta.
422	insufficient-funds	Saldo disponible insuficiente u otra regla de negocio.

Para transferencias hacia otros bancos, el core expone las rutas de /api/v1/interbank, que se documentan en la referencia.