fluX Partners API

Integra pagos
en tu plataforma
sin fricciones

API REST diseñada para integradores. Recaudo, dispersión, cuentas virtuales y webhooks en tiempo real — todo desde un solo endpoint.

⚡ Quick Start Ver todos los endpoints →
99.9%
Uptime garantizado
<30ms
Latencia promedio
13
Endpoints
REST
JSON · HTTPS · Webhooks
Dispersión
Envía fondos a cuentas bancarias en tiempo real.
Recaudo
Recibe pagos y notifícalos vía webhook al instante.
Cuentas virtuales
Crea y administra cuentas e instrumentos por cliente.
Webhooks
Eventos push para money-in, money-out y estados.

Autenticación

Todas las peticiones requieren el header X-API-Key. Las claves tienen prefijo sk_live_ para producción y sk_test_ para sandbox.

Base URL https://api.flux.finance
🔐  Tu API Key
LIVE sk_live_••••••••••••••••••••
⚠️ Nunca compartas tu API Key en repositorios públicos ni código cliente.
Header requerido: X-API-Key: <FLUX_API_KEY> en cada request.

Quick Start

Tu primera petición — lista el catálogo de bancos disponibles.

curl -X GET https://api.flux.finance/partners/banks \
  -H "X-API-Key: <FLUX_API_KEY>" \
  -H "Content-Type: application/json"
const axios = require('axios');

const response = await axios.get('https://api.flux.finance/partners/banks', {
  headers: {
    'X-API-Key': '<FLUX_API_KEY>',
    'Content-Type': 'application/json'
  }
});
console.log(response.data);
import requests

response = requests.get(
  'https://api.flux.finance/partners/banks',
  headers={
    'X-API-Key': '<FLUX_API_KEY>',
    'Content-Type': 'application/json'
  }
)
print(response.json())

Respuesta esperada:

{
  "data": [
    {
      "id":      "bancolombia",
      "name":    "Bancolombia",
      "code":    "007",
      "country": "CO",
      "active":  true
    }
  ],
  "page":      1,
  "page_size": 20,
  "total":     48
}

Errores

La API usa códigos HTTP estándar. Los errores retornan error.code y error.message.

401
Unauthorized
API Key ausente o inválida.
400
Bad Request
Parámetros faltantes o con formato incorrecto.
404
Not Found
El recurso solicitado no existe.
409
Conflict
Request duplicado — usa Idempotency-Key.
500
Internal Server Error
Reintenta con backoff exponencial.

Bancos

GET /partners/banks?page=1&page_size=20
ParámetroTipoReq.Descripción
pageintegeropcionalNúmero de página. Default: 1
page_sizeintegeropcionalItems por página. Máx: 100

Cuentas

GET /partners/clients/{clientId}/accounts
POST /partners/clients/{clientId}/private-accounts

{
  "alias":    "cuenta-principal",
  "currency": "COP"
}
ParámetroTipoReq.Descripción
clientIdUUIDrequeridoID único del cliente.

Instrumentos

GET /partners/clients/{clientId}/instruments
GET /partners/clients/{clientId}/instruments/{instrumentId}
POST /partners/clients/{clientId}/instruments

{
  "type":           "bank_account",
  "bank_id":        "bancolombia",
  "account_number": "1234567890",
  "account_type":   "savings"
}

Transacciones

Idempotencia: Envía un UUID único en Idempotency-Key. Reintentos con el mismo key no generan cobros dobles. 
POST /partners/transactions/money-out
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000

{
  "client_id":     "uuid-del-cliente",
  "instrument_id": "uuid-del-instrumento",
  "amount":        150000,
  "currency":      "COP",
  "description":   "Pago nómina semana 21"
}
POST /partners/clients/{clientId}/transactions/{transactionId}/refund

{
  "amount": 150000,
  "reason": "customer_request"
}

Webhooks

POST /partners/webhooks/money-in es llamado por fluX hacia tu servidor. Valida X-Webhook-Token. 
GET /partners/clients/{clientId}/webhooks
POST /partners/clients/{clientId}/webhooks

{
  "url":    "https://tuapp.com/webhooks/flux",
  "events": ["money_in", "money_out"],
  "active": true
}
PATCH /partners/clients/{clientId}/webhooks/{id}

{ "active": false }
DELETE /partners/clients/{clientId}/webhooks/{id}

Seguridad

⚠️ Buenas prácticas
  • No loguear tokens ni API Keys en texto plano — usa gestores de secretos (Vault, AWS SSM).
  • Aplicar rate-limit por API Key en tu gateway.
  • Validación estricta de UUIDs y montos en el borde antes de llamar a fluX.
  • Idempotencia obligatoria en money-out: guarda el Idempotency-Key antes de enviar.
  • Valida el header X-Webhook-Token en cada evento de money-in.

Todos los endpoints

MétodoRutaDescripción
GET/partners/banksCatálogo bancario
GET/partners/clients/{clientId}/accountsListar cuentas
POST/partners/clients/{clientId}/private-accountsCrear cuenta privada
GET/partners/clients/{clientId}/instrumentsListar instrumentos
GET/partners/clients/{clientId}/instruments/{instrumentId}Detalle de instrumento
POST/partners/clients/{clientId}/instrumentsCrear instrumento
POST/partners/transactions/money-outMoney out — requiere Idempotency-Key
POST/partners/clients/{clientId}/transactions/{transactionId}/refundReembolso
GET/partners/clients/{clientId}/webhooksListar webhooks
POST/partners/clients/{clientId}/webhooksCrear webhook
PATCH/partners/clients/{clientId}/webhooks/{id}Actualizar webhook
DELETE/partners/clients/{clientId}/webhooks/{id}Eliminar webhook
POST/partners/webhooks/money-inEvento entrante — valida X-Webhook-Token