API reference

Hosted Payment Page

HPP API Reference

Overview

The Hosted Payment Page redirects customers to a secure provider-managed payment interface. Sensitive payment credentials do not touch the merchant's servers, helping reduce PCI DSS scope.

Reduced PCI scope

Payment data stays on the hosted payment service.

No card handling

The provider handles sensitive card data.

Mobile optimized

Responsive checkout across phones and computers.

Multiple methods

Cards, wallets, and supported accounts in one flow.

HPP request

Generate an HPP token and redirect URL by calling the unified API endpoint:

POST /asm
{
  "schemaVersion": "1.0",
  "requestId": "{{$guid}}",
  "timestamp": "{{$timestamp}}",
  "channelName": "WEB",
  "serviceName": "API_PURCHASE",
  "serviceParams": {
    "merchantUid": {{MERCHANT_UID}},
    "storeId": {{STORE_ID}},
    "hppKey": {{HPP_KEY}},
    "transactionInfo": {
      "referenceId": "ORDER-2024-001",
      "invoiceId": "INV-001",
      "amount": "150.00",
      "currency": "USD",
      "description": "E-commerce purchase",
      "returnUrl": "https://yoursite.com/payment/return",
      "cancelUrl": "https://yoursite.com/payment/cancel"
    }
  }
}

Request parameters

Parameter	Type	Presence	Description
`schemaVersion`	String	Constant	API schema version, such as 1.0
`requestId`	UUID String	Required	Unique request identifier
`merchantUid`	String	Required	Merchant identifier issued during account setup
`storeId`	String	Required	Merchant store identifier
`hppKey`	String	Required	HPP authentication key
`transactionInfo.referenceId`	String	Required	Unique internal order reference
`transactionInfo.invoiceId`	String	Required	Transaction invoice ID
`transactionInfo.amount`	String	Required	Amount with two decimal places
`transactionInfo.currency`	String	Required	ISO 4217 currency code, such as USD
`transactionInfo.description`	String	Optional	Transaction description
`transactionInfo.returnUrl`	String	Required	Post-payment redirect URL
`transactionInfo.cancelUrl`	String	Optional	Cancellation redirect URL

Response

A successful request returns an HPP URL for the customer redirect:

{
  "schemaVersion": "1.0",
  "timestamp": "2024-11-05 09:04:44.741",
  "responseId": "{{$guid}}",
  "responseCode": "2001",
  "errorCode": "0",
  "responseMsg": "RCS_SUCCESS",
  "params": {
    "hppRequestId": "HPP-2024-001",
    "hppToken": "eyJhbGciOiJIUzI1NiIsInR...",
    "hppUrl": "https://hpp.waafipay.com/pay?token=eyJhbGci...",
    "expiresAt": "2024-11-05 09:09:44.741"
  }
}