Link de recibo de pagamento via botão de URL

Este guia mostra o padrão de recibo Opção A: o corpo do template de WhatsApp contém os detalhes do recibo e um botão de URL dinâmico abre a página de recibo hospedada. Use esse padrão quando seu sistema externo já hospeda páginas de recibo e você quer uma mensagem Utility pequena e esperada no WhatsApp.

Antes de começar

Você precisa de:

Um canal de WhatsApp conectado no Switchbord.
Uma chave de API do Switchbord para o workspace, caso chame POST /api/v1/template-sends diretamente.
Um template Utility aprovado com um botão de URL, por exemplo payment_receipt_link.
Uma página de recibo pública em HTTPS, como https://pay.example.com/receipts/R-1001.

Não use este fluxo para mensagens promocionais. Templates Utility devem estar vinculados a eventos esperados pelo cliente, como pagamento, parcela, reserva, reembolso ou disponibilidade de documento.

Estrutura do template

Um template típico de link de recibo contém variáveis no corpo e um botão de URL:

Ciao {{1}}, abbiamo ricevuto il pagamento {{2}} per la ricevuta {{3}}.

Button URL: https://pay.example.com/receipts/{{1}}

A variável do botão é o sufixo dinâmico. Se a URL base for https://pay.example.com/receipts/, envie apenas R-1001 como a variável.

Envio direto via API

curl -X POST https://api.switchbord.ai/api/v1/template-sends \
  -H "Authorization: Bearer $SWITCHBORD_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: payment-receipt-R-1001" \
  -d '{
    "templateName": "payment_receipt_link",
    "templateLocale": "it",
    "recipient": {
      "phoneE164": "+393331234567",
      "externalId": "traveller-123",
      "name": "Giulia Rossi"
    },
    "variables": {
      "body": {
        "1": "Giulia",
        "2": "€ 240,00",
        "3": "R-1001"
      },
      "buttons": {
        "url": [
          { "index": 0, "suffix": "R-1001" }
        ]
      }
    },
    "metadata": {
      "source": "booking-system",
      "eventType": "payment.receipt.created"
    }
  }'

Resposta esperada:

{
  "data": {
    "contactId": "contact_123",
    "conversationId": "conversation_123",
    "messageId": "message_123",
    "clientMessageId": "payment-receipt-R-1001",
    "status": "queued",
    "reused": false,
    "idempotent": true
  }
}

Construtor de webhook de entrada

Se o sistema externo puder chamar um webhook, mas não puder armazenar uma chave de API do Switchbord, configure um webhook de entrada do workspace em vez disso:

Abra Settings → Integrations → Webhooks & API.
Crie um novo webhook de entrada.
Selecione o template Utility aprovado payment_receipt_link.
Mapeie os campos obrigatórios:

Campo do template	Modo de origem	Exemplo de origem
Telefone do destinatário	Caminho no payload	`customer.phone`
ID externo	Caminho no payload	`receipt.id`
Corpo `{{1}}`	Caminho no payload	`customer.first_name`
Corpo `{{2}}`	Caminho no payload	`receipt.amount`
Corpo `{{3}}`	Caminho no payload	`receipt.number`
Variável do botão de URL	Caminho no payload	`receipt.number`

Cole um payload de exemplo e execute o preview de dry-run.
Crie o webhook. O endpoint permanece desabilitado/dry-run até que um futuro fluxo de promoção verificado por run-log habilite a execução real.

Payload de exemplo:

{
  "customer": {
    "phone": "+393331234567",
    "first_name": "Giulia"
  },
  "receipt": {
    "id": "payment-receipt-R-1001",
    "number": "R-1001",
    "amount": "€ 240,00",
    "link": "https://pay.example.com/receipts/R-1001"
  }
}

Assinando requisições de webhook de entrada

As requisições de webhook usam assinaturas HMAC com timestamp. O segredo é exibido apenas uma vez, quando o webhook é criado.

import { createHash, createHmac } from "node:crypto";

const rawBody = JSON.stringify(payload);
const timestamp = Math.floor(Date.now() / 1000);
const secretHash = createHash("sha256").update(webhookSecret).digest("hex");
const digest = createHmac("sha256", secretHash)
  .update(`${timestamp}.${rawBody}`)
  .digest("hex");

await fetch(webhookUrl, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-Switchbord-Signature": `t=${timestamp},v1=${digest}`,
    "Idempotency-Key": payload.receipt.id
  },
  body: rawBody
});

Nunca envie o segredo bruto do webhook como um cabeçalho, parâmetro de query ou campo JSON.

Checklist de lançamento

Execute o preview de dry-run no navegador e verifique a requisição mapeada.
Não espere ainda run logs de endpoint assinado para configs criadas em Settings; eles permanecem desabilitados até que a promoção real seja lançada.
Confirme que o template é Utility aprovado no mesmo workspace.
Use chaves de idempotência estáveis a partir do id do evento de origem.
Mantenha as URLs de recibo somente em HTTPS e evite embutir tokens privados de longa duração.

Solução de problemas

Sintoma	Verificação
`404 webhook_not_found_or_disabled`	Configs criadas em Settings estão desabilitadas hoje; use o preview no navegador ou a API direta até que a promoção seja lançada.
Futuro `401 missing_timestamp`	`X-Switchbord-Signature` deve incluir `t=<segundos unix>`.
Futuro `401 expired_timestamp`	O relógio do remetente difere em mais de cinco minutos.
Futuro `401 invalid_signature`	Assine o corpo bruto exato da requisição, não uma cópia reserializada.
`400 template_not_approved_utility`	Selecione um template Utility aprovado no mesmo workspace.
`400 missing_button_url_variable`	Mapeie o sufixo do botão de URL e garanta que ele resolva para uma string não vazia.
Envios duplicados	Use uma `Idempotency-Key` estável para cada evento de recibo.

Primeiros passos

Funcionalidades

WhatsApp

Guias

Contribuindo

Plataforma

Operações

Segurança e Conformidade

Link de recibo de pagamento via botão de URL

Antes de começar

Estrutura do template

Envio direto via API

Construtor de webhook de entrada

Assinando requisições de webhook de entrada

Checklist de lançamento

Solução de problemas

​Antes de começar

​Estrutura do template

​Envio direto via API

​Construtor de webhook de entrada

​Assinando requisições de webhook de entrada

​Checklist de lançamento

​Solução de problemas

Antes de começar

Estrutura do template

Envio direto via API

Construtor de webhook de entrada

Assinando requisições de webhook de entrada

Checklist de lançamento

Solução de problemas