Integration guide
Set up mandates, initiate recurring payments, and manage the mandate lifecycle
Available Markets
Mandates are currently available in Australia (PayTo). Support for UK cVRP is coming soon.
Beta
The Mandates API is currently in beta. Request/response shapes might be subject to change. Please, reach out to your Volt contact before integrating.
Overview
The Mandate Management API lets you set up a mandate (a standing authorisation by the payer for future debits), initiate recurring payments against an active mandate, amend or pause it, and cancel it when the customer relationship ends.
Mandate setup flow
The integration mirrors the Global Payments API pattern: responses contain a mandateSetupFlow object that drives the authorisation (setup) process:
{
// ...
"mandateSetupFlow": {
"status": "PROCESSING",
"details": {
"reason": "AWAITING_USER_REDIRECT",
"redirect": {
"url": "https://short.vo.lt/authorisation?code=xyz",
"redirectUrl": "https://myBank.com/authorisation?code=xyz"
}
}
}
}The setup flow is the same state machine as for :
Prerequisites
In order to use Volt's API you need to be authenticated. Use this to handle authentication with Volt's API.
Create a mandate
API-only integration requires passing the X-Volt-Initiation-Channel HTTP header with value api.
The setup flow begins with POST /mandates. The payer must authorise the mandate. Once authorised, the mandate becomes ACTIVE and can be used to initiate payments.
Partner collects mandate details from the payer.
Gather the data needed to set up the mandate.
Partner creates the mandate.
Call POST /mandates endpoint. The response includes a redirect URL to which the user should be redirected.
{
// ...
"mandateSetupFlow": {
"status": "PROCESSING",
"details": {
"reason": "AWAITING_USER_REDIRECT",
"redirect": {
"url": "https://short.vo.lt/authorisation?code=xyz",
"redirectUrl": "https://myBank.com/authorisation?code=xyz"
}
}
}
// ...
}Payer is being redirect to the Volt hosted checkout.
Volt will handle authorisation (setup) process.
Payer authorises the mandate at their institution.
Payer accepts mandate details.
Payer returns to the partner.
Full control is given back to the partner.
Partner receives the mandate notification about the status.
Notification (webhook) will be sent to you.
On success, the mandate's top-level status.status becomes ACTIVE.
{
// ...
"status": {
"status": "ACTIVE",
"details": null
}
// ...
}Recalling an unauthorised mandate
To withdraw a mandate that has not yet been authorised, call DELETE /mandates/{id}. This is only valid before the mandate reaches ACTIVE; afterwards use Cancel.
Initiate a recurring payment
Once the mandate is ACTIVE, you can debit the payer by calling POST /mandates/{id}/payments.
Partner submits the recurring payment request.
{
"currency": "AUD",
"amount": 10000,
"paymentReference": "T1Qwerty",
"internalReference": "H35X48Y4FWOD6G3S",
"communication": {
"notification": {
"url": "https://mywebsite.com/notifications"
}
}
}Payment amount and frequency must respect the mandate's constraints/limits.
Response structure is the same as in Global Payments API. Payment details can be fetched with GET /payments/{id}.
Partner receives the payment notification about the payment status.
Notification (webhook) will be sent to you.
You can configure payment notifications in the Fuzebox or pass it directly in the POST /mandates/{id}/payments request.
A detailed guide on configuring notifications in the Fuzebox can be found here.
Manage an active mandate
PATCH /mandates/{id} is used to:
- submit
requiredInputvalues during the setup flow (WAITING_FOR_INPUT), - update system-related fields on a mandate that has not yet been authorised.
For changes to an already-authorised mandate, use Amendments instead.
POST /mandates/{id}/suspend pauses an ACTIVE mandate.
While suspended, recurring payments cannot be initiated.
POST /mandates/{id}/release returns a SUSPENDED mandate to ACTIVE.
Only the party that suspended the mandate may release it — a customer cannot release a payer-suspended mandate, and vice versa.
POST /mandates/{id}/cancel permanently terminates an ACTIVE or SUSPENDED mandate. It is also used to cancel a NEW mandate that the payer has not yet acted on.
No further payments can be initiated with this mandate.
Amendments
To change mandate details or limits on an ACTIVE or SUSPENDED mandate, see the .
Webhooks
Volt delivers webhooks to the communication.notification.url you provided when creating the mandate.
Webhook signatures and timestamping use the same X-Volt-Signed / X-Volt-Timed headers as the rest of the Volt API — verify them as described in the .
Reference
For full API reference, see the .
How is this guide?
Last updated on