OneOffPaymentRequest

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/akahu/main/json-schema/akahu-one-off-payment-request-schema.json",
  "title": "OneOffPaymentRequest",
  "description": "A request for payment from the user",
  "x-generated": "2026-10-27",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/akahu-one-off-payments-api-openapi.yml#/components/schemas/OneOffPaymentRequest",
  "type": "object",
  "properties": {
    "payee": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "minLength": 2,
          "maxLength": 70,
          "pattern": "^[A-Za-z0-9 '\\.,&\\-_]*$",
          "description": "The name of the payee"
        },
        "account_number": {
          "$ref": "#/$defs/BankAccountNumber"
        },
        "particulars": {
          "type": "string",
          "maxLength": 12,
          "pattern": "^[A-Za-z0-9 \\-_]*$",
          "description": "The Particulars field that will go on the payee's bank statement"
        },
        "code": {
          "type": "string",
          "maxLength": 12,
          "pattern": "^[A-Za-z0-9 \\-_]*$",
          "description": "The Code field that will go on the payee's bank statement"
        },
        "reference": {
          "type": "string",
          "maxLength": 12,
          "pattern": "^[A-Za-z0-9 \\-_]*$",
          "description": "The Reference field that will go on the payee's bank statement"
        }
      },
      "required": [
        "name",
        "account_number"
      ],
      "description": "The payee's details"
    },
    "payer": {
      "type": "object",
      "properties": {
        "bank": {
          "$ref": "#/$defs/OneOffPaymentBank"
        },
        "name": {
          "type": "string",
          "minLength": 2,
          "maxLength": 70,
          "pattern": "^[A-Za-z0-9 '\\.,&\\-_]*$",
          "description": "The name of the payer"
        },
        "account_number": {
          "allOf": [
            {
              "$ref": "#/$defs/BankAccountNumber"
            },
            {
              "description": "The bank account number of the payer"
            }
          ]
        },
        "release_account_details": {
          "type": "boolean",
          "default": false,
          "description": "Request that the bank releases the payer's account details. These details will be populated in the `payer.name` and `payer.account_number` fields of the payment once available. Payer account release cannot be requested when the payer account number is specified as part of the initial payment request."
        },
        "particulars": {
          "type": "string",
          "maxLength": 12,
          "pattern": "^[A-Za-z0-9 \\-_]*$",
          "description": "The Particulars field that will go on the payer's bank statement"
        },
        "code": {
          "type": "string",
          "maxLength": 12,
          "pattern": "^[A-Za-z0-9 \\-_]*$",
          "description": "The Code field that will go on the payer's bank statement"
        },
        "reference": {
          "type": "string",
          "maxLength": 12,
          "pattern": "^[A-Za-z0-9 \\-_]*$",
          "description": "The Reference field that will go on the payer's bank statement"
        }
      },
      "description": "The payer's details"
    },
    "amount": {
      "type": "number",
      "minimum": 0.01,
      "maximum": 1000000,
      "description": "The amount to be paid in dollars, e.g. 12.34. (Rounded to 2 decimal places)."
    },
    "redirect_uri": {
      "type": "string",
      "format": "uri",
      "description": "The URI to redirect the user to after payment approval"
    },
    "redirect_mode": {
      "$ref": "#/$defs/OneOffPaymentRedirectMode"
    },
    "webhook_uri": {
      "type": "string",
      "format": "uri",
      "description": "The URI to send webhooks regarding updates to this payment"
    },
    "expires_at": {
      "type": "string",
      "format": "date-time",
      "description": "The payment will be cancelled at this time, unless it has been authorised. Defaults to 1 hour in the future."
    }
  },
  "required": [
    "payee",
    "amount",
    "redirect_uri"
  ],
  "$defs": {
    "BankAccountNumber": {
      "type": "string",
      "pattern": "^\\d{2}-\\d{4}-\\d{7}-\\d{2,3}$",
      "description": "The bank account number of the payee"
    },
    "OneOffPaymentBank": {
      "type": "string",
      "enum": [
        "anz",
        "asb",
        "bnz",
        "kiwibank",
        "nzhl",
        "westpac",
        "demo_bank"
      ],
      "description": "The bank the customer must use to make this payment"
    },
    "OneOffPaymentRedirectMode": {
      "type": "string",
      "enum": [
        "deep_link"
      ],
      "description": "The mode used by Akahu when redirecting the user to your provided `redirect_uri`.\nThis option is important for native mobile app developers.\n - `deep_link` → Specify this value if your provided `redirect_uri` intends to activate your native mobile application via iOS [universal link](https://developer.apple.com/documentation/xcode/allowing-apps-and-websites-to-link-to-your-content/) or Android [app link](https://developer.android.com/training/app-links/about). When you supply this value, the user will be required to tap to confirm before returning to your application. This interaction is important to ensure successful native app activation."
    }
  }
}