SopagueDocs
v3

Quando um pagamento é processado (Gateway 2D, Gateway 3D ou Link de Pagamento), a plataforma envia automaticamente uma notificação HTTP POST para a URL de callback configurada no campo urlCallBack da requisição de pagamento.

Configuração

Inclua o parâmetro urlCallBack na requisição de pagamento:

{
  "urlCallBack": "https://seusite.com.br/webhook/pagamento"
}

Corpo da Notificação

Gateway 2D/3D

{
  "Value": 100.50,
  "Origin": "GATEWAY_2D",
  "Date": "2025-09-11T14:30:25Z",
  "Installments": 1,
  "TransactionType": "CREDIT",
  "ResultId": "010078826509090055210005100989250000000000",
  "AuthorizationCode": "2345",
  "Status": "0",
  "PaymentLinkId": null
}

Link de Pagamento

{
  "Value": 50.00,
  "Origin": "PAYMENT_LINK_2D",
  "Date": "2025-09-11T14:30:25Z",
  "Installments": 1,
  "TransactionType": "CREDIT",
  "ResultId": "010078826509090055210005100989250000000000",
  "AuthorizationCode": "2345",
  "Status": "0",
  "PaymentLinkId": "3c228652-122e-4da6-b572-4aea64caad63"
}

Campos do Payload

Headers HTTP

As requisições do webhook são enviadas com o header Access-Key, que garante a autenticidade da requisição. Caso queira consultar seu Access Key, acesse a página Autenticação.

Content-Type: application/json
Access-Key: 4361bc4e-279d-4775-b0f0-6f2520f5ef5b

Validação da Access-Key — sensibilidade a maiúsculas e minúsculas

A Access-Key pode ser transmitida com caracteres alfabéticos em maiúsculas ou minúsculas. Quando a chave possuir formato UUID/GUID, as duas representações abaixo referem-se ao mesmo identificador:

1f84a6c3-b027-4d9e-8a51-c6e2b7f0d134
1F84A6C3-B027-4D9E-8A51-C6E2B7F0D134

Portanto, não realize uma comparação textual case-sensitive. Adote uma das abordagens abaixo ao validar a chave recebida no header:

  • Preferencialmente: converta o valor para o tipo UUID/GUID da linguagem utilizada e compare a partir desse tipo.
  • Alternativamente: normalize os dois valores (ex.: ambos para letras minúsculas) antes de compará-los como string, ou utilize uma comparação case-insensitive.

Não assuma que a representação textual recebida terá obrigatoriamente o mesmo casing utilizado no momento da configuração.

Requisitos do Endpoint de Destino

  • Aceitar requisições POST
  • Retornar status HTTP 200 para notificações recebidas com sucesso

Para interpretar corretamente os status das transações recebidas via webhook, consulte a tabela de Códigos de Resposta.