Create payment request

POST/requests

Creates a new payment request with the specified parameters

Authorization

bearer

AuthorizationBearer <token>

Your Volley API key as a bearer token

In: header

Request Body

application/json

Payload for creating a payment request

bank_account_id*string

ID of the bank account in Volley where you'll receive payment.

amount*string

The requested amount amount with currency code.

message*string

Message or description to explain the purpose of the payment.

flow*string

Payment flow type

expires_in?string

Expiry for this request as a duration (e.g. 10m).

merchant_identifier?string

Optional merchant identifier for tracking purposes

merchant_customer_identifier?string

Optional merchant customer identifier for tracking purposes

type?string

Type of request allowing one-off or multiple payments. Either "single" or "multi".

reference?string

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

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.

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).

max_payment_amount?integer

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

success_redirect_url?string

Optional. If provided, the user will be redirected back to this URL after a successful payment. Must be an allowed domain for your Volley account.

failure_redirect_url?string

Optional. If provided, the user will be redirected back to this URL after a failed payment. Must be an allowed domain for your Volley account.

options?

Options for request creation

Response Body

`application/json`

const body = JSON.stringify({  "bank_account_id": "bankaccount_ZYm2YeJXZ8Vzx3jjMLyp6",  "amount": "10.00 NZD",  "message": "Payment for invoice #12345",  "flow": "link"})fetch("https://example.com/requests", {  method: "POST",  headers: {    "Content-Type": "application/json"  },  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": "QG8NV468",      "reference": "INV-1234"    },    "banner_image_url": "https://example.com/banner.jpg",    "logo_image_url": "https://example.com/logo.jpg",    "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_dynamic_amount": true,    "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  },  "payment": {    "id": "payment_Bzv6djpVl07tmMx2Tuode",    "request_id": "request_8GbnJK6WrxGvPobCylFDO",    "amount": {      "value": "10.00 NZD",      "formatted": "$10.00"    },    "status": "pending",    "url": "https://app.volley.nz/pay/8GbnJK6WrxGvPobCylFDO/Bzv6djpVl07tmMx2Tuode",    "qr_data": "data:image/svg;...",    "merchant_identifier": "merchant_abc123",    "cust_info": {      "id": "custinfo_OJKskG1WEa70sQG8NV468",      "payment_id": "payment_Bzv6djpVl07tmMx2Tuode",      "email": "customer@example.com",      "phone": "+1234567890",      "first_name": "John",      "last_name": "Doe",      "address1": "Building",      "address2": "123 Main Street",      "address3": "Te Aro",      "address4": "",      "city": "Wellington",      "postcode": "6011",      "marketing_opt_in": false,      "created_at": "2025-01-15T10:30:00Z",      "updated_at": "2025-01-15T10:30:00Z"    },    "provider": "anz",    "is_test_mode": false,    "created_at": "2025-02-12T08:30:00Z",    "updated_at": "2025-02-12T08:30:00Z",    "completed_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`