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:

1. Displaying the payment form to the customer.
2. Processing the payment submission by creating the transaction via SAPI.
3. 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:

• Testing Introduction
• Sandbox Scenario - Card Not Present