PaymentInitiationObj

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/azupay/main/json-schema/azupay-payment-initiation-obj-schema.json",
  "title": "PaymentInitiationObj",
  "x-generated": "2026-10-12",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/azupay-payment-initiation-api-openapi.yml#/components/schemas/PaymentInitiationObj",
  "type": "object",
  "required": [
    "PaymentInitiation"
  ],
  "additionalProperties": false,
  "properties": {
    "PaymentInitiation": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "clientId",
        "paymentAgreementId",
        "paymentAmount",
        "clientTransactionId"
      ],
      "properties": {
        "paymentAgreementId": {
          "type": "string",
          "description": "ID of the payment agreement to initiate payment"
        },
        "paymentRequestId": {
          "type": "string",
          "minLength": 32,
          "maxLength": 32,
          "pattern": "^[A-Z|a-z|0-9]*$"
        },
        "metaData": {
          "type": "object",
          "additionalProperties": true,
          "description": "An object containing no more than 10 string fields. Where the field name is limited to 40 ASCII characters and the field value is limited to 255 ASCII characters"
        },
        "clientTransactionId": {
          "$ref": "#/$defs/ClientTransactionIdObj"
        },
        "clientId": {
          "$ref": "#/$defs/ClientIdObj"
        },
        "paymentAmount": {
          "$ref": "#/$defs/PayToAmountObj"
        },
        "reference": {
          "type": "string",
          "minLength": 1,
          "maxLength": 35,
          "pattern": "^[ -~]*$",
          "description": "Unique identification to unambiguously identify the transaction. \nThis identification is passed on, unchanged, throughout the entire end-to-end payment message, \nand will appear on payers statements.\n"
        },
        "description": {
          "type": "string",
          "minLength": 5,
          "maxLength": 280,
          "description": "Optional remittance information used to unambiguously refer to the payment transaction."
        },
        "paymentInitiationNotification": {
          "$ref": "#/$defs/NotificationObj"
        },
        "additionalDetails": {
          "$ref": "#/$defs/AdditionalDetailsObj"
        }
      }
    }
  },
  "$defs": {
    "AdditionalDetailsObj": {
      "type": "object",
      "required": [
        "customerNumber",
        "userID",
        "authMethod",
        "channelType"
      ],
      "description": "Additional details for auditing purposes",
      "properties": {
        "customerNumber": {
          "type": "string",
          "description": "Uniquely identifies the Customer for whom the request has been initiated for. i.e. the Customer  that owns the account. This field should contain the Member Number or Customer Number from the  Client's banking system.\n",
          "maxLength": 25
        },
        "userID": {
          "type": "string",
          "description": "Uniquely identifies the User that has initiated the request. This could be the Customer or someone  authorised to act on behalf of the Customer.\n",
          "maxLength": 25
        },
        "authMethod": {
          "type": "string",
          "description": "This field allows us to understand how the user has logged in. Over a period we can determine if  there is a deviation from normal usage patterns. e.g. Moving from biometric to PIN and linking that  with payments we can detect fraud happening but also apply other rules to understand if PayIds are  being from a device for malicious intent.\n",
          "enum": [
            "2FACTOR",
            "OTP",
            "BIOMETRIC",
            "PASSWORD",
            "PIN",
            "NONE"
          ]
        },
        "channelType": {
          "type": "string",
          "description": "This field allows us to understand, similar to authenticationMethod, which channels are being used  to initiate a request. If `BROWSER` or `MOBILE` is selected. `ipAddress` and `deviceFingerprint`  will be required fields.\n",
          "enum": [
            "BROWSER",
            "MOBILE",
            "BRANCH",
            "IVR",
            "OTHER"
          ]
        },
        "ipAddress": {
          "type": "string",
          "description": "IP address of the device or computer from which the user request originated. Required if request  originated from a browser or mobile, else do not send.\n"
        },
        "fraudScore": {
          "type": "string",
          "description": "This is a fraud score you may have calculated. if not, do not send."
        },
        "deviceFingerprint": {
          "type": "string",
          "description": "The device fingerprint or browser fingerprint. A change in device is a possible indicator of  fraud/ID takeover/phone number porting. The device fingerprint, machine fingerprint or browser  fingerprint. Required if the request originated from a web browser or mobile device, else do not  send.\n"
        },
        "notes": {
          "type": "string",
          "description": "Free text field up to 2048 characters.",
          "maxLength": 2048
        },
        "geoLocation": {
          "type": "string",
          "description": "Latitude and Longitude from which the user request originated. For example  -33.8708464,151.20732999999998 Only to be provided if GPS is enabled on the device, else do not  send.\n",
          "maxLength": 50
        }
      }
    },
    "ClientIdObj": {
      "type": "string",
      "description": "Id of the client initiating the transaction. This is supplied by Azupay and only changes between environments.\nFor example, you might be allocated CLIENT1TEST for the UAT environment and CLIENT1 for production.\n",
      "minLength": 5,
      "maxLength": 50
    },
    "ClientTransactionIdObj": {
      "description": "Unique Id for the transaction created by the merchant system\n\nThis field is used to prevent the creation of duplicated clients in case of a message retry. It is\nrecommended that a unique id (like uuid) is used for each client. If the same value is used a second time\nthe client will be replaced.\n",
      "minLength": 5,
      "maxLength": 100,
      "type": "string"
    },
    "NotificationObj": {
      "type": "object",
      "description": "Merchant Callback Details",
      "required": [
        "endpointURL",
        "authorizationHeader"
      ],
      "properties": {
        "endpointURL": {
          "$ref": "#/$defs/endpointURL"
        },
        "authorizationHeader": {
          "$ref": "#/$defs/authorizationHeader"
        }
      }
    },
    "PayToAmountObj": {
      "type": "string",
      "pattern": "^[0-9]+(\\.[0-9]{2})$",
      "description": "Amount in AUD to be requested from the Payee"
    },
    "authorizationHeader": {
      "type": "string",
      "description": "The string that Azupay will put into the Authorization request header when calling the Callback url.\n\nWill be obfuscated (shown as ****) in API responses.\n"
    },
    "endpointURL": {
      "type": "string",
      "format": "url",
      "description": "An internet accessible url which Azupay will invoke when the status of the transaction has \nchanged. The call will be done using the HTTP POST method. The endpoint exposed by the client \nmust be TLS 1.2 and the server certificate must be issued by a well known commercial certificate \nauthority and that self-signed or internally signed certs are not acceptable.\n"
    }
  }
}