Push Transaction Status API

Partners can choose to receive a notification when a transaction reaches a final state.

Pyng delivers the notification to the partner's callback URL as soon as the final transaction status is known.

The partner should respond with an HTTP status code between 200 and 299 to indicate successful processing.

Retries

Pyng retries failed notifications up to 5 times using exponential backoff.

Signature

Pyng will generate Base64 encoded SHA256 HMAC cryptographic signature that should be used to verify integrity and source of the message. Partner is assigned unique secret, which should be used to verify signature.

Overview

This webhook provides the final status of a transaction created through the Checkout API.

Notification Schema

Request Headers

Header Name	Header Value
x-pyng-signature	Base64 SHA-256 cryptographic signature

Request Body

Parameter Key	Parameter Data Type	Required	Notes
data	object	Y	Object of TransactionStatusPushRequest type
traceId	string	Y	Unique identifier of the request

TransactionStatusPushRequest

Parameter Key	Parameter Data Type	Required	Notes
idempotencyKey	string	Y	Unique identifier of the notification. Redeliveries will have the same idempotencyKey. When partner receives notification with the idempotencyKey they successfully processed before - notification should be ignored
siteId	object	Y	Site payment intent is associated with. Object of SiteId
paymentIntentId	string	Y	Id of the payment intent transaction is associated with.
transactionId	string	N	Unique identifier of the transaction, assigned by Pyng. Available if customer has scanned QR code and started a payment.
transactionStatus	string	Y	One of TransactionStatusEnum
transactionStatusDescription	string	N	Additional information regarding the status of the transaction if available
transactionUpdated	integer	N	Unix timestamp indicating when transaction was last updated. Available if customer has scanned QR code and started a payment.
orderId	string	N	Available if partner passed orderId parameter to create payment intent
lineItems	array	N	Optional. Itemized purchase details. See Line Items
amountPaid	integer	N	Optional. Actual charged amount in cents

SiteId

Parameter Key	Parameter Data Type	Required	Notes
id	string	Y	Primitive id of the site, payment intent is associated with

Line Items

See the canonical Line Items definition in the Pull Transaction Status doc: Line Items.

Example

POST /partner/callback-url HTTP/1.1
Host: partner-integration.pyng.com.au
x-pyng-signature: SHA256Signature
Content-Type: application/json
{
    "data":
    {
        "idempotencyKey": "a7fd3e0f-472b-4b25-94c9-dee6688d0606",
        "siteId": { "id": "site-abc-123" },
        "paymentIntentId": "05e6d32f-93a3-4eba-ad13-a41c57e1e8b2",
        "transactionId": "bae2e821-7a31-7924-c030-de18a9abeea2",
        "transactionStatus": "Settled",
        "transactionUpdated": 1731821436160,
        "transactionStatusDescription": "Insufficient Funds",
        "orderId": "b723f133-a98b-400c-8a5a-bfd0350a6f6d",
        "lineItems": [
          {
            "itemId": "flat-white",
            "quantity": 1,
            "amountPerUnit": 450,
            "amountSubtotal": 500,
            "amountTotal": 500,
            "addOns": { "customizations": "Extra shot", "modifiers": ["extra-shot"] }
          },
          {
            "itemId": "flat-white",
            "quantity": 1,
            "amountPerUnit": 450,
            "amountSubtotal": 550,
            "amountTotal": 550,
            "addOns": { "customizations": "Oat milk", "modifiers": ["oat-milk"] }
          },
          {
            "itemId": "SKU1234-56789",
            "quantity": 1,
            "amountPerUnit": 890,
            "amountSubtotal": 1090,
            "discounts": [
              { "amount": 100, "reason": "Site promotion" },
              { "amount": 50,  "reason": "POS coupon" }
            ],
            "amountTotal": 940,
            "addOns": { "customizations": "Gluten-free bread", "modifiers": ["gluten-free-bread"] }
          },
          {
            "itemId": "blueberry-muffin",
            "quantity": 1,
            "amountPerUnit": 450,
            "amountSubtotal": 450,
            "amountTotal": 450,
            "addOns": { "customizations": "Warmed", "modifiers": ["warmed"] }
          }
        ],
        "amountPaid": 2940
    },
    "traceId": "6b54f8d3-04eb-479b-9929-3645ce27dedc"
}

Notes

• Webhook delivery is asynchronous.
• Partners should make webhook handling idempotent.
• Redeliveries reuse the same idempotencyKey.