Crear Transferencia

Crea una nueva solicitud de transferencia (Pay-Out). Los fondos se descontarán de la cuenta origen referenciada.

Restricciones de Negocio

• Monto Máximo: El monto máximo por transferencia ACH permitido por el sistema es de 20,000.00 BOB.
• Saldo Disponible: La cuenta origen debe poseer el saldo suficiente para cubrir la transferencia. En caso contrario, el servidor responderá inmediatamente con un HTTP 400 Bad Request.

Petición

• Endpoint: /api/v2/transfers
• Método: POST

Headers Requeridos

Header	Valor	Descripción
X-API-KEY	<TU_API_KEY>	Tu llave de integración API Key.
Idempotency-Key	UUID-v4	Requerido. Clave única para evitar duplicación de retiros.
Accept	application/json

Body Parameters

Atributo	Tipo	Obligatorio	Descripción
business_code	integer	Sí	Identificador único de tu comercio asociado a la API Key.
amount	numeric	Sí	Monto a transferir. Mínimo 0.10, Máximo 20000.00. Formato de dos decimales (ej. 150.50).
currency	string	Sí	Código de moneda, ej. "BOB".
reference	string	No	Referencia o glosa de la transacción para el extracto (Máximo 50 caracteres).
destination	object	Sí	Objeto polimórfico describiendo la cuenta receptora de los fondos.

Objeto destination (Tipo: bank_account)

Atributo	Tipo	Obligatorio	Descripción
type	string	Sí	Debe ser el valor estático "bank_account".
bank_code	integer	Sí	Código numérico del banco destino (ver Bancos Soportados).
account_number	string	Sí	Número de la cuenta bancaria. Solo se admiten dígitos y guiones.
account_titular	string	Sí	Nombre completo del beneficiario de la cuenta (Máximo 100 caracteres).

Ejemplo de Petición

POST /api/v2/transfers
X-API-KEY: <TU_API_KEY>
Idempotency-Key: e1a50a12-872f-4b08-8e6d-5a8b79c2356c
Content-Type: application/json

{
  "business_code": 17,
  "amount": 1500.0,
  "currency": "BOB",
  "reference": "Pago a Proveedor Factura 001",
  "destination": {
    "type": "bank_account",
    "bank_code": 1,
    "account_number": "123456-7",
    "account_titular": "Juan Pérez"
  }
}

Respuesta

Respuesta Exitosa (HTTP 201 Created)

Si el Idempotency-Key es nuevo y los fondos de la cuenta origen están disponibles, la API devolverá inmediatamente el recurso creado con el estado "PENDING".

{
  "id": 123,
  "business_code": 17,
  "status": "PENDING",
  "amount": 1500.0,
  "currency": "BOB",
  "reference": "Pago a Proveedor Factura 001",
  "destination": {
    "type": "bank_account",
    "bank_code": 1,
    "account_number": "******-7",
    "account_titular": "Juan Pérez"
  },
  "created_at": "2026-05-15T15:00:00Z"
}

Respuestas de Error Comunes

Nota General: Para validar estructuras de errores comunes como validaciones (HTTP 422), revisa Códigos HTTP y Errores.

HTTP 400 Bad Request (Saldo Insuficiente)

Ocurre cuando el monto de la transferencia supera el saldo disponible actual en la cuenta.

{
  "type": "business_logic_error",
  "code": "INSUFFICIENT_FUNDS",
  "message": "No tiene suficiente saldo para realizar la operación."
}

HTTP 403 Forbidden (Módulo no Habilitado)

Ocurre cuando el comercio no ha activado los permisos de transferencias ACH.

{
  "type": "permission_error",
  "code": "MODULE_NOT_ENABLED",
  "message": "No tiene habilitado este módulo para realizar transferencias."
}