Skip to main content

PaymentRequestCreateRequest

Payload for creating a new payment request

executionModestringrequired

Specifies how the payer is expected to complete the payment request

Possible values: [PAYMENT_LINK, HOSTED_PAGE]

externalIdstringrequired

Client-provided identifier for idempotency or external tracking

Possible values: <= 255 characters

Example: REQ-123456
payerIduuidrequired

Unique identifier of the payer

Example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
receivingCurrencyTypestringrequired

Specifies if the payment will be made using FIAT or CRYPTO

Possible values: [FIAT, CRYPTO]

receivingCurrencystringrequired

ISO 4217 or crypto currency code for settlement

Possible values: <= 5 characters, Value must match regular expression [A-Z]{3,5}

Example: AED
receivingAmountnumberrequired

Amount expected to be received

Example: 99.99
dueDatedate

Optional due date for the payment to be completed

Example: 2025-06-30
documentReferencestringrequired

Document reference such as an invoice or PO number

Possible values: <= 255 characters

Example: INV-2025-001
documentIduuidrequired

UUID of the uploaded document associated with this payment

Example: 123e4567-e89b-12d3-a456-426614174000
paymentMethodsstring[]required

List of accepted payment methods for the payer

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

Example: ["CARD","CRYPTO"]
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.

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

Possible values: <= 255 characters

Example: https://example.com/success
cancelRedirectUrlstring

URL to redirect the user after payment cancellation

Possible values: <= 255 characters

Example: https://example.com/cancel
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 or omitted:

  • 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
Default value: false
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. Omit this object to have funds settled to your Hubpay wallet.

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]

PaymentRequestCreateRequest
{
"executionMode": "PAYMENT_LINK",
"externalId": "REQ-123456",
"payerId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"receivingCurrencyType": "FIAT",
"receivingCurrency": "AED",
"receivingAmount": 99.99,
"dueDate": "2025-06-30",
"documentReference": "INV-2025-001",
"documentId": "123e4567-e89b-12d3-a456-426614174000",
"paymentMethods": [
"CARD",
"CRYPTO"
],
"successRedirectUrl": "https://example.com/success",
"cancelRedirectUrl": "https://example.com/cancel",
"allowPartialPayments": false,
"payoutDetails": {
"payoutBeneficiaryId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"payoutReference": "string",
"payoutPurposeOfPayment": "COMPUTER_SERVICES"
}
}