Checkout de pago

En el pago en línea, el carpintero paga un servicio en un checkout del sistema de la central, y el servicio solo queda aprobado cuando su sistema confirma el pago a Cortecloud.

Su sistema participa en tres momentos:

1. recibe de Cortecloud el aviso de que el carpintero eligió pagar en línea;
2. genera el checkout y registra su URL en Cortecloud, que redirige al carpintero a ella;
3. informa a Cortecloud si el pago fue confirmado o cancelado.

Registro del endpoint de checkout

Para recibir el aviso del primer momento, su sistema necesita un endpoint registrado en Cortecloud para la central. El registro lo hace soporte: envíe la URL del endpoint y el código de la central a suporte@serrabits.com.br. Sin ese registro, la opción de pago en línea no aparece para el carpintero.

Flujo

1. El carpintero elige pagar en línea en un servicio en presupuesto generado (4; ver estado del servicio).

2. Cortecloud avisa a su sistema. El servicio pasa a esperando pago en línea (25) y Cortecloud hace un POST al endpoint registrado con el id del servicio:

   { "serviceId": 123 }

   Si su endpoint responde con error, el servicio vuelve a presupuesto generado (4) y el carpintero no es redirigido. Este aviso no lleva credenciales: cualquiera que conozca la URL del endpoint puede llamarlo. Por eso, el paso 3 confirma el servicio mediante la API antes de generar el cobro.

3. Su sistema consulta el servicio con GET /services/{id}. Verifique que status.code sea 25 y use los valores del servicio (materiales, mano de obra y flete) para armar el cobro.

4. Su sistema registra la URL del checkout con POST /payment/checkout-url:

   { "serviceId": 123, "url": "https://checkout.example.com/pedido/abc" }

   Cortecloud redirige al carpintero a esa URL.

5. El carpintero paga en el checkout.

6. Su sistema informa el resultado:

   • pago confirmado: POST /payment/finish-checkout con el paymentId, el identificador del pago en su sistema. El servicio pasa a aprobado (6).

     { "serviceId": 123, "paymentId": "pay_789" }

   • el pago falló o fue abandonado: POST /payment/cancel-checkout. El servicio vuelve a presupuesto generado (4) y la URL de checkout registrada se borra; el carpintero puede intentarlo de nuevo.

     { "serviceId": 123 }

Mientras su sistema no informe el resultado, el servicio queda en esperando pago en línea (25).

Reembolso

Si un pago ya confirmado debe revertirse, llame a POST /payment/return-service con el mismo paymentId enviado en la confirmación. El servicio vuelve de aprobado (6) a presupuesto generado (4), y el pago y la URL de checkout registrados se borran. Guarde el paymentId de cada confirmación para poder hacerlo.

{ "serviceId": 123, "paymentId": "pay_789" }

La ruta solo actualiza el servicio en Cortecloud. La devolución del dinero al carpintero se hace en su sistema de pago.

Estados requeridos

Cada ruta de pago solo acepta el servicio en un estado y responde 409 fuera de él:

Ruta	Estado requerido
POST /payment/checkout-url	Esperando pago en línea (25)
POST /payment/finish-checkout	Esperando pago en línea (25)
POST /payment/cancel-checkout	Esperando pago en línea (25)
POST /payment/return-service	Aprobado (6), con el mismo paymentId de la confirmación