Skip to content

Pull Transaction Status API

Use this endpoint to retrieve the current status of a payment-intent-based transaction.

After the customer scans the QR code and approves payment in the Pyng App, the transaction is expected to reach a final state within a short period.

Recommended polling interval:

  • every 5 seconds after the Create Payment Intent API call

URL path - /checkout/{siteId}/transaction-status

Method - GET

Overview

This endpoint provides the authoritative transaction status for a previously created payment intent.

Request Headers

Header Name Header Value Notes
Content-Type application/json
Authorization Bearer access_token Access token must have an appropriate scope to access resource

Path Parameters

Parameter Key Parameter Data Type Notes
siteId string Unique site id assigned to the Partner's site by Pyng

Query parameters

Parameter Key Parameter Data Type Required Notes
paymentIntentId string Y Unique id of the payment intent

Response

Status Code - 200 OK

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

TransactionStatusResponse

Parameter Key Parameter Data Type Required Notes
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

Line Items

Parameter Key Parameter Data Type Required Notes
itemId string Y Identifier of the item (or SKU) in partner's catalogue
quantity integer Y Item quantity. Must be greater or equal to 1
amountPerUnit integer Y Amount per unit in cents. Excludes any add-ons
amountSubtotal integer Y Line subtotal in cents (includes add-ons, before discounts)
addOns object N Optional metadata
├─ customizations string N Free-text description of applied add-ons
└─ modifiers string[] N Modifier identifiers/keys
discounts array N Discounts applied to this item (if any)
├─ amount integer N Discount amount in cents
└─ reason string N Human-readable reason for discount
amountTotal integer N Amount after all discounts in cents (if any)

TransactionStatusEnum

Status Final Notes
Pending N Payment intent has been generated but customer hasn't scanned QR code. If QR Code has not been scanned in 60 seconds - Qr Code will expire
InProgress N Customer has scanned QR Code and started payment
Settled Y Transaction has been successfully settled with the retailer's financial institution
Declined Y Transaction has been declined or rejected by customer, customer financial institution or retailer financial institution
Expired Y QR code has not been scanned within 60 seconds and cannot be used anymore. New Qr Code has to be generated

Notes

  • Pending and InProgress are non-final states.
  • Settled, Declined, and Expired are final states.
  • Partners can use this endpoint together with webhook delivery for reconciliation and resilience.

Examples

Request

GET /checkout/{siteId}/transaction-status?paymentIntentId={paymentIntentId} HTTP/1.1
Host: sample.pyng.com.au
Authorization: Bearer access_token

Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
    "data":
    {
        "transactionId": "bae2e821-7a31-7924-c030-de18a9abeea2",
        "transactionStatus": "Settled",
        "transactionUpdated": 1731821436160,
        "transactionStatusDescription": "Insufficient Funds",
        "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"
}

Error Response

HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8

{
  "errors": [
    {
      "message": "payment intent not found"
    }
  ],
  "traceId": "6b54f8d3-04eb-479b-9929-3645ce27dedc",
  "timestamp": 1731821436160
}