Skip to main content

Getting started

This guide shows you how to generate and use Payment Links with Hubpay.

You’ll learn how to:

  • Create a payment link
  • Share it with your customer
  • Handle the result and confirm payment securely

💡 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​

Hubpay requires an official document (such as an Invoice, Purchase Order, Sales Purchase Agreement, Commercial Contract etc.) to verify the transaction details and ensure compliance with UAE regulatory requirements.

📘 API Reference → Upload Document

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

3. Create a payment request​

Use the API to create a new payment link.
Be sure to set executionMode to PAYMENT_LINK in your request payload. Specify the amount, currency, payer details (if needed), and any metadata.

📘 API Reference → Create Payment Request

Part of the response will look like this:

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

When the payer completes their payment journey, 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
Important

The successRedirectUrl redirect means the payer has completed their payment journey, not that funds have been received.

For example, with bank transfers, the payer may have successfully submitted payment instructions, but Hubpay has not yet received the funds.

Always verify payment status via webhook or API lookup before fulfilling orders or providing services.

Send the paymentUrl to your customer via email, SMS, WhatsApp, CRM, or any preferred channel.

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

payment link options

5. Customer completes payment​

The customer reviews the payment details and completes payment using their preferred method.

6. Confirm the payment​

Do not rely solely on the redirect to successRedirectUrl. Always confirm payment via webhook or API.

The redirect to successRedirectUrl means the payer has completed their journey (e.g., submitted bank transfer instructions), but does not confirm that Hubpay has received the funds.

MethodDescription
WebhookListen for the payment_request.paid event on your backend.
API lookupPoll GET /v1/collections/payment-requests/{id} for status.

payment link confirmation

For secure confirmation of all payments, see Confirming payments.

info

Always confirm payment on your backend!

Never trust only the redirect or browser UI. The successRedirectUrl redirect indicates the payment journey is complete, not that funds have been received. Use webhooks or API lookup to validate actual payment status before delivering goods or services.

5. (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

6. (Optional) Customize branding​

For details on branding your payment links, see Branding.

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