HPP Integration Guide

This page contains the step-by-step integration reference for Hosted Payment Pages, including the Payment Request shape, redirect mechanics, and result handling.

Step 1: Create a Payment Request

Create a Payment Request that includes the hostedPaymentPage object. The presence of this object signals that the request is intended for the hosted checkout flow.

Endpoint: POST /paymentrequests

For general Payment Request fields, see Create a Payment Request. HPP-specific fields (hostedPaymentPage and its children) are documented on this page; they are not yet included in the published OpenAPI specification.

Minimal HPP Request:

{
    "reference": "INV-2026-001",
    "payment": {
        "amount": 3000,
        "currencyCode": "AUD",
        "description": "Payment for Order #12345"
    },
    "paymentMethods": [
        "card"
    ],
    "transactionRequest": {
        "category": {
            "frequency": "single",
            "captureType": "auto"
        }
    },
    "hostedPaymentPage": {
        "merchantName": "Acme Store",
        "logo": "data:image/png;base64,iVBORw0KGgo..."
    }
}

Response (excerpt):

{
    "id": "zWIEEs6BBU2A3GUQ8gD3Ag",
    "reference": "INV-2026-001",
    "createdDateTime": "2026-01-27T10:15:00Z",
    "paymentRequestStatus": "created",
    "hostedPaymentPage": {
        "url": "https://sandbox.hosted.gpaunz.com/hpp/zWIEEs6BBU2A3GUQ8gD3Ag"
    }
}

Use the hostedPaymentPage.url value from the response to redirect the customer. Do not construct the URL manually.

Step 2: Redirect the Customer

Redirect the customer’s browser to the hostedPaymentPage.url returned in the Step 1 response.

Example redirect:

HTTP/1.1 302 Found
Location: https://sandbox.hosted.gpaunz.com/hpp/zWIEEs6BBU2A3GUQ8gD3Ag

The customer arrives at the SAPI-hosted page, which displays merchant branding, the payment amount, and the payment form — all without requiring any frontend JavaScript on your site.

Step 3: Customer Completes Payment

The hosted page handles:

Displaying the payment form to the customer.
Processing the payment submission by creating the transaction via SAPI.
Showing the result (or redirecting back to your site — see resultPage below).

The merchant has no frontend responsibilities during this step.

Step 4: Outcome Display

After the transaction completes, HPP behaviour depends on the resultPage value in your Payment Request:

`resultPage`	Behaviour
`show` (default)	HPP displays a hosted result page showing the transaction outcome. When `redirectUrl` is provided, the result page includes a link back to the merchant site.
`redirect`	On approved transactions, HPP automatically redirects the customer to `redirectUrl`. On declined or failed transactions, the hosted result page is displayed.
`none`	Accepted API value.

When resultPage is redirect, the redirectUrl field is required.

End-to-End Flow (Diagram)

sequenceDiagram
    autonumber
    participant Merchant Server
    participant Customer Browser
    participant HPP (SAPI-Hosted)
    participant Single API

    Merchant Server->>Single API: POST /paymentrequests (with hostedPaymentPage)
    Single API-->>Merchant Server: Payment Request ID + hostedPaymentPage.url
    Merchant Server-->>Customer Browser: Redirect to returned HPP URL
    Customer Browser->>HPP (SAPI-Hosted): Load HPP
    HPP (SAPI-Hosted)-->>Customer Browser: Render payment page
    Customer Browser->>HPP (SAPI-Hosted): Customer submits payment
    HPP (SAPI-Hosted)->>Single API: Create transaction
    Single API-->>HPP (SAPI-Hosted): Transaction result
    alt resultPage = "redirect" and approved
        HPP (SAPI-Hosted)-->>Customer Browser: Redirect to merchant redirectUrl
    else resultPage = "show" or declined/failed
        HPP (SAPI-Hosted)-->>Customer Browser: Display hosted result page
    end
    alt Webhooks (recommended)
        Single API-->>Merchant Server: Transaction webhook
        Single API-->>Merchant Server: Payment Request webhook
    else Polling (fallback)
        Merchant Server->>Single API: GET /paymentrequests/{id}
        Single API-->>Merchant Server: Payment Request with transaction result
    end

`hostedPaymentPage` Object Reference

Field	Type	Required	Description
`merchantName`	string	No	Displayed on the payment page. Max 140 characters. When omitted, the platform uses the merchant name from your account configuration.
`logo`	string	Yes	Base64-encoded image (PNG, SVG, or WebP). Max 10 KB decoded. Prefix with the appropriate data URI (e.g. `data:image/png;base64,...`).
`resultPage`	string	No	Controls post-payment behaviour. Accepted values: `show` (default), `redirect`, `none`. See Outcome Display for `show` and `redirect` behaviour.
`redirectUrl`	string	Conditional	Required when `resultPage` is `redirect`. On approved transactions, the customer is automatically redirected to this URL. When `resultPage` is `show` and this field is provided, the result page includes a link back to the merchant site. Must be a valid URL.
`lineItems`	array	No	Line item breakdown displayed on the payment page. Max 50 items. See below.
`adjustments`	array	No	Adjustments (discounts, shipping, tax) displayed on the payment page. Max 10 items. Requires `lineItems` to be present. See below.

`lineItems` Array

Field	Type	Required	Description
`title`	string	Yes	Line item title. Max 50 characters.
`image`	string	No	URL (`http` or `https`) of the line item image.
`amount`	integer	Yes	Amount in cents. Must be ≥ 0.
`quantity`	float	No	Quantity (default: 1). Must be > 0. Rounded to 3 decimal places.
`modifier`	string	No	Unit label (e.g. “each”, “kg”). Max 50 characters.

`adjustments` Array

Field	Type	Required	Description
`title`	string	Yes	Adjustment title. Max 30 characters.
`amount`	integer	Yes	Amount in cents. Can be negative (discount) or positive (fee).
`adjustmentType`	string	Yes	One of: `Other`, `Discount`, `Shipping`, `Tax`.
`order`	integer	No	Display order. If provided, must be set on all adjustments (no duplicates).

Important: The sum of (lineItem.amount × lineItem.quantity) for all line items plus the sum of all adjustment.amount values must equal payment.amount.

Payment Request Defaults

When hostedPaymentPage is present:

Field	Default
`paymentMethods`	`["card"]`
`transactionRequest.category.frequency`	`single`
`attempts`	`1` (allowed range: 1–3)

Retry Behaviour

If a payment is declined, the customer can retry on the same HPP page up to the configured attempts limit (default: 1, maximum: 3). Once attempts are exhausted, the HPP displays an appropriate message.

Testing & Sandbox

HPP uses the same sandbox environment as the API.

Sandbox scenarios are triggered by specific input values (e.g. payment.amount) rather than test card numbers. See: