Tu primer cobro desde tu sistema

Al terminar este tutorial habrás pedido tres cobros a FINORA Pago desde la línea de comandos, como lo haría tu sistema de caja: uno aprobado, uno rechazado y uno en duda. Todo en modo de prueba, contra el banco simulado de FINORA: no se mueve dinero real.

No necesitas programar nada todavía. Usaremos curl, que viene con Windows 10 y 11. Lo que aprendas aquí se traduce línea por línea a C#, Java, Python o lo que use tu caja.

Antes de empezar

• Un equipo con Windows 10 u 11 y FINORA Pago instalado y configurado con el RIF y la clave de API de un comercio de pruebas. Si aún no lo tienes: Instalar y configurar FINORA Pago.
• En Configuración, Sandbox por defecto activado, o recuerda poner "sandbox": true en cada cobro.
• Una ventana de PowerShell. Los ejemplos usan curl.exe, con la extensión, para que PowerShell no lo confunda con su propio comando.

1. Comprueba que FINORA Pago te escucha

1. Mira la bandeja de Windows, junto al reloj: el icono de FINORA Pago debe estar ahí.

2. Pregúntale por su salud:

   curl.exe -s http://127.0.0.1:9810/v1/salud

3. Lee la respuesta. Debe parecerse a esto (abreviada; trae más campos):

   {"version":"1.9.0","comercio":{"rif":"J123456789","nombre":"Comercio Demo FINORA C.A."},
    "merchantAlcanzable":true,"ventanaAbierta":false,"cobroEnCurso":null,"puerto":9810,"sandboxPorDefecto":true}

   Lo importante: comercio trae tu comercio de pruebas y merchantAlcanzable es true. Si no, revisa Comprobar que FINORA Pago está en línea.

Si configuraste un token local

Agrega la cabecera a cada petición: -H "X-Pago-Token: <TU_TOKEN_LOCAL>". Sin ella, FINORA Pago responde 401 TOKEN_LOCAL_INVALIDO.

2. Pide un cobro con ventana

Vas a pedir 227,00 por el pedido 8841 y esperar el veredicto en la misma llamada.

1. Guarda el pedido en un archivo cobro.json. Así evitas pelear con las comillas de PowerShell:

   {
     "monto": 227.00,
     "referencia": "8841",
     "descripcion": "Pedido 8841",
     "mostrar": true,
     "esperar": true,
     "sandbox": true
   }

2. Envíalo:

   curl.exe -s -X POST http://127.0.0.1:9810/v1/cobros -H "Content-Type: application/json" --data-binary "@cobro.json"

   La terminal se queda esperando. Es lo correcto: con "esperar": true, la respuesta llega cuando el cobro termina.

3. Mira la pantalla: se abrió la ventana de pago con el rótulo Sandbox: sin dinero real y el total 227,00. Haz de cliente: elige Pago móvil, escribe una cédula de prueba y un teléfono con formato válido (por ejemplo, 04141234567), el código de 4 dígitos de un banco y cualquier clave de 4 dígitos. Pulsa Pagar.

4. La ventana muestra APROBADA. Pulsa OK (o espera el cierre automático).

5. Vuelve a PowerShell. Ya llegó la respuesta. Busca estos campos:

   {
     "cobroId": "CB…",
     "estado": "APROBADA",
     "codigo": "00",
     "referencia": "8841",
     "autorizacion": { "referenciaBanco": "PM…", "autorizador": "BANCO_SIM" },
     "sandbox": true
   }

   • estado es lo único que tu caja necesita para decidir: APROBADA = entregar.
   • cobroId identifica este cobro. Tu caja debe guardarlo junto a la venta.
   • autorizador: BANCO_SIM confirma que respondió el banco simulado.

3. Provoca un rechazo

El banco simulado decide por los céntimos del monto. Con .51 rechaza por fondos insuficientes.

1. Cambia en cobro.json el monto a 10.51 y la referencia a 8842.

2. Envía el cobro igual que antes y completa el pago móvil en la ventana.

