whatsapp.payment.updated

Use whatsapp.payment.updated para processar este evento em seu endpoint de webhook.

Gatilhos

Ocorre quando uma transação de pagamento do WhatsApp é alterada. Inscreva-se em whatsapp.payment.updated ao configurar seu endpoint de webhook.

Sintaxe

A YCloud envia uma solicitação HTTP POST para a URL de webhook configurada. O formato a seguir mostra uma variante do payload. Os valores entre colchetes angulares são marcadores de posição; seus tipos estão listados em Parâmetros. Campos opcionais e outras variantes são descritos abaixo.

{
  "id": "<ID>",
  "type": "whatsapp.payment.updated",
  "apiVersion": "<API_VERSION>",
  "createTime": "<CREATE_TIME>",
  "whatsappPayment": {
    "wabaId": "<WABA_ID>",
    "referenceId": "<REFERENCE_ID>",
    "status": "<STATUS>",
    "transactions": [
      {
        "id": "<ID>",
        "type": "<TYPE>",
        "status": "<STATUS>",
        "createdTimestamp": "<CREATED_TIMESTAMP_VALUE>",
        "updatedTimestamp": "<UPDATED_TIMESTAMP_VALUE>",
        "amount": {
          "value": "<VALUE_VALUE>",
          "offset": "<OFFSET_VALUE>"
        },
        "currency": "<CURRENCY>",
        "methodType": "<METHOD_TYPE>",
        "error": {
          "code": "<CODE>",
          "reason": "<REASON>"
        }
      }
    ]
  }
}

Parâmetros

Valide o cabeçalho HTTP YCloud-Signature antes de processar o corpo JSON. Consulte validação de assinatura.

Envelope do evento

Parâmetro	Tipo	Obrigatório	Descrição
`id`	string	Sim	ID exclusivo do evento. Tamanho mínimo: `6`. Tamanho máximo: `128`.
`type`	string	Sim	Sempre `whatsapp.payment.updated`.
`apiVersion`	string	Sim	A versão da API usada para renderizar este evento.
`createTime`	string (date-time)	Sim	A hora em que este evento foi criado, formatada em RFC 3339. Ex.: `2022-06-01T12:00:00.000Z`.

Payload do evento

Parâmetro	Tipo	Obrigatório	Descrição
`whatsappPayment`	object	Não	Payload específico do evento `whatsappPayment`.

Os quatro campos comuns do envelope são obrigatórios. Os campos do payload dependem da variante do evento. Em cada tabela de objeto, Obrigatório se aplica quando o objeto pai estiver presente. Campos opcionais podem ser omitidos; um exemplo não torna um campo obrigatório.

whatsappPayment

Parâmetro	Tipo	Obrigatório	Descrição
`wabaId`	string	Sim	ID da conta do WhatsApp Business.
`referenceId`	string	Sim	Identificador exclusivo do pagamento fornecido pela empresa. Diferencia maiúsculas de minúsculas, não pode ser uma string vazia, pode conter apenas letras em inglês, números, sublinhados, traços ou pontos, e não deve exceder 35 caracteres.
`status`	string	Sim	Status deste pagamento. `captured`: Indica que o pagamento foi concluído com sucesso. `pending`: Indica que o usuário tentou, mas ainda não recebeu o sinal de transação bem-sucedida.
`transactions`	object[]	Não	Contém a tentativa de transação mais recente para este pagamento.

whatsappPayment.transactions[]

Parâmetro	Tipo	Obrigatório	Descrição
`id`	string	Sim	ID da transação.
`type`	string	Sim	O tipo de pagamento para estas transações. Um dos seguintes: `billdesk`, `razorpay`, `payu` ou `zaakpay`.
`status`	string	Sim	O status da transação. Um dos seguintes: `pending`, `success` ou `failed`.
`createdTimestamp`	integer (int64)	Sim	Hora em que a transação foi criada em milissegundos da época unix.
`updatedTimestamp`	integer (int64)	Sim	Hora em que a transação foi atualizada pela última vez em milissegundos da época unix.
`amount`	object	Sim	Valor total que o usuário pagou.
`currency`	string	Sim	A moeda deste pagamento. Atualmente, o único valor suportado é `INR`.
`methodType`	string	Não	Descreve o tipo de método de pagamento usado pelo consumidor para pagar pelo pedido. Pode ser um dos seguintes: `upi`, `card`, `wallet` ou `netbanking`. As informações do método de pagamento podem não estar disponíveis para pagamentos com falha.
`error`	object	Não	Os detalhes do erro de pagamento podem não estar disponíveis para todas as tentativas de pagamento.

whatsappPayment.transactions[].amount

Parâmetro	Tipo	Obrigatório	Descrição
`offset`	integer (int32)	Sim	Deve ser `100` para `INR`.
`value`	integer (int32)	Sim	Número inteiro positivo que representa o valor do montante multiplicado pelo deslocamento (offset). Por exemplo, ₹12,34 tem o valor 1234.
`description`	string	Não	Use apenas para `tax`, `shipping` ou `discount`. Descrição do valor. O limite máximo é de 60 caracteres. Comprimento máximo: `60`.
`discount_program_name`	string	Não	Use apenas para `discount`. Texto usado para definir pedidos com incentivo. Se o pedido tiver incentivo, o comerciante precisará definir essas informações. O limite máximo é de 60 caracteres. Comprimento máximo: `60`.

whatsappPayment.transactions[].error

Parâmetro	Tipo	Obrigatório	Descrição
`code`	string	Sim	Descreve o motivo da falha no pagamento gerado pelo gateway de pagamento, e a Meta transmite isso aos parceiros.
`reason`	string	Sim	Descreve em texto sem formatação o motivo da falha no pagamento gerado pelo gateway de pagamento, e a Meta transmite isso aos parceiros.

Exemplo

O seguinte JSON é o corpo entregue ao seu receptor. IDs, números de telefone e outros valores de conta são ilustrativos.

{
  "id": "evt_eEkn26qar3nOB8md",
  "type": "whatsapp.payment.updated",
  "apiVersion": "v2",
  "createTime": "2024-10-10T07:08:00.000Z",
  "whatsappPayment": {
    "wabaId": "WABA-ID",
    "referenceId": "<reference-id>",
    "status": "captured",
    "transactions": [
      {
        "id": "<transaction-id>",
        "type": "razorpay",
        "status": "success",
        "createdTimestamp": 1728544066000,
        "updatedTimestamp": 1728544066000,
        "amount": {
          "value": 21000,
          "offset": 100
        },
        "currency": "INR",
        "methodType": "upi | card | wallet | netbanking",
        "error": {
          "code": "error-code",
          "reason": "error-reason"
        }
      }
    ]
  }
}

Depois de verificar a assinatura e aceitar o evento de forma duradoura, retorne uma resposta 2xx. Processe tarefas lentas de forma assíncrona.

HTTP/1.1 200 OK

Para conferir orientações passo a passo sobre cenários, consulte os exemplos anotados.

Primeiros passos

Guias

Endpoints

Webhook reference

whatsapp.payment.updated

Gatilhos

Sintaxe

Parâmetros

Envelope do evento

Payload do evento

whatsappPayment

Exemplo

​Gatilhos

​Sintaxe

​Parâmetros

​Envelope do evento

​Payload do evento

​whatsappPayment

​Exemplo

Gatilhos

Sintaxe

Parâmetros

Envelope do evento

Payload do evento

whatsappPayment

Exemplo