Contrato de integração Checkout API × Onion

TLDR: o Checkout API faz POST /checkout_notifications no Onion sempre que o status de um pagamento muda; o campo status (enabled/disabled) diz ao Onion se ele deve liberar ou bloquear o acesso do cliente.

Visão geral

O Onion é uma das plataformas LMS integradas ao checkout. A integração é unidirecional: o Checkout API notifica, o Onion reage. Todos os eventos vão para o mesmo endpoint — o que muda é o campo status do payload.

Este documento é o contrato que o time do Onion implementa. O mecanismo genérico que dispara estas chamadas está em payment_integration_flow.md.

Fluxo

mermaid graph TD A["Cliente realiza pagamento no checkout"] --> B["Checkout API cria pagamento local<br/>status: draft"] B --> C["Checkout API envia ao gateway Asaas<br/>status: pending"] C --> D["Asaas processa e confirma via webhook"] D --> E["Checkout API atualiza status interno<br/>paid · overdue · refunded"] E --> F["POST /checkout_notifications no Onion"] F --> G["Onion libera ou bloqueia o acesso"] style F fill:#1f2937,color:#fff

Contratos

Endpoint e autenticação

POST /checkout_notifications Content-Type: application/json Authorization: Bearer {token}

O Onion deve validar o token antes de processar o payload.

Payload

json { "status": "enabled", "email": "cliente@email.com", "name": "Nome do Cliente", "doc_number": "12345678900", "phone_number": "11999999999", "token": "token_de_verificacao", "transaction": "ref_pagamento_abc123", "expires_at": "2026-12-31 23:59:59" }

Campo Tipo Descrição
status string "enabled" libera o acesso, "disabled" bloqueia
email string Email do cliente — identificador principal
name string Nome completo do cliente
doc_number string CPF ou CNPJ do cliente
phone_number string Telefone do cliente
token string Token de verificação da requisição
transaction string Referência única do pagamento no checkout
expires_at string Expiração do acesso, no formato YYYY-MM-DD HH:MM:SS

Eventos e ações esperadas

Evento no Checkout status enviado Ação esperada do Onion
Pagamento confirmado "enabled" Criar ou ativar o usuário e liberar o acesso ao app
Pagamento vencido (overdue) "disabled" Bloquear o acesso do cliente ao app
Pagamento reembolsado (refunded) "disabled" Bloquear o acesso do cliente ao app

Pagamento confirmado (enabled)

  • Cliente não existe no Onion → criar a conta com os dados do payload e liberar o acesso.
  • Cliente já existe → apenas liberar o acesso.
  • Respeitar expires_at como data limite do acesso.

Pagamento vencido (disabled)

  • Bloquear o acesso do cliente ao app.
  • O Checkout API faz retry automático em 5 dias, caso o cliente regularize.

Pagamento reembolsado (disabled)

  • Bloquear o acesso imediatamente. Sem retry — a ação é definitiva.

Resposta esperada

Código Significado
200 OK Processado com sucesso
4xx Erro de validação — registrado no checkout como falha
5xx Erro interno — registrado no checkout como falha

O Checkout API registra todas as chamadas e respostas em WebhookLog para auditoria.

Exemplo completo

```http POST https://api.onion.com/checkout_notifications HTTP/1.1 Content-Type: application/json Authorization: Bearer token_fornecido_pelo_onion

{ “status”: “enabled”, “email”: “joao@email.com”, “name”: “João Silva”, “doc_number”: “12345678900”, “phone_number”: “11999999999”, “token”: “abc123token”, “transaction”: “PAY_REF_001”, “expires_at”: “2027-03-18 23:59:59” } ```

http HTTP/1.1 200 OK

Retry automático

  • Quando o pagamento fica overdue, o Checkout API agenda um re-sync em 5 dias.
  • O job PlatformRunIntegrationSyncJob reenvia o webhook com execute_now = true.
  • Se o pagamento continua overdue após o retry, o acesso é removido definitivamente.
  • Pagamentos refunded não têm retry — a remoção é imediata.

Repagamento

Quando o cliente faz um repagamento (quitação de dívida anterior):

  • O campo transaction carrega a referência do pagamento original.
  • O expires_at é recalculado a partir da data do primeiro pagamento da parcela original.
  • O Onion deve reativar o acesso do cliente com base em email + transaction.

Dados necessários para configuração

O time do Onion precisa fornecer ao time do Checkout:

Dado Exemplo Para quê
URL base da API https://api.onion.com/ Destino dos webhooks
Token de autenticação Bearer xxx Enviado no header Authorization

Ambos ficam em Rails.application.credentials.dig(:onion, :api_url) e (:onion, :api_key).

Referências