Webhooks

Webhooks (ingress)

Providers call these public endpoints after the customer finishes at the hosted checkout. PayWay resolves the charge session, verifies with the provider, updates status, and writes an idempotent usage log on first verified success. You do not call these — they document what PayWay receives.

Callback URL. PayWay registers {PublicBaseUrl}/v1/webhooks/{gateway}?session_id={chs_…} with the provider at initiation, so the session is always resolvable on the return trip.

POST/v1/webhooks/sslcommerz?session_id={sessionId}Public

SSLCommerz IPN

SSLCommerz posts the IPN here; PayWay validates and marks the session.

Content-Type is application/x-www-form-urlencoded. PayWay resolves the session by session_id (query) or tran_id, then marks success/failed/cancelled and writes the usage log idempotently.

Headers

Header	Value	Required	Notes
`Content-Type`	`application/x-www-form-urlencoded`	yes

Query parameters

Field	Type	Required	Notes
`session_id`	string	no	The chs_… id; PayWay adds this to the callback URL it registers.

Request body

Field	Type	Required	Notes
`status`	string	yes	VALID / VALIDATED / FAILED / CANCELLED.
`tran_id`	string	yes	Merchant transaction id sent at initiation.
`val_id`	string	no	Validation id used as the gateway transaction id.
`amount`	string	no	Paid amount.

Request examples

curl -X POST "https://api.payway.sianik.com/v1/webhooks/sslcommerz?session_id=chs_8f2a1c9d3b4e5f60"

Responses

200Acknowledged

{
  "message": "ok"
}

Respond 200 quickly. Production validates val_id against the SSLCommerz validation API.

GET/v1/webhooks/bkash?session_id={sessionId}&paymentID={id}&status={status}Public

bKash callback

bKash redirects the customer here after authorization; PayWay executes/queries and marks the session.

Query parameters

Field	Type	Required	Notes
`session_id`	string	no	The chs_… id.
`paymentID`	string	no	bKash payment id from callback (also accepts paymentId). Execute/Query body must use paymentId — see guide#bkash-paymentid.
`status`	string	no	success / failure / cancel.

Request examples

curl -X GET "https://api.payway.sianik.com/v1/webhooks/bkash?session_id=chs_8f2a1c9d3b4e5f60&paymentID=PAY123&status=success"

Responses

200Acknowledged

ok

Production executes the payment via the bKash driver using the slot's decrypted credentials before marking success.

bKash casing. Callback query uses paymentID. When PayWay (or your library-first code) calls Execute/Query, the JSON body must use paymentId. See hosted guide.

Handler sequence

Resolve the ChargeSession by session_id first, then provider payment id / sessionkey. Order references are not unique and are not used as a fallback.
Verify with the provider validation API (SSLCommerz) or execute/query (bKash).
Update the session status.
On first verified success: insert a UsageLog (idempotent) and apply fee rules.
Respond 200 quickly.