FondosEG API v1

Integra pagos y transferencias con una API clara y segura.

Conecta tu backend con FondosEG para consultar saldos, mover dinero, gestionar alquileres y recibir eventos en tiempo real. Empieza en pruebas y pasa a producción sin cambiar tu implementación.

Empezar a integrar Ver OpenAPI

REST + JSONSandboxWebhookHMACSDK ReadyAPI Keys

cURLPOST/v1/transfers

curl -X POST https://api.fondoseg.com/v1/transfers \
  -H "Authorization: Bearer {API_KEY}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 8f6e5b3c-2d4a-4c9e-9b91-1f2a3b4c5d6e" \
  -d '{
    "amount": 15000.50,
    "currency": "XAF",
    "from_account_id": "acc_1234567890",
    "to_account_id": "acc_9876543210",
    "description": "Pago de alquiler - Mayo 2024"
  }'

200 OKJSON

{
  "id": "trf_01J2X7H8Y9ZC3D4E5F6G7H8I9J",
  "status": "completed",
  "amount": 15000.50,
  "currency": "XAF",
  "created_at": "2024-05-20T14:33:21Z",
  "reference": "ALQ-MAYO-2024-001"
}

Webhook

transfer.completed

{
  "event": "transfer.completed",
  "data": {
    "id": "trf_01J2X7H8Y9ZC3D4E5F6G7H8I9J",
    "status": "completed",
    "amount": 15000.50
  }
}

2024-05-20T14:33:21ZEntregado ✓

REST + JSON

Interfaz estándar y predecible

Entorno test

Prueba sin mover dinero real

Webhooks HMAC

Eventos verificados y deduplicables

Inicio rápido

Tu primera petición en cuatro pasos

La ruta recomendada separa credenciales, servidor y entornos desde el primer día.

Crea una credencial

Regístrate en el portal y genera una clave en el entorno test con los permisos mínimos necesarios.

Guarda el secreto

Conserva API key y secret en variables del servidor. El secret solo se muestra una vez.

Llama desde tu backend

Envía los headers de autenticación desde una función o API propia, nunca desde el navegador.

Valida y despliega

Prueba idempotencia, errores y webhooks antes de solicitar credenciales de producción.

Autenticación

Credenciales solo en el servidor

Cada request usa una API key identificable y un secret privado. Asigna una credencial distinta a cada aplicación y entorno.

x-api-key

Identifica la aplicación y sus permisos.

x-api-secret

Autentica la petición. Nunca debe llegar al cliente.

idempotency-key

UUID único para cada POST que mueve dinero.

content-type

Usa application/json cuando envíes un body.

.env

FONDOSEG_API_KEY=sk_test_••••••••
FONDOSEG_API_SECRET=secret_••••••••
FONDOSEG_BASE_URL=https://fondoseg.com

Importante: no incluyas las credenciales en React, Flutter, aplicaciones móviles, repositorios, analytics o logs. Tu app llama a tu backend y tu backend llama a FondosEG.

Ejemplos

Consulta un saldo en minutos

La respuesta mantiene la misma estructura en pruebas y producción; el entorno test añade sandbox: true.

server.ts

const response = await fetch(
  'https://fondoseg.com/api/v1/external/balance',
  {
    headers: {
      accept: 'application/json',
      'x-api-key': process.env.FONDOSEG_API_KEY,
      'x-api-secret': process.env.FONDOSEG_API_SECRET,
    },
  }
);

const result = await response.json();
if (!response.ok) throw new Error(result.error.message);

console.log(result.data.balance);

Crear una transferencia idempotente

Si la red falla, reintenta con la misma idempotency-key. FondosEG devolverá el resultado original sin duplicar el movimiento.

transfer.ts

const response = await fetch(
  'https://fondoseg.com/api/v1/external/transfer',
  {
    method: 'POST',
    headers: {
      'content-type': 'application/json',
      'x-api-key': process.env.FONDOSEG_API_KEY,
      'x-api-secret': process.env.FONDOSEG_API_SECRET,
      'idempotency-key': crypto.randomUUID(),
    },
    body: JSON.stringify({
      sender_name: 'Cliente origen',
      sender_phone: '+240222000000',
      receiver_name: 'Cliente destino',
      receiver_phone: '+240222111111',
      destination_city: 'Malabo',
      amount: 25000,
      currency: 'XAF',
    }),
  }
);

Referencia

Endpoints disponibles

