Skip to content

Create Payment Intent API

Use this endpoint to create a payment intent for a partner checkout flow.

After a successful response, the partner receives a QR code representation of the payment intent. The QR code can then be displayed on a POS screen or website for the customer to scan with the Pyng App.

URL path - /checkout/{siteId}/payment-intent

Method - POST

Overview

This endpoint is intended for payment-intent-based checkout flows, including QR-driven customer payments.

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

Body Parameters

Parameter Key Parameter Data Type Required Notes
amount integer Y Payment amount in cents. Amount must be a positive integer. Minimum value is 1
orderId string N Unique order identifier generated by a partner
qrCodeFormat string N Format of the Qr Code. One of QrCodeFormat. Default - base64
lineItems array N Optional itemized purchase details for receipt/promo mapping. See Line Items

QrCodeFormat

Partners can request the QR code in one of the supported formats.

Format Notes
base64 Payment intent will be returned as base64 encoded png image. Can be displayed on the screen without any extra conversions.
text Payment intent will be returned as plain text. Client has to encode received text as a QR Code to display it.

Line Items

Partners can optionally send itemized purchase details. These do not change the payment authorization flow; they enable item-level promotions, discounts and itemized webhooks.

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

Response

Status Code - 201 Created

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

CreatePaymentIntentResponse

Parameter Key Parameter Data Type Required Notes
qrCode string Y Payment intent representation in the requested format
paymentIntentId string Y Unique identifier of payment intent generated by Pyng
orderId string N Unique order identifier generated by a partner and passed in the request

Notes

  • amount must be provided in cents.
  • orderId is recommended when the partner needs downstream reconciliation.
  • lineItems are optional and do not change the payment authorization behavior.

Examples

Request

POST /checkout/{siteId}/payment-intent HTTP/1.1
Host: sample.pyng.com.au
Authorization: Bearer access_token
Content-Type: application/json

{
  "amount": 2500,
  "orderId": "57688c4d-bf47-4cd0-a4db-b9d3e77a0269"
}

Request (with line items)

POST /checkout/{siteId}/payment-intent HTTP/1.1
Host: sample.pyng.com.au
Authorization: Bearer access_token
Content-Type: application/json

{
  "amount": 3090,
  "orderId": "order-xyz-789",
  "qrCodeFormat": "base64",
  "lineItems": [
    {
      "itemId": "flat-white",
      "quantity": 2,
      "amountPerUnit": 450,
      "amountSubtotal": 1000,
      "addOns": { "customizations": "Extra shot", "modifiers": ["extra-shot"] }
    },
    {
      "itemId": "flat-white",
      "quantity": 1,
      "amountPerUnit": 450,
      "amountSubtotal": 550,
      "addOns": { "customizations": "Oat milk", "modifiers": ["oat-milk"] }
    },
    {
      "itemId": "SKU1234-56789",
      "quantity": 1,
      "amountPerUnit": 890,
      "amountSubtotal": 1090,
      "addOns": { "customizations": "Gluten-free bread", "modifiers": ["gluten-free-bread"] }
    },
    {
      "itemId": "blueberry-muffin",
      "quantity": 1,
      "amountPerUnit": 450,
      "amountSubtotal": 450,
      "addOns": { "customizations": "Warmed", "modifiers": ["warmed"] }
    }
  ]
}

Response

HTTP/1.1 201 Created
Content-Type: application/json;charset=UTF-8
{
    "data":
    {
        "qrCode": "data:image/png;base64,qrCode===",
        "paymentIntentId": "92332209-0785-4f76-8787-ca08354f58f4"
    },
    "traceId": "9ae2e340-b983-4274-b400-c974a9ab40ab"
}

Error Response

HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8

{
  "errors": [
    {
      "message": "amount must be greater than 0"
    }
  ],
  "traceId": "9ae2e340-b983-4274-b400-c974a9ab40ab",
  "timestamp": 1731821436160
}