PaymentRequest

Details of a payment request

executionModestringrequired

How the payer completes the payment: PAYMENT_LINK is shareable, HOSTED_PAGE is a standalone Hubpay page, and EMBEDDED is compact checkout contained in a website iframe or direct native WebView

Possible values: [PAYMENT_LINK, HOSTED_PAGE, EMBEDDED]

idstring<uuid>required

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

accountIdstring<uuid>required

Unique identifier of the account associated with this payment request

payerIdstring<uuid>required

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

dueDatestring<date>

Optional due date by which the payment should be made

expiresAt(string | null)<date-time>nullable

The deadline for a HOSTED_PAGE or EMBEDDED payment request, set to 60 minutes after the request is created. The request normally expires at this time, but the two cases below can make it expire earlier or later. Null for PAYMENT_LINK requests, which never expire.

The payer can start a payment until 15 minutes before this time. If the payer has not taken a quote or started a card or bank payment by then, the request expires at that earlier time.

At this time, a request that is still UNPAID or PART_PAID becomes EXPIRED and the payment_request.expired webhook is sent. One exception: if a crypto deposit was sent in time and is still confirming, the request stays open until the deposit settles. It then becomes PAID if the deposit covers the full amount, or EXPIRED if it does not.

Example: 2026-09-15T11:00:00Z

documentReferencestringrequired

Document reference such as an invoice number or PO reference

Possible values: non-empty

documentIdstring<uuid>

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, EXPIRED]

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 the payer is returned to when they cancel or leave the payment page, or when a hosted payment request expires unpaid. Arrival is not proof of cancellation; verify the request status via webhook or API.

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

payoutBeneficiaryIdstring<uuid>required

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 [

idstring<uuid>

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

sendCurrencystring

Currency the payer sends in (crypto code for crypto payments, fiat code for card/bank)

Example: USDT

sendAmountnumber

Amount the payer sends, in sendCurrency

Example: 272.48

receiveCurrencystring

Currency the merchant receives in

Example: AED

receiveAmountnumber

Amount the merchant receives, in receiveCurrency

Example: 1000

methodstring

Payment method used for the transaction

Possible values: [CARD, BANK_TRANSFER, CRYPTO]

Example: BANK_TRANSFER

accountIdstring<uuid>

Unique identifier for the account

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

payerIdstring<uuid>

Unique identifier for the payer

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

paymentRequestIdstring<uuid>

Unique identifier for the payment request

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

createdAtstring<date-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

Card details

issuerstring

Card issuer

issuerCountrystring

Country of the card issuer

schemestring

Card scheme

Example: VISA

cardTypestring

Card type

Example: CREDIT

last4string

Crypto details

transactionHashstring

Transaction hash for the crypto payment

Example: 0x5c69bee701ef814a2b6a3f8d1e4f7b8c9e1f5c6d7e8f9a0b1c2d3e4f5g6h7i8j

Bank transfer details

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

beneficiaryIdstring<uuid>

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",
  "expiresAt": "2026-09-15T11:00:00Z",
  "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",
      "sendCurrency": "USDT",
      "sendAmount": 272.48,
      "receiveCurrency": "AED",
      "receiveAmount": 1000,
      "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"
      }
    }
  ]
}