One-off Payments

With a one-off payment requests, your customers approve each payment in their bank app on their mobile device. One-off payments are perfect when you need to collect a payment from a customer for a specific transaction, like an invoice.

When you create a one-off payment request, Volley generates a secure payment URL that you can share with your customer. If the customer decides to accept your request, Volley will take care of redirecting them securely to their banking app to approve the payment.

With one-off payments, Volley only receives temporary, single-use access to execute the specific payment amount that was approved. After the payment goes through there's no ongoing access to the customer's account whatsoever.

One-off Types

One-off payment requests can be configured for single or multiple payments.

Single Payments (using type: "single") can only be paid once and ideal for a specific transaction, e.g. an e-commerce purchase or cart checkout, invoices, ticket purchases. The payment request is marked as paid once a payment has been made and cannot be re-used.

Multi payments (using type: “multi”) can be paid multiple times, even by different customers, great for donation links or crowdfunding. Each payment is still an individual one-off transaction, but the payment request remains active and more payments can be made.

Making a One-off Payment Request

You can create a one-off payment request by calling the POST /requests endpoint:

Request

// POST https://api.volley.nz/v1/requests
{
  "bank_account_id": "bankaccount_ZYm2YeJXZ8Vzx3jjMLyp6", // The account which you'll be paid into
  "amount": "1000.00 NZD",     // Fixed amount up to a maximum of $5000.00
  "message": "Invoice #1234",  // A short message to describe the payment 
  "type": "single",            // "single" for one payment, "multi" for multiple payments
  "reference": "INV-1234-AB",  // Reference for bank statement, see PCR Fields
  "merchant_identifier": "..." // A unique identifier matching this request to a record in your system
}

Response

{
  "request": {
    "id": "request_qTVSdEszuE9jfpTQaJ3j7",
    "type": "single",
    "status": "active",
    "bank_account_id": "bankaccount_ZYm2YeJXZ8Vzx3jjMLyp6",
    "url": "https://app.volley.nz/pay/qTVSdEszuE9jfpTQaJ3j7",
    "message": "Invoice #1234",
    "merchant_identifier": "...",
    "pcr": {
      "reference": "ABC12345678"
    },
    "amount": {
      "formatted": "$1000.00",
      "value": "1000.00 NZD"
    },
    "allow_dynamic_amount": false,
    "min_payment_amount": 50,
    "max_payment_amount": 500000,
    "collect_customer_phone": false,
    "require_customer_phone": false,
    "require_customer_basic_info": false,
    "require_customer_address": false,
    "allow_marketing_opt_in": false,
    "is_test_mode": false,
    "logo_image_url": "https://images.volley.nz/volley-logo.png",
    "user_id": "user_PB3CbjbM8xdCNALUlC5JQ",
    "created_at": "2025-08-13T11:09:00Z",
    "updated_at": "2025-08-13T11:09:01Z",
    "expires_at": "2025-08-13T11:14:00Z"
  }
}

Payment Limits

One-off payment requests support payments up to $5,000 NZD each.

Dynamic Amounts

One-off payment requests can be configured to have a dynamic amount. This allows the customer to choose how much they want to pay. Volley will automatically populate the “quick” options based on your minimum and maximum amounts.

Request

// POST https://api.volley.nz/v1/requests
{
  "bank_account_id": "bankaccount_ZYm2YeJXZ8Vzx3jjMLyp6",
  "message": "Invoice #1234",
  "type": "single",          
  allow_dynamic_amount: true,
  minimum_payment_amount: 100, // $1.00 NZD
  maximum_payment_amount: 5000 // $50.00 NZD
}