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)​
You can either reference an existing payer by payerId, or create one inline when creating the payment request.
- Existing payer: If you already have a
payerId, you can skip this step and pass it directly in the payment request. - New payer: Create one ahead of time using the API, or provide the payer details inline in the
payerfield of the payment request (see step 3).
📘 API Reference → Create Payer
2. Upload a document (optional)​
Depending on your merchant configuration and selected payment method(s), Hubpay may require 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, and either a payerId or inline payer details.
Set autoSendPaymentLink to true to automatically email the payment link to the payer.
📘 API Reference → Create Payment Request
Part of the response will look like this:
{
"paymentUrl": "https://pay.hubpay.io/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
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.
4. Share the link​
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:
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.
| Method | Description |
|---|---|
| Webhook | Listen for the payment_request.paid event on your backend. |
| API lookup | Poll GET /v1/collections/payment-requests/{id} for status and payment details. The response includes the list of payments made against the request. |
For secure confirmation of all payments, see Confirming payments.
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.createdv1.collection.payment_request.paidv1.collection.payment_request.part_paidv1.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.