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 for saved cards (required to use saved payment methods)
`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`	City name
`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`, automatically saves the card for future use
`tokenization.show_save_card_for_future_payments`	`boolean`	If `true`, displays a checkbox allowing customers to opt-in to save card

🧾 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 at the merchant level (contact your payment platform administrator to enable this feature).
If unsupported, the response will include:

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

For detailed information on the two methods of saving cards, see the Saving Cards for Future Payments section below.

💾 Saving Cards for Future Payments¶

The HPP supports two methods for saving payment cards for future use:

Feature	`show_save_card_for_future_payments`	`save_card_for_future_payments`
Displays checkbox	✅ Yes	❌ No
Customer consent	Explicit (opt-in)	Implicit
Use case	Customer choice	Subscription/recurring payments

Method 1: `show_save_card_for_future_payments`¶

This parameter displays a checkbox on the HPP allowing customers to opt-in to saving their card.

Request Body Example:

{
  "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",
  "customer_id": "CUST123456",
  "tokenization": {
    "show_save_card_for_future_payments": true
  }
}

When show_save_card_for_future_payments is set to true, a checkbox appears on the payment page allowing the customer to choose whether to save their card for future payments.

Method 2: `save_card_for_future_payments`¶

This parameter implicitly saves the card without displaying a checkbox to the customer.

Request Body Example:

{
  "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",
  "customer_id": "CUST123456",
  "tokenization": {
    "save_card_for_future_payments": true
  }
}

When save_card_for_future_payments is set to true, the card is automatically saved without requiring customer interaction.

⚠️ Compliance Note: When using save_card_for_future_payments (implicit saving), ensure your terms of service and privacy policy inform customers that payment information will be stored for future use. Depending on your jurisdiction, this may have regulatory implications (GDPR, PCI-DSS, etc.).

Note: If both show_save_card_for_future_payments and save_card_for_future_payments are set to true, the save_card_for_future_payments behavior takes precedence and the card is saved without displaying a checkbox.

🔑 Requirements for Card Tokenization¶

For both methods to work, the following requirements must be met:

Tokenization must be enabled at the merchant level
Customer must exist: A customer with the specified customer_id must already exist in the Payment Platform before creating the HPP session (if customer_id is provided). If the customer doesn't exist, the API will return a validation error.

📌 Assigning Saved Payment Methods to a Customer¶

When a card is successfully saved (via either method):

With customer_id: The saved payment method is automatically assigned to the specified customer_id. The customer record must already exist in the Payment Platform before creating the HPP session.
Without customer_id: The payment method is still saved but remains unassociated with any customer. These payment methods can be retrieved via API but cannot be associated with a customer later.

Important Notes:

Payment methods saved with a customer_id are linked to that customer profile
Payment methods saved without a customer_id remain permanently unassociated
To save a payment method for a specific customer, include the customer_id in the initial HPP request

💳 Paying with Saved Cards¶

Customers who have saved payment methods can use them for future payments by providing their customer_id.

Using Saved Cards via HPP¶

When a customer_id is included in the HPP request, and that customer has saved payment methods, the HPP will display a "Saved Cards" payment option allowing the customer to select from their previously saved cards.

Request Body Example:

{
  "reference": "ORDER-789012",
  "terminal_id": "TERM001",
  "currency": "EUR",
  "amount": 5000,
  "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",
  "customer_id": "CUST123456"
}

Using Saved Cards via API¶

Saved payment methods can also be used directly through the API by referencing the payment method token. See the API Integration documentation for details on using saved payment methods with direct API calls.

⚠️ Important: Customer ID Required¶

It is not possible to pay with a saved card if no customer_id is provided in the request.

Without a customer_id, the system cannot retrieve saved payment methods
Always include the customer_id field when you want to enable saved card payment options

⚠️ 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",
    "customer_id": "CUST123456",
    "tokenization": {
      "save_card_for_future_payments": true
    }
  }'

Hosted Payment Page API¶

🔐 Authentication¶

HTTP Header¶

🧭 Frontend Setup¶

🛠️ Backend Setup¶

📤 Endpoint¶

📦 Request Body¶

✅ Required Fields¶

🧾 Optional Fields¶

🧾 Response¶

💳 Tokenization Notes¶

💾 Saving Cards for Future Payments¶

Method 1: show_save_card_for_future_payments¶

Method 2: save_card_for_future_payments¶

🔑 Requirements for Card Tokenization¶

📌 Assigning Saved Payment Methods to a Customer¶

💳 Paying with Saved Cards¶

Using Saved Cards via HPP¶

Using Saved Cards via API¶

⚠️ Important: Customer ID Required¶

⚠️ Misconfiguration Handling¶

🔁 Redirects and Callbacks¶

✅ Best Practices¶

🛠️ Troubleshooting¶

🎨 Customization¶

🧪 Sample cURL Request¶

Method 1: `show_save_card_for_future_payments`¶

Method 2: `save_card_for_future_payments`¶