Webhook - Notificações de Pagamento

Dados da API

API Gateway
Esta API é utilizada para operações do gateway de pagamento:

• Produção: https://api.sopague.com.br/gateway
• Homologação: https://api-hmg.sopague.com.br/gateway
• Arquitetura: Representational State Transfer (REST)

Como Funciona

Quando um pagamento é processado (Gateway 2D, Gateway 3D ou Link de Pagamento), nossa plataforma pode enviar (opcional) automaticamente uma notificação HTTP POST para sua URL de callback configurada.

Configuração

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

Requisição com Webhook

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

Corpo da notificação

Webhook enviará uma notificação com os seguintes campos para sua url de callback configurada

Gateway 2D/3D

Webhook - Gateway

{
  "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

Webhook - Link

{
  "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"
}

Headers HTTP

As requisições do webhook são enviadas com um header de nome 'Access-Key', essa chave de acesso é o que garante a autenticidade da requisição. Solicite ao suporte a sua 'Access-Key' para configurar na sua aplicação.

Content-Type: application/json
Access-Key: callback-id-123

Seu Endpoint

Seu endpoint deve:

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

Campos do Payload

Campo	Descrição	Tipo
Value	Valor do pagamento	decimal
Origin	Origem do pagamento	string
Date	Data do pagamento	string
ResultId	ID do resultado	string
Status	Status da transação	string
PaymentLinkId	ID do link (apenas para links)	string

Domínios

PROPRIEDADE	CONTEÚDO
Origin	GATEWAY_2D, GATEWAY_3D, PAYMENT_LINK_2D

---

Consulte também

Códigos de Resposta

Para interpretar corretamente os status das transações recebidas via webhook, consulte nossa tabela completa de códigos de resposta:

Códigos de Resposta do Host →