Copy page

Plataforma

Transacciones

La API de Transacciones devuelve registros de libro creados después de confirmar pagos exitosos. Úsala para conciliar pagos, auditar saldos y respaldar integraciones basadas en webhooks.

Resumen

Cada solicitud de pago confirmada produce un registro de transacción. Las transacciones incluyen montos brutos y netos, metadatos de activo y red, direcciones de origen y destino, y hashes de transacción on-chain opcionales.

Las transacciones están limitadas a la entidad autenticada:

• Claves API a nivel de cuenta — transacciones solo de esa cuenta
• Claves API a nivel de organización — todas las transacciones de la organización, o una sola cuenta cuando se proporciona accountID

Autenticación

Todas las solicitudes requieren ambos encabezados:

• Authorization: Bearer <access_token>
• x-fluxis-api-key: <your_api_key>

Listar transacciones

Code
GET /v1/transactions?page=1&page_size=50

Parámetros de consulta

Parámetro	Requerido	Descripción
page	Sí	Número de página (mínimo 1)
page_size	Sí	Elementos por página (5–100)
accountID	No	Filtrar a una cuenta específica (solo claves de organización). Debe pertenecer a tu organización

Ejemplo

Code
curl "https://api.fluxis.us/v1/transactions?page=1&page_size=50" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "x-fluxis-api-key: fxs.prd.YOUR_KEY_ID"

Para claves de organización limitadas a una cuenta:

Code
curl "https://api.fluxis.us/v1/transactions?page=1&page_size=50&accountID=c87464d1-c54a-48c3-80c9-bee4fddf593d" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "x-fluxis-api-key: fxs.prd.YOUR_KEY_ID"

Forma de la respuesta

Code
{
  "data": {
    "data": [
      {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "type": "payment_in",
        "status": "completed",
        "gross_amount": "100.00",
        "net_amount": "97.50",
        "expected_amount": "100.00",
        "currency": "USDC",
        "network": "polygon",
        "unique_asset_id": "npolygon_t0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359",
        "from": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
        "from_type": "wallet",
        "to": "0x1234567890abcdef1234567890abcdef12345678",
        "to_type": "vault",
        "financial_provider": "fluxis",
        "transaction_hash": "0xabcdef...",
        "created_at": "2026-05-21T12:00:00Z",
        "updated_at": "2026-05-21T12:05:00Z"
      }
    ],
    "total": 150,
    "page": 1,
    "page_size": 50,
    "total_pages": 3
  }
}

Tipos de transacción

Tipo	Descripción
payment_in	Pago entrante de cliente
payment_out	Pago saliente
deposit	Depósito
withdraw	Retiro
refund	Reembolso
adjustment	Ajuste manual
swap	Intercambio de activos
dry_run	Registro de prueba / vista previa

La mayoría de integraciones de comercio interactúan principalmente con registros payment_in creados cuando las solicitudes de pago alcanzan confirmed.

Estados de transacción

Estado	Descripción
preview	Estado de vista previa
pending	Esperando procesamiento
created	Registro creado
processing	En progreso
completed	Completado exitosamente
failed	Fallido
error	Estado de error
expired	Expirado

Relación con solicitudes de pago

Code
sequenceDiagram
    participant PR as Payment Request
    participant WH as Webhook
    participant TX as Transaction

    PR->>PR: processing → completed / underpaid / overpaid
    PR->>WH: payment_request_status_update
    PR->>PR: confirmed (ledger step)
    PR->>TX: payment_in transaction created

1. Los webhooks se disparan en processing, completed, underpaid y overpaid — consulta Eventos de webhook.
2. Tras la confirmación, aparece una transacción de libro en GET /v1/transactions.
3. Haz polling de transacciones como respaldo si se pierde un webhook.

Patrón de conciliación

Flujo recomendado:

1. Almacena IDs de solicitud de pago cuando creas sesiones de checkout
2. Actualiza el estado del pedido desde webhooks payment_request
3. Nightly (o bajo demanda), recorre GET /v1/transactions y concilia brechas

Documentación relacionada

• Solicitudes de pago — ciclo de vida de estados
• Eventos de webhook — actualizaciones de estado en tiempo real
• Verificación de firma de webhook — verificación HMAC para entregas de webhook
• Liquidaciones y consolidación — cómo se mueven los fondos tras la confirmación
• Guía de integración API — Paso 7 conciliación