Todos los endpoints públicos están versionados bajo /api/v1/external.

GET/api/v1/external/balancebalance

Consulta el saldo disponible para la credencial.

GET/api/v1/external/historyhistory

Lista operaciones con paginación y filtros.

POST/api/v1/external/transfertransfer

Crea una transferencia operada por un gestor.

POST/api/v1/external/wallet-transfertransfer

Mueve saldo entre clientes FondosEG.

GET/api/v1/external/propertiesproperties

Consulta las propiedades visibles.

GET/api/v1/external/rentalsproperties

Consulta contratos de alquiler.

GET · POST/api/v1/external/rental-paymentspayments

Consulta o inicia pagos de alquiler.

Eventos

Webhooks firmados, estados al instante

Configura una URL HTTPS desde tu consola. Verifica la firma sobre el body sin modificar antes de procesar cualquier evento.

transfer.created

transfer.paid_out

wallet_transfer.confirmed

rental_payment.updated

webhook.ts

const rawBody = await request.text();
const timestamp = request.headers.get(
  'x-fondoseg-webhook-timestamp'
);
const signature = request.headers.get(
  'x-fondoseg-webhook-signature'
);

// HMAC SHA-256 de `${timestamp}.${rawBody}`
// con FONDOSEG_WEBHOOK_SECRET.
// Compara firmas en tiempo constante y deduplica
// por X-FondosEG-Webhook-Id.

Resiliencia

Errores predecibles y trazables

Guarda siempre el x-request-id; es la referencia que permite seguir una operación de extremo a extremo.

400validation_error

Corrige el payload; no reintentes automáticamente.

401invalid_credentials

Revisa key, secret y estado de la credencial.

403permission_denied

La clave no tiene el scope o rol requerido.

409idempotency_conflict

La misma clave se usó con otro payload.

429rate_limit_exceeded

Respeta retry-after y usa backoff exponencial.

5xxinternal_error

Reintenta con backoff y la misma idempotency-key.

Go live

Checklist antes de producción

Completa estas verificaciones con credenciales test. Después crea una clave production separada y cambia únicamente las variables del servidor.

Credenciales separadas para test y producción.

Secrets almacenados en un gestor seguro.

Idempotencia probada en todas las operaciones monetarias.

Reintentos limitados con backoff para 429 y 5xx.

Firmas y deduplicación de webhooks verificadas.

Logs con request ID, status y latencia, sin datos sensibles.

¿Listo para construir?

Crea tu cuenta de desarrollador, genera una credencial test y realiza tu primera petición. La referencia OpenAPI está disponible para automatizar el resto.

Crear cuenta OpenAPI JSON

curl -X POST https://api.fondoseg.com/v1/transfers \ -H "Authorization: Bearer {API_KEY}" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: 8f6e5b3c-2d4a-4c9e-9b91-1f2a3b4c5d6e" \ -d '{ "amount": 15000.50, "currency": "XAF", "from_account_id": "acc_1234567890", "to_account_id": "acc_9876543210", "description": "Pago de alquiler - Mayo 2024" }'

const response = await fetch( 'https://fondoseg.com/api/v1/external/balance', { headers: { accept: 'application/json', 'x-api-key': process.env.FONDOSEG_API_KEY, 'x-api-secret': process.env.FONDOSEG_API_SECRET, }, } ); const result = await response.json(); if (!response.ok) throw new Error(result.error.message); console.log(result.data.balance);

const response = await fetch( 'https://fondoseg.com/api/v1/external/transfer', { method: 'POST', headers: { 'content-type': 'application/json', 'x-api-key': process.env.FONDOSEG_API_KEY, 'x-api-secret': process.env.FONDOSEG_API_SECRET, 'idempotency-key': crypto.randomUUID(), }, body: JSON.stringify({ sender_name: 'Cliente origen', sender_phone: '+240222000000', receiver_name: 'Cliente destino', receiver_phone: '+240222111111', destination_city: 'Malabo', amount: 25000, currency: 'XAF', }), } );

const rawBody = await request.text(); const timestamp = request.headers.get( 'x-fondoseg-webhook-timestamp' ); const signature = request.headers.get( 'x-fondoseg-webhook-signature' ); // HMAC SHA-256 de `${timestamp}.${rawBody}` // con FONDOSEG_WEBHOOK_SECRET. // Compara firmas en tiempo constante y deduplica // por X-FondosEG-Webhook-Id.