Payment requests

The core model of Volley's API is the payment request. You can create a request for your customers to pay you which they can approve with their bank app. Our API makes it simple to define the bank account you want to be paid to, the amount to pay, reference details for the bank statement, and a message to help customers see what it is they're paying for.

How it works

1. Create a request. Call the Volley API with the bank account that will receive funds, the amount, and an optional reference. Volley returns a payment request with an unique id and url.
2. Present it to your customer. Use one of our UI options (QR code, hosted, embedded) to share or redirect your customer to the request,
3. Customer approves. They select their bank and are redirected to their bank app to and approve or decline the payment.
4. Get the result. You can poll the status of a request or subscribe to webhooks to get notified directly once payment is made.

Creating your first request

Send a POST to /v1/requests with your API key included as a Bearer Token:

curl -X POST https://api.volley.nz/v1/requests \
  -H "Authorization: Bearer $VOLLEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "bank_account_id": "bankaccount_xxx",
    "amount": "50.00 NZD",
    "message": "Invoice #123",
    "type": "single",
    "reference": "REF123",
    "merchant_identifier": "37436c2350b34586bde2c13128920b24"
  }'

See the API reference for the full list of parameters.

Request status and lifecycle

Request expiry can be set with expiresIn parameter (e.g. "expires_in": "10m") when creating a request, and Volley will automatically disable further payments after this time.

One-off and reusable requests

Payment requests can be either one-off with only one payment accpeted, or reusable where the same request can be paid any number of times by different customers.

Reusable requests are perfect for things like charity donations, fundraising, collecting fees or subs, or any other scenario where multiple customers pay the same amount for the same product or service.

To setup a reusable payment you can set pass type: "multi" in your request. Multi requests do not transition to the "paid" status after the first payment is made, remaining active so additional customers can use it to pay.

Each payment against a request is tracked as its own unique payment ID and it's own status.

Flexible amounts

Volley requests can be for a fixed amount or you can let the payer choose how much they'll pay. This is ideal for donation use cases, as donor's can all use the same QR code or link but choose their own amount to give on their own device.

To setup a dynamic amount request you can set allow_dynamic_amount: true on a request.

Dynamic amount requests can also have suggested amounts to make it quick to donate. You can include these by passing a comma-separated list of amounts in the suggested amounts field, e.g. suggested_amounts: "10,20,50,100,200".

Particulars, code and reference

The New Zealand banking system has three text fields used for providing payment references and other identifiers: particulars, code, and reference, collectively referred to as the "PCR" fields. These are included on the bank statement lines for both the payee and the payer bank accounts when a payment is made.

Volley uses the particulars and code fields, and you can optionally use the reference field when creating a payment request. This is useful for reconciling payments against your bank account.

| Reference | You can provide anything matching [a-zA-Z0-9-]12 | | Particulars | A unique payment identifier set by Volley. In the form V-XXXXXX. | | Code | Always set as “Volley” to help payers identify how this payment was made. |

Test mode

Volley provides Test Mode which allows you to create a realistic testing environment for your app that can use real bank apps to simulate a payment. When using test mode, payments are overriden to $0.01 and paid to a dedicated test bank account owned by Volley, rather than your business account. We'll configure this test bank account for you during onboarding.

You can create test mode payment requests by using a test environment API key.

Test mode requests can have payments made by any of our supported banks and a "sandbox bank" labelled on the request page as “API Centre”. The sandbox bank lets you quickly the payment flow without needing to use a real bank app. You can access the sandbox with the following credentials:

• Username: user01
• Password: Any password.

Test amounts

When in test mode, you can create a payment request for specific "magic" amounts to simulate different testing scenarios.