Create payment request

POST/requests

Creates a new one-off or recurring payment request that can be shared or presented to a customer/s.

Authorization

bearer

AuthorizationBearer <token>

Your Volley API key as a bearer token

In: header

Request Body

application/json

Request payload for creating a payment request.

bank_account_id*string

ID of the bank account in Volley where you'll receive payment. This bank account must be already verified, contact Volley if you have an account needing verification.

amount*string

The requested amount as an amount with currency string.

message*string

Message or description to explain the purpose of the payment.

expires_in?string

Optional expiry time for this request as a duration string (e.g. 10m). If not provided the request will not expire.

merchant_identifier?string

A free-text identifier field for internal tracking or reconciliation purposes, e.g. can be used to tie requests to a resource within your own system. All payments created from this request will share the same merchant identifier.

merchant_customer_identifier?string

Optional identifier for the paying customer, used for identification of repeat payments. This field is required to be provided if the payer is a known customer in your system i.e. is logged in at the time of creating a payment request. Any stable identifier (e.g. a hash of the customer's ID or email address in your system) is allowed.

type?string

Type of this request, indicating whether it's a single use or allows multiple payments. A single use request is marked as "paid" immediately after the first payment is received and cannot be used again. Single is currently required for recurring payments.

Default"single"

reference?string

A reference to appear in the "PCR" fields on the bank statement of both you and the payer. Maximum 12 characters. Allowed [a-zA-Z0-9-].

allow_dynamic_amount?boolean

If true, customers can self-select or enter the amount they would like to pay or donate.

min_payment_amount?integer

Optional if allow_dynamic_amount is true. The minimum allowed payment amount in cents. Defaults to 100 ($1.00).

Formatint64

Default100

max_payment_amount?integer

Required if allow_dynamic_amount is true. The maximum allowed payment amount in cents.

Formatint64

require_customer_basic_info?boolean

If true, a customer is required to provide their email address and name before payment.

collect_customer_phone?boolean

If true, a customer can optionally provide their phone number before payment.

require_customer_phone?boolean

If true, a customer is required to provide their phone number before payment.

require_customer_address?boolean

If true, a customer is required to provide their address before payment.

success_redirect_url?string

Optional. URL to redirect a customer to after successful payment. The host must be configured in your Domains settings on the Volley Dashboard.

failure_redirect_url?string

Optional. URL to redirect a customer to after a failed payment. The host must be configured in your Domains settings on the Volley Dashboard.

recurring_options?

Constraints that limit the type and frequency of payments that can be executed after a customer has agreed to a recurring payment request.

cust_info?

Customer identification details supplied when creating a payment request, required (with at least an email address) for recurring payment requests.

options?

Options for request creation

Response Body

`application/json`

const body = JSON.stringify({  "bank_account_id": "bankaccount_ZYm2YeJXZ8Vzx3jjMLyp6",  "amount": "10.00 NZD",  "message": "Invoice"})fetch("https://example.com/requests", {  method: "POST",  headers: {    "Content-Type": "application/json",    "Authorization": "Bearer $VOLLEY_API_KEY"  },  body})

{  "request": {    "id": "request_8GbnJK6WrxGvPobCylFDO",    "bank_account_id": "bankaccount_ZYm2YeJXZ8Vzx3jjMLyp6",    "user_id": "user_cEwCTcXyxhdFbJLyune6x",    "amount": {      "value": "10.00 NZD",      "formatted": "$10.00"    },    "message": "Invoice #1234 - Website Development",    "status": "active",    "url": "https://app.volley.nz/pay/8GbnJK6WrxGvPobCylFDO",    "qr_data": "data:image/svg;...",    "type": "multi",    "flow": "link",    "merchant_identifier": "merchant_abc123",    "pcr": {      "code": "Volley",      "particulars": "V-78A14T",      "reference": "INV-1234"    },    "banner_image_url": "https://example.com/banner.jpg",    "logo_image_url": "https://example.com/logo.jpg",    "allow_dynamic_amount": true,    "min_payment_amount": 1000,    "max_payment_amount": 100000,    "require_customer_basic_info": true,    "collect_customer_phone": false,    "require_customer_phone": false,    "require_customer_address": false,    "allow_marketing_opt_in": false,    "is_test_mode": false,    "success_redirect_url": "https://example.com/success",    "failure_redirect_url": "https://example.com/failure",    "created_at": "2025-02-12T08:30:00Z",    "expires_at": "2025-03-12T08:30:00Z",    "updated_at": "2025-02-12T08:30:00Z",    "deleted_at": null  }}

{  "code": "bad_request.invalid_param.amount",  "message": "Invalid format for amount (valid: '10.00 NZD')",  "params": {}}

{  "code": "bad_request.invalid_param.amount",  "message": "Invalid format for amount (valid: '10.00 NZD')",  "params": {}}

{  "code": "bad_request.invalid_param.amount",  "message": "Invalid format for amount (valid: '10.00 NZD')",  "params": {}}

Create payment request

Authorization

Request Body

Response Body

201application/json

400application/json

401application/json

500application/json

`application/json`

`application/json`

`application/json`

`application/json`