Getting started

This quickstart shows you how to integrate Hubpay’s Hosted Payment Page (HPP) into your application or website.

You’ll learn how to:

Create a payment link
Redirect customers to our secure checkout page
Handle the result (confirmation, cancellation) using redirect URLs and webhooks

💡 You’ll need API credentials and access to the Collections API.
See our Authentication Guide for more details.

1. Create a payer (if needed)

If you don’t already have a payerId, create one using the API.
This identifies the customer who will make the payment.

📘 API Reference → Create Payer

2. Upload a document

Upload a supporting document (like an invoice or contract) for compliance and transaction clarity.

📘 API Reference → Upload Document

{
  "id": "550e8400-e29b-41d4-a716-446655440000"
}

3. Create a payment request

Create a payment request referencing the payerId and documentId.
Be sure to set executionMode to HOSTED_PAGE in your request payload.
The response will contain a paymentUrl with an attached sessionToken (signed JWT).
This token is required to access the payment page and is valid for 1 hour.

📘 API Reference → Create Payment Request

Part of an example payload:

{
  "payerId": "550e8400-e29b-41d4-a716-446655440000",
  "executionMode": "HOSTED_PAGE",
  "successRedirectUrl": "https://yourapp.com/success",
  "cancelRedirectUrl": "https://yourapp.com/cancel"
}

Part of an example response:

{
  "paymentUrl": "https://pay.hubpay.ae/AH-VGTJ-24GX?sessionToken=eyJhbGciOiJSUzI1NiIs...",
  "successRedirectUrl": "https://yourapp.com/success",
  "cancelRedirectUrl": "https://yourapp.com/cancel"
}

When payment succeeds, Hubpay adds paymentRequestId and paymentId as query parameters to your success redirect URL:

https://yourapp.com/success?paymentRequestId=8a282576-18c0-4c0e-b158-44b92eda1afe&paymentId=46be2ff1-cdbf-4b3d-a4cd-beb0fb22ea0d

If the session expires before payment is complete, you can refresh it using refresh payment session API which returns a new payment URL with the latest sessionToken, granting the user an additional 1 hour to complete payment.

4. Redirect the customer

Send your user to the paymentUrl:

window.location.href = paymentUrl;

For React Native, use react-native-webview:

<WebView
    source={{ uri: paymentUrl }}
    onMessage={handleMessage}
/>

After the redirect, your customer will see a page similar to this:

payment portal options

Typically, the customer is redirected after clicking a “Pay” button or completing their payment confirmation.

5. Handle redirect result

After payment or cancellation, the customer is redirected to your chosen URLs:

payment portal redirect

Outcome	Description
`successRedirectUrl`	Payment completed. Use the appended IDs to confirm the payment in your backend.
`cancelRedirectUrl`	Customer cancelled or left the payment page.

📱 For React Native, handle the message in your webview handler:

const handleMessage = (event) => {
    try {
        const message = JSON.parse(event.nativeEvent.data);
        switch (message.type) {
            case "success":
                // Handle success, e.g. navigate to success screen with IDs
                break;
            case "cancel":
                // Handle cancellation
                break;
        }
    } catch (error) {}
};

For secure confirmation of all payments, see Confirming payments.

6. (Optional) Listen for webhooks

Set up webhooks to get real-time notifications of payment events:

v1.collection.payment_request.created
v1.collection.payment_request.paid
v1.collection.payment_request.part_paid
v1.collection.payment_request.cancelled

7. (Optional) Customize branding

For details on branding your payment experience, see Branding.

Need help?
Contact our team or check the API Reference for more details.

1. Create a payer (if needed)​

2. Upload a document​

3. Create a payment request​

4. Redirect the customer​

5. Handle redirect result​

6. (Optional) Listen for webhooks​

7. (Optional) Customize branding​