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

currencystringrequired

Three-letter ISO or crypto currency code for settlement

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

Example: AED

amountnumberrequired

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 when they have successfully completed their payment journey.

Important: This redirect does NOT confirm that funds have been received. For asynchronous payment methods like bank transfers, the payer may have successfully submitted payment instructions, but funds may not yet be received by Hubpay.

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

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.

cancelRedirectUrlstring

URL to redirect the payer if they cancel the payment

autoSendPaymentLinkboolean

Whether the payment link was automatically sent to the payer's email address upon creation

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]

amountPaidnumber

Total amount paid against this payment request

Example: 50

amountRemainingnumber

Remaining amount to be paid

Example: 100

payments object[]

List of payments made against this payment request

Array [

iduuid

Unique identifier for the payment

Example: 123e4567-e89b-12d3-a456-426614174000

referencestring

Reference for the payment

Example: REF123

statusstring

Status of the payment

Possible values: [CREATED, PENDING, RECEIVED, COMPLETE, FAILED, REVERSED]

Example: PENDING

paymentSymbolstring

Currency in which the payment is made

Example: AED

paymentAmountnumber

Amount to be paid

Example: 100

currencystring

Currency in which the payment is received

Example: GBP

amountnumber

Amount received after conversion

Example: 75

methodstring

Payment method used for the transaction

Possible values: [CARD, BANK_TRANSFER, CRYPTO]

Example: BANK_TRANSFER

accountIduuid

Unique identifier for the account

Example: 123e4567-e89b-12d3-a456-426614174004

payerIduuid

Unique identifier for the payer

Example: 123e4567-e89b-12d3-a456-426614174001

paymentRequestIduuid

Unique identifier for the payment request

Example: 123e4567-e89b-12d3-a456-426614174002

createdAtdate-time

Timestamp when the payment was created

Example: 2023-10-01T12:00:00Z

details object

Details depending on payment method

type

Details depending on payment method

Possible values: [PaymentRequestCardPayment, PaymentRequestCryptoPayment, PaymentRequestBankTransferPayment]

PaymentRequestCardPayment
PaymentRequestCryptoPayment
PaymentRequestBankTransferPayment

issuerstring

Card issuer

issuerCountrystring

Country of the card issuer

schemestring

Card scheme

Example: VISA

cardTypestring

Card type

Example: CREDIT

last4string

exchangeRatenumber

Exchange rate at the time of payment

Example: 1.25

depositAddressstring

Deposit address for the crypto payment

Example: 1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa

transactionHashstring

Transaction hash for the crypto payment

Example: 0x5c69bee701ef814a2b6a3f8d1e4f7b8c9e1f5c6d7e8f9a0b1c2d3e4f5g6h7i8j

bankReferencestring

Bank reference number for the payment

Example: 123456789

senderAccountNumberstring

Sender's account number

Example: GB29NWBK60161331926819

senderNamestring

Sender's name

Example: John Doe

payout object

beneficiaryIduuid

referencestring

transactionReferencestring

purposeOfPaymentstring

amountnumber

currencystring

statusstring

Status of a payment payout during its lifecycle.

Possible values: [PENDING_APPROVAL, INITIATED, PAID, FAILED]

]

PaymentRequest
{
  "executionMode": "PAYMENT_LINK",
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "externalId": "string",
  "accountId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "payerId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "currency": "AED",
  "amount": 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",
  "autoSendPaymentLink": true,
  "payoutDetails": {
    "payoutBeneficiaryId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "payoutReference": "string",
    "payoutPurposeOfPayment": "COMPUTER_SERVICES"
  },
  "amountPaid": 50,
  "amountRemaining": 100,
  "payments": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "reference": "REF123",
      "status": "PENDING",
      "paymentSymbol": "AED",
      "paymentAmount": 100,
      "currency": "GBP",
      "amount": 75,
      "method": "BANK_TRANSFER",
      "accountId": "123e4567-e89b-12d3-a456-426614174004",
      "payerId": "123e4567-e89b-12d3-a456-426614174001",
      "paymentRequestId": "123e4567-e89b-12d3-a456-426614174002",
      "createdAt": "2023-10-01T12:00:00Z",
      "details": {
        "issuer": "string",
        "issuerCountry": "string",
        "scheme": "VISA",
        "cardType": "CREDIT",
        "last4": "string"
      },
      "payout": {
        "beneficiaryId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "reference": "string",
        "transactionReference": "string",
        "purposeOfPayment": "COMPUTER_SERVICES",
        "amount": 0,
        "currency": "string",
        "status": "PENDING_APPROVAL"
      }
    }
  ]
}