PaymentRequestObj

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/azupay/main/json-schema/azupay-payment-request-obj-schema.json",
  "title": "PaymentRequestObj",
  "x-generated": "2026-10-12",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/azupay-payment-request-api-openapi.yml#/components/schemas/PaymentRequestObj",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "PaymentRequest"
  ],
  "properties": {
    "PaymentRequest": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "clientId",
        "clientTransactionId",
        "paymentDescription"
      ],
      "properties": {
        "payID": {
          "type": "string",
          "minLength": 5,
          "maxLength": 50,
          "description": "Unique email PayID for this transaction. Value supplied here is the PayID used by your customer to make payment. If not supplied, Azupay will generate one automatically. The PayID's domain must match one of the configured domains for the client.",
          "pattern": "^([a-z0-9_\\-\\.]+)@([a-z0-9_\\-\\.]+)\\.([a-z]+)$"
        },
        "payIDSuffix": {
          "type": "string",
          "minLength": 5,
          "maxLength": 50,
          "description": "The email domain to use when Azupay generates the PayID. All domains must be validated and preconfigured by Azupay before they can be used. If supplied value is not configured an error is returned. If a PayID is supplied this value is ignored. If not supplied the default email domain configured in the system is used."
        },
        "clientId": {
          "type": "string",
          "minLength": 5,
          "maxLength": 50,
          "description": "Id of the client creating the request for payment. This is supplied by Azupay and only changes between environments. For example, you might be allocated CLIENT1TEST for the UAT environment and CLIENT1 for production."
        },
        "suggestedPayerDetails": {
          "$ref": "#/$defs/suggestedPayerDetailsObj"
        },
        "clientBranch": {
          "$ref": "#/$defs/clientBranch"
        },
        "clientTransactionId": {
          "type": "string",
          "minLength": 3,
          "maxLength": 100,
          "description": "Unique Id for the transaction created by the merchant system"
        },
        "multiPayment": {
          "description": "When set to true and a paymentAmount has been set, we will allow multiple payments to be made to the PayID, up to the value of the paymentAmount. When set to false and a paymentAmount has not been set, the PayID can accept any number of payments for any amount. A refund will be issued automatically if a payment exceeds this amount.                 If multiPayment has not been set, the default is false.",
          "type": "boolean"
        },
        "metaData": {
          "type": "object",
          "additionalProperties": true,
          "description": "An object containing metadata about payment request."
        },
        "payerNotificationEmail": {
          "description": "Customer/Payer Email address to notify based on client configuration.",
          "maxLength": 140,
          "type": "string",
          "format": "email"
        },
        "payerNotificationMobile": {
          "description": "Customer/Payer mobile number to notify based on client configuration. Must start with +61.",
          "maxLength": 20,
          "type": "string"
        },
        "paymentAmount": {
          "type": "number",
          "description": "Amount in AUD requested to pay for the transaction. Not mandatory if multiPayment is true. If multiPayment is true then it can be set to accept adhoc payments up to this amount.",
          "minimum": 0.01,
          "multipleOf": 0.01
        },
        "paymentDescription": {
          "type": "string",
          "minLength": 5,
          "maxLength": 140,
          "description": "Description of this transaction. It will be the last part of the PayID name that appears in the customer's online banking when they lookup the PayID. Must not contain any of the customer's personal information.\nThis description could be truncated to accommodate a maximum of 140 characters allowed on a PayID name so it is \nrecommended not to exceed 110 characters.\n"
        },
        "enableVirtualAccount": {
          "type": "boolean",
          "description": "Enable virtual account for this payment request. This field is only applied if your client is configured to support virtual accounts."
        },
        "paymentExpiryDatetime": {
          "type": "string",
          "format": "date-time",
          "description": "Timestamp when the payment request expires and is no longer able to accept payments. The associated PayID is also de-registered within 48 hours of the specified time."
        },
        "checkoutUrl": {
          "description": "Share this url with your customer to request payment using a web interface and qr code. You can enable this feature by going to Azupay Client Dashboard > Apps and enabling the Checkout Web App.",
          "type": "string",
          "readOnly": true,
          "format": "url"
        },
        "paymentNotification": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "paymentNotificationEndpointUrl": {
              "description": "An internet accessible url which azupay will invoke when the status of an inflight PaymentRequest has reached either \"COMPLETED\", \"FAILED\" or \"RETURNED\" status. The call will be done using the HTTP POST verb. The url should end in /paymentRequestStatus. The endpoint exposed by the client must be TLS 1.2 and the server certificate must be issued by a well known commercial certificate authority and that self-signed or internally signed certs are not acceptable.",
              "type": "string",
              "format": "url"
            },
            "paymentNotificationAuthorizationHeaderValue": {
              "description": "The string that azupay will put into the Authorization request header when making the paymentNotification call.",
              "type": "string"
            }
          }
        },
        "lineItems": {
          "description": "An array of line items associated with the current payment request",
          "type": "array",
          "items": {}
        },
        "ultimatePayeeName": {
          "type": "string",
          "minLength": 1,
          "maxLength": 140,
          "pattern": "^[a-zA-Z0-9\\-_ ]*$",
          "description": "Used for specifying the name of the sub merchant for whom you are creating the PaymentRequest for."
        },
        "variant": {
          "type": "string",
          "minLength": 1,
          "maxLength": 50,
          "description": "The Variant field will determine the type of checkoutURL in the response.</br>\nFor users who are not using Azupay UX, this field is optional and does not need to be provided.</br>\nIf the field is set to PayID, the checkoutURL will have the Payment Request - PayID App.</br>\nIf the field is set to 1Click, the checkoutURL will have the Payment Request - 1 Click App.</br>\n"
        },
        "suggestedPayerPayID": {
          "$ref": "#/$defs/SuggestedPayerPayIDObj"
        },
        "recurringPaymentAmount": {
          "type": "number",
          "description": "Amount in AUD for recurring payments. Must be provided along with `recurringPaymentFrequency` \nand `paymentAmount` fields for recurring payment requests.\nThis field applies only when the Checkout\nApp V3 is enabled with payTo. Go to Dashboard -> Apps -> Checkout and enable V3 with PayId+PayTO.\nWhen this field is provided the Checkout App will create a PaymentAgreement with an initialPayment amount\ncorresponding to the `paymentAmount` and an amount corresponding to `recurringPaymentAmount` with frequency\nof `recurringPaymentFrequency`. You can obtain the `paymentAgreementId` from the `PaymentRequestStatus`\nto collect the recurring payments later.\n",
          "minimum": 0.01,
          "multipleOf": 0.01
        },
        "recurringPaymentFrequency": {
          "type": "string",
          "description": "Frequency for recurring payments. Must be provided along with `recurringPaymentAmount` \nand and `paymentAmount` fields. This field applies only when the Checkout\nApp V3 is enabled with payTo. Go to Dashboard -> Apps -> Checkout and enable V3 with PayId+PayTO\n",
          "enum": [
            "FORTNIGHTLY",
            "SEMIANNUAL",
            "MONTHLY",
            "QUARTERLY",
            "WEEKLY",
            "ANNUAL",
            "ADHOC",
            "DAILY"
          ]
        },
        "recurringPaymentType": {
          "type": "string",
          "description": "Type of recurring payment agreement. FIXED means exact recurring amount (default behavior),\nVARIABLE means maximum recurring amount cap. When VARIABLE, the recurringPaymentAmount\nrepresents the maximum amount that can be charged, and paymentAmount (initial payment)\nmust not exceed this maximum. Defaults to FIXED if not specified.\n",
          "enum": [
            "FIXED",
            "VARIABLE"
          ]
        },
        "recurringPaymentEndDate": {
          "type": "string",
          "description": "Optional end date for the recurring payment agreement in YYYY-MM-DD format.\nMust be at least current date + 1 day (Australia/Sydney timezone).\nApplies to both FIXED and VARIABLE agreement types.\nEnables automatic agreement expiration without manual intervention.\n",
          "pattern": "^(?:[1-9]\\d{3}-(?:(?:0[1-9]|1[0-2])-(?:0[1-9]|1\\d|2[0-8])|(?:0[13-9]|1[0-2])-(?:29|30)|(?:0[13578]|1[02])-31)|(?:[1-9]\\d(?:0[48]|[2468][048]|[13579][26])|(?:[2468][048]|[13579][26])00)-02-29)$"
        }
      }
    }
  },
  "$defs": {
    "AccountNameObj": {
      "type": "string",
      "description": "The Account Name",
      "minLength": 1,
      "maxLength": 100,
      "pattern": "[^\\x00-\\x1F\\x7F]+"
    },
    "AccountNumberObj": {
      "type": "string",
      "description": "The Account Number (without the BSB)",
      "minLength": 4,
      "maxLength": 9,
      "pattern": "^\\d*$"
    },
    "BsbObj": {
      "type": "string",
      "description": "The BSB of the account number",
      "minLength": 6,
      "maxLength": 6,
      "pattern": "^\\d*$"
    },
    "PayerPayIDObj": {
      "type": "string",
      "minLength": 1,
      "maxLength": 140,
      "description": "The payer's PayID. Valid examples are `0432123321` (mobile) and `jane.smith@example.com` (email).\n"
    },
    "SuggestedPayerPayIDObj": {
      "type": "string",
      "minLength": 1,
      "maxLength": 140,
      "description": "Note `SuggestedPayerPayID` has been deprecated and replaced by `SuggestedPayerDetails`.\nThe payer's PayID. Valid examples are `0432123321` (mobile) and `jane.smith@example.com` (email).\nUse this field to pre-populate the payID that gets entered within a 1Click transaction.\nThis can only be used with a payment request with the variant 1Click.\n"
    },
    "clientBranch": {
      "type": "string",
      "minLength": 5,
      "maxLength": 50,
      "description": "Optional branch identifier within the client"
    },
    "suggestedPayerDetailsObj": {
      "type": "object",
      "additionalProperties": false,
      "description": "Payer details to pre-populate the UI. Only one of `payIDDetails` or `bankAccountDetails` allowed.\n",
      "properties": {
        "payIDDetails": {
          "type": "object",
          "description": "PayID Details",
          "additionalProperties": false,
          "required": [
            "payID"
          ],
          "properties": {
            "payID": {
              "$ref": "#/$defs/PayerPayIDObj"
            }
          }
        },
        "bankAccountDetails": {
          "description": "Bank Account Details",
          "additionalProperties": false,
          "type": "object",
          "properties": {
            "bsb": {
              "$ref": "#/$defs/BsbObj"
            },
            "accountNumber": {
              "$ref": "#/$defs/AccountNumberObj"
            },
            "accountName": {
              "$ref": "#/$defs/AccountNameObj"
            }
          }
        }
      }
    }
  }
}