Payment requests
Parameter reference for creating payment requests.
Body parameters
| Field | Required | Default | Description |
|---|---|---|---|
bank_account_id | Yes | — | ID of the bank account that will receive funds. Must be verified — list your accounts via the API. |
amount | Yes* | — | Requested amount as a currency string, e.g. "10.00 NZD". *Not required for recurring requests, where the amount is governed by recurring_options. |
message | Yes | — | Short description shown to the customer explaining what they're paying for. Max 180 characters. |
type | No | single | single for one-off payments, multi for reusable requests. Recurring requests must use single. |
reference | No | — | Free-text reference on the customer's and your bank statement. Max 12 chars, [a-zA-Z0-9-]. |
merchant_identifier | No | — | Free-text identifier for your own reconciliation. Inherited by all payments from this request. |
merchant_customer_identifier | No | — | Stable identifier for a known customer in your system (e.g. a hashed user ID). Enables repeat-payment detection. |
expires_in | No | — | Duration string (e.g. "10m", "1h") after which the request expires. If omitted, the request never expires. |
allow_dynamic_amount | No | false | If true, customers self-select the amount they pay and amount is ignored. |
min_payment_amount | No | 100 | Minimum dynamic amount in cents. Only relevant when allow_dynamic_amount is true. |
max_payment_amount | No | — | Maximum dynamic amount in cents. Required when allow_dynamic_amount is true. |
require_customer_basic_info | No | false | Require the customer to provide email and name before payment. |
collect_customer_phone | No | false | Allow the customer to optionally provide their phone number. |
require_customer_phone | No | false | Require a phone number before payment. |
require_customer_address | No | false | Require an address before payment. |
success_redirect_url | No | — | URL to redirect to after successful payment. Host must be configured in Domains settings. |
failure_redirect_url | No | — | URL to redirect to after failed payment. Host must be configured in Domains settings. |
recurring_options | No | — | Recurring payment limits. See Recurring options. |
cust_info | No | — | Customer identification. Required for recurring requests, where at minimum an email must be provided. See Customer info. |
options.generate_qr_code | No | false | If true, the response includes a QR code data URL as request.qr_data. |
Recurring options
Constraints that limit the type and frequency of payments made after a customer authorises a recurring request.
| Field | Required | Description |
|---|---|---|
period | Yes | Window over which the period limit applies. One of daily, weekly, monthly. |
max_per_period | Yes | Maximum total charge across the period, e.g. "50.00 NZD" for a monthly period means no more than $50/month. |
max_per_payment | No | Maximum charge for any single payment. Set this equal to max_per_period for a fixed subscription. |
total_count | No | Cap on the total number of payments across the life of the consent (e.g. 6 instalments). |
total_amount | No | Cap on the total value of all payments across the life of the consent. |
end_date | No | Date after which no further payments can be taken. |
Customer info
Customer identification details supplied when creating a payment request. Required for recurring requests, where at minimum an email must be provided.
| Field | Description |
|---|---|
email | Customer email address. |
first_name | Customer first name. |
last_name | Customer last name. |
phone | Customer phone number. |