Checkout Session Completion Webhook (Draft)

Draft

This document describes a proposed webhook contract for Pay with Pyng. It is not final and may change before public release.

Partner can choose to receive a notification when a Checkout Session reaches a terminal state.

Pyng will deliver a notification to the partner's callback URL after the final state is known.

Terminal States

• Completed
• Cancelled
• Expired
• Failed

Request Headers

Header Name	Header Value
x-pyng-signature	Signature for webhook verification
x-pyng-signature-kid	Key identifier for public key lookup
x-pyng-timestamp	Timestamp used for replay protection
Content-Type	application/json

Request Body

Parameter Key	Parameter Data Type	Required	Notes
data	object	Y	Checkout Session completion data
traceId	string	Y	Unique identifier of the request

Checkout Session Completion Payload

Parameter Key	Parameter Data Type	Required	Notes
checkoutSessionId	string	Y	Unique Checkout Session id
orderId	string	Y	Partner order identifier
siteId	string	Y	Partner site identifier
status	string	Y	Final session status
outcome	string	Y	Final outcome
paymentIntentId	string	N	Related payment intent id
transactionId	string	N	Related transaction id
updatedAt	string	Y	Final status update timestamp

Notes

• Webhooks are asynchronous and should be treated as an authoritative completion signal.
• Partners should make webhook handling idempotent.
• Pyng intends to use public/private key signature verification so partners verify payloads with a Pyng public key rather than a shared secret.
• Webhook endpoints should be HTTPS only.
• Partners should acknowledge quickly with a 2xx response and process idempotently because duplicate delivery is possible.
• Expired is used when Hosted Checkout reaches its configured timeout before payment completion.
• Signature and replay-protection details are still draft and will be finalized later.