OneOffPayment

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/akahu/main/json-schema/akahu-one-off-payment-schema.json",
  "title": "OneOffPayment",
  "description": "The current state of a payment",
  "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/OneOffPayment",
  "type": "object",
  "properties": {
    "_id": {
      "$ref": "#/$defs/OneOffPaymentId"
    },
    "status": {
      "$ref": "#/$defs/OneOffPaymentStatus"
    },
    "status_reason": {
      "type": "object",
      "properties": {
        "code": {
          "$ref": "#/$defs/OneOffPaymentStatusCode"
        },
        "message": {
          "type": "string",
          "description": "A human readable message about the status"
        }
      },
      "required": [
        "code",
        "message"
      ],
      "description": "If applicable, more details about the payment status"
    },
    "created_at": {
      "type": "string",
      "format": "date-time",
      "description": "When the payment was created"
    },
    "updated_at": {
      "type": "string",
      "format": "date-time",
      "description": "When the payment was last updated"
    },
    "expires_at": {
      "type": "string",
      "format": "date-time",
      "description": "The payment will be cancelled at this time, unless it has been authorised"
    },
    "submitted_at": {
      "type": "string",
      "format": "date-time",
      "description": "When the payment was submitted"
    },
    "terminal_at": {
      "type": "string",
      "format": "date-time",
      "description": "When the payment reached a terminal status"
    },
    "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",
          "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"
    }
  },
  "required": [
    "_id",
    "status",
    "created_at",
    "updated_at",
    "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"
    },
    "OneOffPaymentId": {
      "type": "string",
      "pattern": "^one_off_payment_[a-z0-9]{25,27}$"
    },
    "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."
    },
    "OneOffPaymentStatus": {
      "type": "string",
      "enum": [
        "READY",
        "AUTHORISED",
        "SUBMITTED",
        "SENT",
        "CANCELLED",
        "FAILED"
      ],
      "description": "The status of the payment"
    },
    "OneOffPaymentStatusCode": {
      "type": "string",
      "enum": [
        "PENDING",
        "SETTLEMENT_IN_PROGRESS",
        "INTERNAL_ERROR",
        "BANK_ERROR",
        "BANK_ERROR_INDETERMINATE",
        "REJECTED",
        "TIMED_OUT",
        "USER_CANCELLED",
        "APP_CANCELLED"
      ],
      "description": "A more specific code for the payment status"
    }
  }
}