Hosted Payment Page API

The Hosted Payment Page (HPP) allows you to create secure, preconfigured payment sessions that redirect customers to a checkout interface for completing a transaction.

---

🔐 Authentication

All requests require a valid OIDC access token:

HTTP Header

Authorization: Bearer <access_token>
Content-Type: application/json

Obtain the token using OIDC flows (typically Client Credentials or Authorization Code flow).

---

🧭 Frontend Setup

Ensure window.InitData has client_key and session_id before the app loads.

JavaScript example:

window.InitData = {
  "client_key": "client_key",
  "session_id": "session_id"
}

---

🛠️ Backend Setup

1) Obtain an authentication token.

function createToken() {
  return loadJsonFile('[path]/secret.json')
    .then((secretData) => {
      return fetch(
        '/api/oauth2/login/token',
        {
          method: 'POST',
          headers: {
            'Content-Type': 'application/json',
            'Accept': 'application/json',
          },
          body: JSON.stringify({
            username: secretData.username,
            password: secretData.password
          })
        }
      ).then(response => {
        if (!response.ok) {
          throw new Error(`Network response was not ok: ${response.status}`);
        }
        return response.json();
      })
    })
}

2) Create a session using x-api-key and the access_token.

function createSession(data) { // data -> result from token endpoint
  const randomString = `date-${new Date().getTime()}`;
  return loadJsonFile('[path]/secret.json')
    .then((secretData) => {
      return fetch(
        '/api/sessions',
        {
          method: 'POST',
          headers: {
            'Content-Type': 'application/json',
            'Accept': 'application/json',
            'x-api-key': secretData.xApiKey,
            'Authorization': `Bearer ${data?.access_token}`
          },
          body: JSON.stringify({
            "terminal_id": "DEV02",
            "reference": randomString,
            "description": "f2aed380-b8bb-481f-92be-3060cc1ed4a2",
            "currency": "EUR",
            "amount": 25600,
            "transaction_type": "AUTHORIZE",
            "success_url": "https://google.com/success-url",
            "cancel_url": "https://google.com/failed-url",
            "customer": {
              "first_name": "John",
              "last_name": "Doe",
              "address": "Address",
              "city": "City",
              "country": "BA",
              "postal_code": "10000",
              "email": "email@email.com",
              "phone": "00000"
            },
            "country": "BA",
            "metadata": {
              "simulated_flow": "VERSIONING_FINGERPRINT_Y_CHALLENGE",
              "response_code": "APPROVED",
              "payment_provider_response_message": "approved",
              "payment_provider_response_code": "approved-code",
              "approval_code": "N/A"
            }
          })
        }
      ).then(response => {
        if (!response.ok) {
          throw new Error(`Network response was not ok: ${response.status}`);
        }
        return response.json(); // session id
      })
    })
}

---

📤 Endpoint

POST /api/hosted-payment-page

Creates a hosted payment session and returns a URL for redirection.

---

📦 Request Body

{
  "reference": "ORDER-123456",
  "terminal_id": "TERM001",
  "currency": "EUR",
  "amount": 100,
  "transaction_type": "PURCHASE",
  "description": "Order payment",
  "success_url": "https://merchant.example.com/success-url",
  "cancel_url": "https://merchant.example.com/cancel-url",
  "error_url": "https://merchant.example.com/error-url",
  "customer_id": "CUST123456",
  "customer_first_name": "John",
  "customer_last_name": "Doe",
  "customer_email": "john.doe@example.com",
  "customer_phone_number": "+1234567890",
  "customer_address": "123 Example Street",
  "customer_city": "Sampletown",
  "customer_country": "BA",
  "customer_postal_code": "12345",
  "tokenization": {
    "save_card_for_future_payments": true
  }
}

✅ Required Fields

Field	Type	Description
reference	string	Unique reference for the order
terminal_id	string	ID of the terminal used for payment
currency	string	Currency in ISO 4217 format (e.g., "EUR")
amount	integer	Amount in minor units (e.g., 100 = €1.00)
transaction_type	string	Must be "PURCHASE" or "AUTHORIZE"
success_url	string	Redirect URL after successful payment
cancel_url	string	Redirect URL if user cancels the transaction
error_url	string	Redirect URL for payment failure

🧾 Optional Fields

Field	Type	Description
description	string	Payment description shown on HPP
customer_id	string	Payment Platform customer ID
customer_first_name	string	Customer's first name
customer_last_name	string	Customer's last name
customer_email	string	Email address
customer_phone_number	string	Phone number (E.164 format recommended)
customer_address	string	Street address
customer_city	string	Sampletown
customer_country	string	ISO 3166-1 alpha-2 code (e.g., "BA")
customer_postal_code	string	ZIP/postal code
tokenization.save_card_for_future_payments	boolean	If true, initiates card tokenization if supported

---

🧾 Response

{
  "redirect_url": "https://api.example.com/hpp/payment/TO6FjoePBl0GoiAZI6IJeAYIuUanvAmaW1YsBpbj/GfXYVKxPXGksQhBJuyAZ",
  "session_id": "GfXYVKxPXGksQhBJuyAZ"
}

Field	Type	Description
redirect_url	string	Fully qualified URL to which the customer should be redirected for payment
session_id	string	Unique identifier for the hosted payment session

---

💳 Tokenization Notes

If tokenization.save_card_for_future_payments = true is used:

• Tokenization must be enabled on the terminal, payment provider, and provider account level.
• If unsupported, the response will include:

{
  "status": "INVALID",
  "errors": [
    {
      "property": "tokenization",
      "message": "one of requested features not supported=[TOKENIZATION]"
    }
  ]
}

---

⚠️ Misconfiguration Handling

If the link is invalid (e.g., no supported payment methods), the system returns a user-friendly message:

"This payment is currently unavailable. Please contact the merchant."

---

🔁 Redirects and Callbacks

• Cancel URL handling: if window.HppData.cancel_url exists, the user is redirected there when clicking back.
• Redirect URL: after payment completion on the server, redirect user to your chosen redirect_url.

---

✅ Best Practices

• Ensure client_key and session_id are available on the window before app load.
• Backend: first obtain an auth token, then create the session with x-api-key and Authorization.

---

🛠️ Troubleshooting

• Any issues during HPP setup are shown during the flow with descriptive errors and guidance.

---

🎨 Customization

Customization of Hosted Payment Page is currently not supported.

🧪 Sample cURL Request

curl -X POST https://api.example.com/api/hosted-payment-page \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "ORDER-123456",
    "terminal_id": "TERM001",
    "currency": "EUR",
    "amount": 100,
    "transaction_type": "PURCHASE",
    "success_url": "https://merchant.example.com/success-url",
    "cancel_url": "https://merchant.example.com/cancel-url",
    "error_url": "https://merchant.example.com/error-url",
    "tokenization": {
      "save_card_for_future_payments": true
    }
  }'