Intenciones y rieles

Una intención es la venta que quieres cobrar: monto, moneda y tu referencia. Un riel es un medio por el que se puede cobrar (tarjeta en un terminal, pago móvil, crédito inmediato…). Los rieles disponibles dependen de la configuración bancaria de cada comercio, así que tu sistema debe consultarlos en lugar de suponerlos.

Todas las rutas usan tu clave API (X-API-Key) con alcance INTEGRACION o COMPLETO. Ver Autenticación y alcance.

1. Consultar los rieles del comercio

curl -s "https://pos.finoracore.com/api/v1/pagos/rieles?merchantCode=COM00042&amount=2499.00" \
  -H "X-API-Key: $FINORA_API_KEY"

Con amount, solo vuelven los rieles que cubren ese monto (entre sus mínimos y máximos).

{
  "merchantCode": "COM00042",
  "payerIdMode": "POR_RIEL",
  "payerDocTypes": ["V", "E", "J", "G", "P"],
  "currency": "VES",
  "rails": [
    {
      "code": "PAGO_MOVIL",
      "name": "Pago móvil",
      "medio": "PAGO_MOVIL",
      "temporalidad": "SINCRONA",
      "allowsPartial": false,
      "requiresAuthorizer": false,
      "minAmount": null,
      "maxAmount": null,
      "timeoutSeconds": 120,
      "instructions": null,
      "requiresPayerId": true,
      "confirmacionEnLinea": true,
      "campos": [
        { "code": "telefono", "label": "Teléfono", "fieldType": "TELEFONO", "required": true,
          "validationRegex": "^0(412|414|416|424|426)[0-9]{7}$", "minLength": null, "maxLength": null,
          "displayOrder": 1, "prefilledValue": null, "helpText": null }
      ],
      "requiereTerminal": false,
      "disponible": true,
      "motivoNoDisponible": null
    }
  ]
}

Campo	Para qué te sirve
payerIdMode	Cuándo pedir el documento del pagador: NUNCA, ANTES_DE_MEDIOS (una vez, antes de elegir el medio) o POR_RIEL (según requiresPayerId de cada riel).
rails[].campos	Los datos que pide el riel, con tipo (CEDULA, TELEFONO, BANCO, SECRETO, TEXTO, NUMERO, CORREO), validación y orden. Construye tu formulario con ellos.
rails[].requiereTerminal	El riel necesita un terminal físico (por ejemplo, tarjeta).
rails[].disponible, motivoNoDisponible	Si el riel está temporalmente fuera de servicio y por qué. Muéstralo deshabilitado, no lo ocultes.

Describe los medios a tu cliente por su name: los rieles se configuran por comercio y pueden cambiar sin que cambie tu integración.

2. Crear la intención

curl -s -X POST https://pos.finoracore.com/api/v1/pagos/intenciones \
  -H "X-API-Key: $FINORA_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "idempotencyKey": "ped-8841-2026-10-20",
    "merchantCode": "COM00042",
    "amount": 2499.00,
    "currency": "VES",
    "description": "Pedido delivery",
    "externalOrderId": "PED-8841"
  }'

Campo	Obligatorio	Notas
idempotencyKey	sí	Repetirla devuelve la misma intención: crear y reintentar se ven igual (200).
merchantCode	sí	Tu comercio o una agencia dentro del alcance de la clave.
amount, currency	sí	Unidades con decimales.
description, externalOrderId	no	Tu descripción y tu número de pedido.
despacho	no	Para empujar la venta a un terminal en el mismo viaje. Ver Cobro empujado.

{
  "reference": "FNRLZ3K9Q1",
  "state": "CREADA",
  "amount": 2499.00,
  "capturedAmount": 0,
  "pendingAmount": 2499.00,
  "currency": "VES",
  "rails": [],
  "attempts": [],
  "despacho": null
}

Guarda reference junto a tu pedido: es la clave de todas las operaciones siguientes.

3. Seguir el estado

curl -s https://pos.finoracore.com/api/v1/pagos/intenciones/FNRLZ3K9Q1 -H "X-API-Key: $FINORA_API_KEY"

state	Significado
CREADA	La venta existe; todavía no hay cobro.
EN_CURSO	Hay un cobro en marcha.
PARCIAL	Se cobró una parte por un riel y falta el resto (una venta puede repartirse entre medios).
PAGADA	Cobrada por completo: entrega el pedido.
FALLIDA	El cobro no se completó.
VENCIDA	Pasó su plazo sin cobrarse.
ANULADA	Se anuló.

• capturedAmount y pendingAmount dicen cuánto se cobró y cuánto falta: una venta puede pagarse con varios medios.
• attempts lista los intentos de cobro con su riel y su veredicto.
• Para recibir un aviso en lugar de consultar, crea la venta como sesión de checkout con webhookUrl.

Errores

HTTP	codigo	Qué hacer
401	CLAVE_INVALIDA	Revisar la clave.
403	CLAVE_SIN_ACCESO_AL_COMERCIO	El merchantCode está fuera del alcance de tu clave.
404	INTENCION_NO_ENCONTRADA	Corregir la referencia.
409	ESTADO_INVALIDO	La intención no admite la operación en su estado.

Próximamente en el contrato

El listado de intenciones (GET /api/v1/pagos/intenciones), los intentos de cobro por riel desde tu sistema y el reenvío del comprobante se documentarán cuando se incorporen al contrato público.