Webhook — Payment Notifications

API data

API Gateway
This API is used for payment gateway operations:

• Production: https://api.sopague.com.br/gateway
• Sandbox: https://api-hmg.sopague.com.br/gateway
• Architecture: Representational State Transfer (REST)

How it works

When a payment is processed (2D Gateway, 3D Gateway, or Payment Link), our platform can (optionally) automatically send an HTTP POST notification to your configured callback URL.

Configuration

Include the urlCallBack parameter in your request:

Request with Webhook

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

Notification body

The webhook sends a notification with the following fields to your configured callback URL.

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
}

Payment Link

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

HTTP headers

Webhook requests are sent with a header named Access-Key. This access key ensures the authenticity of the request.

Ask support for your Access-Key so you can configure it in your application.

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

Your endpoint

Your endpoint must:

• Accept POST requests
• Return HTTP status 200 (for notifications received successfully)

Payload fields

Field	Description	Type
Value	Payment amount	decimal
Origin	Payment origin	string
Date	Payment date	string
ResultId	Result ID	string
Status	Transaction status	string
PaymentLinkId	Link ID (only for payment links)	string

Domains

PROPERTY	VALUES
Origin	GATEWAY_2D, GATEWAY_3D, PAYMENT_LINK_2D

---

Search and resend notifications

Webhook management endpoints require a valid Bearer token. Searches and resend requests only consider records associated with the authenticated account.

Headers

Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

Search webhook

Use this operation to retrieve the payment link and the latest recorded HTTP status for a notification.

GET /api/webhook?paymentResultId=RESULT_ID

Parameter

PROPERTY	DESCRIPTION	TYPE	LOCATION	REQUIRED	MAXIMUM LENGTH
paymentResultId	Payment result identifier.	string	query	yes	100

Request example

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

🟢 200

Webhook found

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

When the callback is processed successfully, httpStatusCode is "200". Other values, such as "400" or "500", represent the status returned by the callback endpoint on the latest attempt. When no notification attempt has been made, the field is returned as an empty string. If no record is found for the authenticated account, all fields are returned as empty strings.

🔴 400

Returned when paymentResultId is missing or exceeds the maximum allowed length.

🔴 500

Internal error

[
  {
    "tag": "",
    "description": "The command could not be executed. Unknown error."
  }
]

Response fields

PROPERTY	DESCRIPTION	TYPE
paymentLinkId	Payment link identifier. It is empty when the payment is not associated with a link.	string
paymentResultId	Identifier of the payment result that was found.	string
httpStatusCode	Latest HTTP status returned by the callback endpoint. It is empty when no response has been recorded.	string

Resend webhook

Use this operation to request another delivery attempt for a webhook that has not been processed successfully. The request is queued and processed asynchronously.

POST /api/webhook/resend

Request body

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

Parameter

PROPERTY	DESCRIPTION	TYPE	LOCATION	REQUIRED	MAXIMUM LENGTH
paymentResultId	Identifier of the payment result whose webhook will be resent.	string	body	yes	50

Request example

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

🟢 202

Resend queued

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

The queued status confirms that the request was accepted for asynchronous processing; it does not represent the result of the new attempt. Search the webhook again to retrieve the updated httpStatusCode.

🔴 400

Webhook not found

[
  {
    "tag": "",
    "description": "Webhook not found."
  }
]

🔴 409

Returned when the webhook does not have a callback URL or has already been processed with HTTP status 200.

Webhook already processed

[
  {
    "tag": "",
    "description": "The webhook has already been processed successfully."
  }
]

🔴 500

Internal error

[
  {
    "tag": "",
    "description": "The command could not be executed. Unknown error."
  }
]

---

See also

Response codes

To correctly interpret transaction statuses received via webhook, see our full response-code table:

Authorizer Host Response Codes →