# Checkout de pago

> Cómo cobrar un servicio en un checkout del sistema de la central e informar a Cortecloud la confirmación, la cancelación o el reembolso del pago.

URL canónica: https://apis.cortecloud.com.br/docs/es/guias/checkout/

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 {#cadastro-do-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](https://apis.cortecloud.com.br/docs/es/comecando/conceitos.md#codigo-da-central) a suporte@serrabits.com.br. Sin ese registro, la opción de pago en línea no aparece para el carpintero.

## Flujo {#fluxo}

![Flujo del pago en línea entre el usuario, Cortecloud y el sistema de la central](https://apis.cortecloud.com.br/docs/es/img/guias/flow-checkout.png)

1. **El carpintero elige pagar en línea** en un servicio en presupuesto generado (`4`; ver [estado del servicio](https://apis.cortecloud.com.br/docs/es/comecando/conceitos.md#status-do-servico)).
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:

   ```json
   { "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}`](https://apis.cortecloud.com.br/docs/swagger#/Services/getService). 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`](https://apis.cortecloud.com.br/docs/swagger#/Payment/saveCheckoutUrl):

   ```json
   { "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`](https://apis.cortecloud.com.br/docs/swagger#/Payment/finishCheckout) con el `paymentId`, el identificador del pago en su sistema. El servicio pasa a aprobado (`6`).

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

   - el pago falló o fue abandonado: [`POST /payment/cancel-checkout`](https://apis.cortecloud.com.br/docs/swagger#/Payment/cancelCheckout). El servicio vuelve a presupuesto generado (`4`) y la URL de checkout registrada se borra; el carpintero puede intentarlo de nuevo.

     ```json
     { "serviceId": 123 }
     ```

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

## Reembolso {#estorno}

Si un pago ya confirmado debe revertirse, llame a [`POST /payment/return-service`](https://apis.cortecloud.com.br/docs/swagger#/Payment/returnService) 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.

```json
{ "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 {#status-exigidos}

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 |