Skip to main content

PaymentRequest

Details of a payment request

executionModestringrequired

Specifies how the payer is expected to complete the payment request

Possible values: [PAYMENT_LINK, HOSTED_PAGE]

iduuidrequired

System-generated unique identifier for the payment request

externalIdstringrequired

Client-provided identifier for the payment request, used for idempotency or external reference

Possible values: <= 36 characters

accountIduuidrequired

Unique identifier of the account associated with this payment request

payerIduuidrequired

Unique identifier of the payer

receivingCurrencyTypestringrequired

Specifies if the payment will be made using FIAT or CRYPTO

Possible values: [FIAT, CRYPTO]

receivingCurrencystringrequired

Three-letter ISO or crypto currency code for settlement

Possible values: non-empty, Value must match regular expression [A-Z]{3,5}

Example: AED
receivingAmountnumberrequired

Amount to be received in the specified currency

Example: 150
dueDatedate

Optional due date by which the payment should be made

documentReferencestringrequired

Document reference such as an invoice number or PO reference

Possible values: non-empty

documentIduuid

Internal document UUID associated with this payment request

paymentMethodsstring[]required

List of permitted payment methods (e.g., CARD, BANK_TRANSFER, CRYPTO)

Possible values: [CARD, BANK_TRANSFER, CRYPTO], >= 1

statusstringrequired

Status of the payment request (e.g., PENDING, PAID, CANCELLED)

Possible values: [PAID, PART_PAID, UNPAID, CANCELLED]

paymentLinkReferencestring

Internal reference ID linking to the payment URL

paymentUrlstring

Public URL where the payer can complete the payment

successRedirectUrlstring

URL to redirect the payer after a successful payment.

Hubpay will append paymentRequestId and paymentId as query parameters to this URL during the redirect flow only — they are not included in the API response payload.

The appended parameters allows your backend to validate the result and retrieve payment details.

cancelRedirectUrlstring

URL to redirect the payer if they cancel the payment

allowPartialPaymentsboolean

Indicates whether partial payments are allowed for this payment request.

If true:

  • The payer will be allowed to enter a custom amount on the hosted payment page
  • Multiple payments can be made until the full amount is settled

If false:

  • The payer will not be prompted to enter an amount on the hosted payment page
  • The full payment amount must be paid in one payment
payoutDetails object

Details for payout to a beneficiary. If this is provided then evey payment made against this request will be paid out to the provided beneficiary

payoutBeneficiaryIduuidrequired

Unique identifier of the payout beneficiary

payoutReferencestringrequired

Reference for the payout, such as an invoice number or transaction ID

Possible values: <= 255 characters

payoutPurposeOfPaymentstringrequired

Purpose of the payout, indicating the reason for the payment to the beneficiary

Possible values: [COMPUTER_SERVICES, FAMILY_SUPPORT, EDUCATION, MEDICAL_TREATMENT, MAINTENANCE_EXPENSES, TRAVEL, SMALL_VALUE_REMITTANCE, CONSTRUCTION_EXPENSES, HOTEL_ACCOMMODATION, ADVERTISING_EXPENSES, ADVISORY_FEES, BUSINESS_INSURANCE, INSURANCE_CLAIMS, DELIVERY_FEES, EXPORTED_GOODS, SERVICE_CHARGES, LOAN_PAYMENT, OFFICE_EXPENSES, PROPERTY_PURCHASE, PROPERTY_RENTAL, ROYALTY_FEES, SHARES_INVESTMENT, FUND_INVESTMENT, TAX_PAYMENT, TRANSPORTATION_FEES, UTILITY_BILLS, PERSONAL_TRANSFER, SALARY_PAYMENT, INFLUENCER_PAYMENT, DIVIDEND_PAYMENT, REWARD_PAYMENT, OTHER_FEES, OTHER]

PaymentRequest
{
  "executionMode": "PAYMENT_LINK",
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "externalId": "string",
  "accountId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "payerId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "receivingCurrencyType": "FIAT",
  "receivingCurrency": "AED",
  "receivingAmount": 150,
  "dueDate": "2024-07-29",
  "documentReference": "string",
  "documentId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "paymentMethods": [
    "CARD"
  ],
  "status": "PAID",
  "paymentLinkReference": "string",
  "paymentUrl": "string",
  "successRedirectUrl": "string",
  "cancelRedirectUrl": "string",
  "allowPartialPayments": true,
  "payoutDetails": {
    "payoutBeneficiaryId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "payoutReference": "string",
    "payoutPurposeOfPayment": "COMPUTER_SERVICES"
  }
}