Webhook - Conciliation Notifications

API details

Conciliation and Bank Slips API

These APIs are used for additional features such as generating and managing bank slips:

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

The conciliation webhook allows you to receive automatic notifications about transaction status changes. This makes the integration more efficient by removing the need to frequently poll the API.

Notified events

The system monitors and notifies the following status changes:

Transaction status

• Authorized: Approved transaction
• Canceled: Irreversibly canceled transaction
• Blocked: Temporarily blocked transaction
• Paid: Payment completed successfully

Notification format

All notifications follow the JSON format below:

{
  "movementId": 0,
  "nsu": "string",
  "codAuth": "string",
  "installmentNumber": 0,
  "moment": "datetime",
  "type": "string",
  "oldValue": "string",
  "newValue": "string"
}

Retry mechanism

Communication resilience

The webhook implements a retry mechanism when communication with the client system fails.

Retries follow an exponential backoff policy, where the interval between attempts increases progressively. This behavior improves resilience, allowing temporarily unavailable systems to still receive notifications if they return to operation, even after hours of downtime.

Data dictionary - Notification

FIELD	DESCRIPTION	TYPE
movementId	Unique movement identifier	int
nsu	Unique transaction sequential number	string
codAuth	Authorization code	string
installmentNumber	Installment number	int
moment	Date and time of the change	datetime
type	Change type	string
oldValue	Previous value	string
newValue	New value	string

Client endpoint response

Response requirements

Your endpoint must return only an HTTP status code. There is no need to return a response body.

Expected status codes:

• 200 (OK): Successful processing
• 400 (Bad Request): Expected errors (invalid payload, incorrect data)
• 500 (Internal Server Error): Unexpected errors in your system

Subscription management

Register webhook

POST /api/webhooks/subscriptions?accountNumber={accountNumber}

Registers a URL to receive webhook notifications.

Required query params

You must send the accountNumber parameter via query params together with the request body.

Request

{
  "url": "https://meusite.com.br/webhook/notificacoes",
  "basicAuth": "dXNlcjpwYXNzd29yZA=="
}

Data dictionary - Parameters

Query Parameters

FIELD	DESCRIPTION	TYPE	SIZE	NOTES
accountNumber	Customer account number	string	-	Required for all webhook operations

Body Parameters

FIELD	DESCRIPTION	TYPE	SIZE	NOTES
url	Endpoint URL to receive notifications	string	-	Must be a valid, accessible URL
basicAuth	Credentials for basic auth	string	-	Format: Base64 of "username:password"

🟢 200

Response

{
  "url": "https://meusite.com.br/webhook/notificacoes"
}

Get webhook

GET /api/webhooks/subscriptions?accountNumber={accountNumber}

Returns the currently registered URL used to receive notifications.

Required query params

You must send the accountNumber parameter via query params.

🟢 200

Response

{
  "url": "https://meusite.com.br/webhook/notificacoes"
}

Delete webhook

DELETE /api/webhooks/subscriptions?accountNumber={accountNumber}

Removes the registered URL, stopping notifications.

Required query params

You must send the accountNumber parameter via query params.

🟢 200

Response

{
  "url": "https://meusite.com.br/webhook/notificacoes"
}

Best practices

Recommendations:

• Implement detailed logs for debugging
• Validate the received payload
• Process notifications asynchronously
• Monitor your endpoint health
• Respond within 30 seconds
• Keep the endpoint available 24/7