Skip to main content

Hosted payment page

The hosted payment page is a Hubpay checkout reached by redirect. Hubpay handles the payment interface while your application controls the order, payer and return journey.

Use this model when you want a checkout integration without collecting payment details in your own interface.

How it works​

  1. Create or identify the payer
  2. Upload a supporting document if your account or payment method requires one
  3. Create a payment request with executionMode set to HOSTED_PAGE
  4. Redirect the customer to the returned paymentUrl
  5. Receive the customer at your success or cancellation URL
  6. Confirm the payment from a signed webhook or API lookup

Your backend must create the payment request. Do not expose Hubpay client credentials in browser code.

Redirects and payment state​

A redirect to successRedirectUrl means the customer completed the checkout journey. It does not always mean funds have been received or settled. For example, a bank-transfer customer may have received instructions but not yet sent the transfer.

Use payment lifecycle webhooks and fetch the payment request to determine the current status before taking a backend action.

Expiry​

A hosted payment request carries an expiresAt 60 minutes after creation. The payer can start a payment for the first 45 minutes; the last 15 minutes let funds already sent arrive. Time spent before the quote screen comes off the quote window: a payer who reaches it 15 minutes after creation sees a 30 minute quote, one who reaches it at 40 minutes sees a 5 minute quote. The request becomes EXPIRED and emits v1.collection.payment_request.expired at the 45 minute mark if the payer never took a quote or started a card or bank payment, otherwise at expiresAt if it is still unpaid or part paid, unless a deposit sent in time is still confirming, in which case it becomes PAID if that deposit covers the balance and expires otherwise. See Payment request events.

What the payer sees on the hosted page follows the same clock. At the 45 minute mark, a payer who has not started a payment is shown that the request no longer accepts new payments, with a Return to merchant button to the request's cancelRedirectUrl when one is set; a card payment, bank transfer or crypto deposit already under way keeps its screen. Once the request has expired, the page shows that the request is no longer open and, when cancelRedirectUrl is set, returns the payer there after a short countdown, again with a button to go at once. Without a cancelRedirectUrl the payer stays on the message, so set one on every hosted request whose payer should be able to get back to you.

Session security​

The hosted paymentUrl contains a signed sessionToken. It is valid for up to one hour and never outlives the payment request's expiresAt.

If the token expires while the payment request is still UNPAID or PART_PAID and before expiresAt, call Refresh payment session. The response contains a new payment URL whose session runs for the remainder of the request's lifetime. Once the request has expired, the refresh is refused; the payment URL still opens and shows the EXPIRED state.

The payer must have an email address on file to refresh the session for a crypto-enabled payment request.

Branding​

Your Hubpay-hosted checkout can use the colours and logo configured for your account. See Payment page branding.

Next steps​