# Checkout de pagamento

> Como cobrar um serviço num checkout do sistema da central e informar ao Cortecloud a confirmação, o cancelamento ou o estorno do pagamento.

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

No pagamento online, o marceneiro paga um serviço num checkout do sistema da central, e o serviço só fica aprovado quando o seu sistema confirma o pagamento ao Cortecloud.

O seu sistema participa em três momentos:

1. recebe do Cortecloud o aviso de que o marceneiro escolheu pagar online;
2. gera o checkout e registra a URL dele no Cortecloud, que redireciona o marceneiro para ela;
3. informa ao Cortecloud se o pagamento foi confirmado ou cancelado.

## Cadastro do endpoint de checkout {#cadastro-do-endpoint-de-checkout}

Para receber o aviso do primeiro momento, o seu sistema precisa de um endpoint cadastrado no Cortecloud para a central. O cadastro é feito pelo suporte: envie a URL do endpoint e o [código da central](https://apis.cortecloud.com.br/docs/comecando/conceitos.md#codigo-da-central) para suporte@serrabits.com.br. Sem esse cadastro, a opção de pagamento online não aparece para o marceneiro.

## Fluxo {#fluxo}

![Fluxo do pagamento online entre o usuário, o Cortecloud e o sistema da central](https://apis.cortecloud.com.br/docs/img/guias/flow-checkout.png)

1. **O marceneiro escolhe pagar online** num serviço em orçamento gerado (`4`; ver [status do serviço](https://apis.cortecloud.com.br/docs/comecando/conceitos.md#status-do-servico)).
2. **O Cortecloud avisa o seu sistema.** O serviço passa para aguardando pagamento online (`25`) e o Cortecloud faz um `POST` no endpoint cadastrado com o id do serviço:

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

   Se o seu endpoint responder com erro, o serviço volta para orçamento gerado (`4`) e o marceneiro não é redirecionado. Esse aviso não leva credenciais: qualquer um que conheça a URL do endpoint pode chamá-lo. Por isso, o passo 3 confirma o serviço pela API antes de gerar a cobrança.
3. **O seu sistema consulta o serviço** por [`GET /services/{id}`](https://apis.cortecloud.com.br/docs/swagger#/Services/getService). Confira que `status.code` é `25` e use os valores do serviço (materiais, mão de obra e frete) para montar a cobrança.
4. **O seu sistema registra a URL do checkout** por [`POST /payment/checkout-url`](https://apis.cortecloud.com.br/docs/swagger#/Payment/saveCheckoutUrl):

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

   O Cortecloud redireciona o marceneiro para essa URL.
5. **O marceneiro paga no checkout.**
6. **O seu sistema informa o resultado:**
   - pagamento confirmado: [`POST /payment/finish-checkout`](https://apis.cortecloud.com.br/docs/swagger#/Payment/finishCheckout) com o `paymentId`, o identificador do pagamento no seu sistema. O serviço passa para aprovado (`6`).

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

   - pagamento falhou ou foi abandonado: [`POST /payment/cancel-checkout`](https://apis.cortecloud.com.br/docs/swagger#/Payment/cancelCheckout). O serviço volta para orçamento gerado (`4`) e a URL de checkout registrada é apagada; o marceneiro pode tentar de novo.

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

Enquanto o seu sistema não informa o resultado, o serviço fica em aguardando pagamento online (`25`).

## Estorno {#estorno}

Se um pagamento já confirmado precisar ser revertido, chame [`POST /payment/return-service`](https://apis.cortecloud.com.br/docs/swagger#/Payment/returnService) com o mesmo `paymentId` enviado na confirmação. O serviço volta de aprovado (`6`) para orçamento gerado (`4`), e o pagamento e a URL de checkout registrados são apagados. Guarde o `paymentId` de cada confirmação para poder fazer isso.

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

A rota só atualiza o serviço no Cortecloud. A devolução do valor ao marceneiro é feita no seu sistema de pagamento.

## Status exigidos {#status-exigidos}

Cada rota de pagamento só aceita o serviço num status e responde `409` fora dele:

| Rota | Status exigido |
| --- | --- |
| `POST /payment/checkout-url` | Aguardando pagamento online (`25`) |
| `POST /payment/finish-checkout` | Aguardando pagamento online (`25`) |
| `POST /payment/cancel-checkout` | Aguardando pagamento online (`25`) |
| `POST /payment/return-service` | Aprovado (`6`), com o mesmo `paymentId` da confirmação |