3.3 PayIn Webhook Delivery

Webhook request

Format

Property	Value
Method	POST
URL	Your callback_url or the shop's webhook_url.
Body	JSON object.

Headers

Header	Description
Content-Type	application/json
X-Timestamp	ISO-8601 timestamp (UTC) of the request.
X-Signature	HMAC-SHA256 signature.

Payload

Field	Type	Description
id	number	Internal transaction ID.
external_id	string	Merchant identifier from the create request.
shop_code	string	Shop code.
status	string	Current external payin status.
amount	string	Transaction amount.
currency	string	Transaction currency.
paymentData	object	Shop-schema output, when configured and non-empty.
updated_at	string	ISO-8601 timestamp of the status update.

Signature

To verify the webhook, compute:

message = X-Timestamp + raw_request_body
signature = HMAC_SHA256(webhook_secret, message)

Compare the computed signature with the X-Signature header using a constant-time comparison.

Example payload

{
  "id": 12345,
  "external_id": "PIN-BDT-001",
  "shop_code": "your_bdt_shop",
  "status": "success",
  "amount": "5000.00",
  "currency": "BDT",
  "paymentData": {
    "payment_link": "https://pay.example.com/bdt/PIN-BDT-001"
  },
  "updated_at": "2025-12-05T10:15:00.000000Z"
}

Delivery

Webhook URL

The platform uses the first available URL:

1. Per-request callback_url from the Create PayIn request.
2. Shop default webhook_url, when configured and enabled.

If neither URL is set, no webhook is sent for that transaction.

Requirements

Your endpoint must respond with HTTP 2xx for delivery to be considered successful.

Any other status, network error, or timeout is treated as a failed attempt.

Retries

The platform retries up to 5 attempts total with delays of 1 minute, 5 minutes, 30 minutes, 60 minutes, and 120 minutes.

Design your endpoint to be idempotent so receiving the same status change more than once is safe.

Example acknowledgment

HTTP/1.1 200 OK
Content-Type: application/json

{
  "received": true
}