3. La ventana muestra el rechazo con el motivo Fondos insuficientes y te ofrece intentar de nuevo, elegir otro medio o cancelar. Pulsa Cancelar.

4. En PowerShell verás "estado": "RECHAZADA" y "codigo": "51". Tu caja no entrega y ofrece otro medio.

4. Provoca una duda

Con .96, el banco simulado no responde a tiempo: el cobro queda en duda y se aprueba minutos después.

1. Cambia el monto a 20.96 y la referencia a 8843. Envía y completa el pago en la ventana.

2. La ventana dice Aún no tenemos la respuesta del banco. No pagues de nuevo. En PowerShell llega "estado": "EN_DUDA". Copia el cobroId.

3. Espera unos minutos y consulta ese mismo cobro (cambia CB… por tu cobroId):

   curl.exe -s "http://127.0.0.1:9810/v1/cobros/CB…"

4. Cuando el banco simulado lo resuelva, la consulta trae el veredicto definitivo. Si todavía no cambió, vuelve a preguntar más tarde.

Lo que acabas de ver es la regla más importante

Ante EN_DUDA tu caja no entrega y no vuelve a cobrar: consulta el mismo cobroId hasta tener la respuesta. Por qué: Aprobado, en duda y rechazado. Qué hacer en el mostrador: Resolver un cobro en duda.

5. Lo mismo desde tu lenguaje

El mismo cobro del paso 2, en tres lenguajes. Todos esperan el veredicto y deciden por estado.

C#

using System.Net.Http.Json;

var http = new HttpClient { BaseAddress = new Uri("http://127.0.0.1:9810"), Timeout = TimeSpan.FromSeconds(930) };
var respuesta = await http.PostAsJsonAsync("/v1/cobros", new {
    monto = 227.00m, referencia = "8841", mostrar = true, esperar = true, sandbox = true
});
var cobro = await respuesta.Content.ReadFromJsonAsync<Cobro>();

switch (cobro?.estado) {
    case "APROBADA": Entregar(cobro.cobroId); break;
    case "EN_DUDA":  RetenerVenta(cobro.cobroId); break;   // no vuelvas a cobrar
    default:         OfrecerOtroMedio(cobro?.codigo); break;
}

record Cobro(string cobroId, string estado, string? codigo);

Python

import requests

r = requests.post("http://127.0.0.1:9810/v1/cobros",
    json={"monto": 227.00, "referencia": "8841", "mostrar": True, "esperar": True, "sandbox": True},
    timeout=930)
cobro = r.json()

if cobro.get("estado") == "APROBADA":
    entregar(cobro["cobroId"])
elif cobro.get("estado") == "EN_DUDA":
    retener_venta(cobro["cobroId"])   # no vuelvas a cobrar
else:
    ofrecer_otro_medio(cobro.get("codigo"))

Programa (sin HTTP)

"%LOCALAPPDATA%\Programs\finora-pago\finora-pago.exe" cobrar --monto 227.00 --referencia 8841 --sandbox true --json > ultimo-cobro.json
echo %ERRORLEVEL%

%ERRORLEVEL% vale 0 si se aprobó, 1 si se rechazó o canceló, 2 si quedó en duda y 3 si hubo un error. El JSON del cobro queda en ultimo-cobro.json.

El plazo de espera

Con "esperar": true, la llamada puede durar tanto como el plazo del cobro (15 minutos por defecto). Dale a tu cliente HTTP un tiempo de espera mayor que ese plazo; si se rinde antes, el cobro sigue vivo del otro lado y tendrás que consultarlo.

Lo que lograste

• Comprobaste la salud de FINORA Pago.
• Pediste un cobro con ventana y recibiste el veredicto en la misma llamada.
• Provocaste un rechazo y una duda, y viste cómo se resuelve una duda consultando el mismo cobro.

Siguiente paso

• Verificar el aviso firmado, si prefieres que FINORA Pago le avise a tu caja.
• La referencia de la API local, con todos los campos y errores.
• Montos de prueba del banco simulado, para ensayar cada caso.