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

---

Consultar e reenviar notificações

Os endpoints de gerenciamento de webhook exigem um token Bearer válido. A consulta e o reenvio consideram somente os registros vinculados à conta autenticada.

Headers

Authorization: Bearer SEU_TOKEN
Content-Type: application/json

Consultar webhook

Utilize esta operação para consultar o link de pagamento e o último status HTTP registrado para uma notificação.

GET /api/webhook?paymentResultId=ID_DO_RESULTADO

Parâmetro

PROPRIEDADE	DESCRIÇÃO	TIPO	LOCAL	OBRIGATÓRIO	TAMANHO MÁXIMO
paymentResultId	Identificador do resultado do pagamento.	string	query	sim	100

Exemplo de requisição

curl --request GET \
  --url '<URL_API_GATEWAY>/api/webhook?paymentResultId=db7fa758-f2e2-47e6-b764-9c1e149cc7fa' \
  --header 'Authorization: Bearer SEU_TOKEN'

🟢 200

Webhook localizado

{
  "paymentLinkId": "3c228652-122e-4da6-b572-4aea64caad63",
  "paymentResultId": "db7fa758-f2e2-47e6-b764-9c1e149cc7fa",
  "httpStatusCode": "200"
}

Quando o callback é processado com sucesso, httpStatusCode será "200". Outros valores, como "400" ou "500", representam o status retornado pelo endpoint de callback na última tentativa. Quando ainda não houve tentativa de notificação, o campo será uma string vazia. Se nenhum registro da conta autenticada for localizado, todos os campos serão retornados como strings vazias.

🔴 400

Ocorre quando paymentResultId não é informado ou ultrapassa o tamanho máximo permitido.

🔴 500

Erro interno

[
  {
    "tag": "",
    "description": "Não foi possível executar comando. Erro desconhecido."
  }
]

Campos do retorno

PROPRIEDADE	DESCRIÇÃO	TIPO
paymentLinkId	Identificador do link de pagamento. Será vazio quando não houver vínculo com um link.	string
paymentResultId	Identificador do resultado do pagamento localizado.	string
httpStatusCode	Último status HTTP retornado pelo endpoint de callback. Será vazio quando ainda não houver resposta.	string

Reenviar webhook

Utilize esta operação para solicitar uma nova tentativa de entrega de um webhook que ainda não foi processado com sucesso. A solicitação é adicionada a uma fila e processada de forma assíncrona.

POST /api/webhook/resend

Corpo da requisição

{
  "paymentResultId": "db7fa758-f2e2-47e6-b764-9c1e149cc7fa"
}

Parâmetro

PROPRIEDADE	DESCRIÇÃO	TIPO	LOCAL	OBRIGATÓRIO	TAMANHO MÁXIMO
paymentResultId	Identificador do resultado do pagamento cujo webhook será reenviado.	string	body	sim	50

Exemplo de requisição

curl --request POST \
  --url '<URL_API_GATEWAY>/api/webhook/resend' \
  --header 'Authorization: Bearer SEU_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{"paymentResultId":"db7fa758-f2e2-47e6-b764-9c1e149cc7fa"}'

🟢 202

Reenvio enfileirado

{
  "paymentLinkId": "3c228652-122e-4da6-b572-4aea64caad63",
  "paymentResultId": "db7fa758-f2e2-47e6-b764-9c1e149cc7fa",
  "status": "queued"
}

O status queued confirma que a solicitação foi aceita para processamento assíncrono; ele não representa o resultado da nova tentativa. Consulte novamente o webhook para verificar o httpStatusCode atualizado.

🔴 400

Webhook não localizado

[
  {
    "tag": "",
    "description": "Webhook não encontrado."
  }
]

🔴 409

Ocorre quando o webhook não possui uma URL de callback ou quando já foi processado com status HTTP 200.

Webhook já processado

[
  {
    "tag": "",
    "description": "O webhook já foi processado com sucesso."
  }
]

🔴 500

Erro interno

[
  {
    "tag": "",
    "description": "Não foi possível executar comando. Erro desconhecido."
  }
]

---

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 →