Crea una sesión de cobro

Cada pedido que se paga en línea necesita su sesión. La crea tu servidor, nunca el navegador, porque usa la clave API del comercio.

Antes de empezar

• La clave API del comercio, guardada en una variable de entorno del servidor.
• La URL del servidor de FINORA de tu ambiente (<URL_DEL_MERCHANT> en los ejemplos).
• La referencia de tu pedido: es lo que te permite reconocerlo cuando llegue el aviso.

1. Arma el cuerpo de la petición. Solo monto es obligatorio, pero en la práctica siempre envías también referencia, returnUrl y webhookUrl:

   {
     "monto": 227.00,
     "moneda": "VES",
     "referencia": "PED-1042",
     "descripcion": "Pan campesino y café",
     "items": [{ "nombre": "Pan campesino", "cantidad": 2, "precio": 113.50 }],
     "returnUrl": "https://mitienda.example/gracias",
     "webhookUrl": "https://mitienda.example/webhooks/finora",
     "ttlSegundos": 900,
     "sandbox": true
   }

   El monto va en unidades con dos decimales (227.00), no en céntimos.

2. Si vas a ofrecer tarjeta, agrega el terminalId del terminal físico que cobrará. Sin terminal, la tarjeta aparece atenuada con su motivo y el cliente puede pagar con los demás medios.

   { "monto": 227.00, "referencia": "PED-1042", "terminalId": "TIENDA01" }

3. Si ya conoces al cliente, precarga sus datos en pagador para que no los escriba otra vez:

   { "pagador": { "tipoDocumento": "V", "documento": "00000001", "nombre": "Ana Ejemplo", "telefono": "04140000001" } }

4. Envía la petición con tu clave:

   curl -s -X POST "<URL_DEL_MERCHANT>/api/v1/checkout/sesiones" \
     -H "X-API-Key: <TU_CLAVE_API>" \
     -H "Content-Type: application/json" \
     -d @sesion.json

5. Guarda el sesionId de la respuesta junto a tu pedido.

6. Devuelve al navegador solo el sesionId y el token, o la urlPago. Nunca la respuesta completa reenviada sin filtrar, y nunca la clave.

Si algo sale mal

Respuesta	Qué significa	Qué hacer
401 CLAVE_INVALIDA	La clave falta, es incorrecta o fue revocada	Revisa la variable de entorno; si la revocaron, pide una nueva
403 CLAVE_SIN_ACCESO_AL_COMERCIO	La clave no es de ese comercio	Usa la clave del comercio correcto
403 TERMINAL_AJENO	El terminal no pertenece a tu comercio	Revisa el terminalId
404 TERMINAL_NO_ENCONTRADO	Ese terminal no existe	Revisa el terminalId en el Portal del comercio
400 PETICION_INVALIDA	Monto cero o negativo, moneda que no es ISO, tiempo de vida fuera de 60 a 3600 segundos, URL que no es http(s)	Corrige el campo que dice el detail

La lista completa está en Códigos de error y de resultado.

Siguiente

Incrusta el checkout en tu página.