Mandates APIbetaMandate management
Create mandate
Authorization
Bearer AuthorizationBearer <token>
Bearer token using a JWT.
In: header
Header Parameters
Idempotency-Key*string
It helps preventing duplicates in your POST requests.
It is recommend using a UUID for the key, however you may use any other unique identifier you choose.
Length
length <= 64X-Volt-Initiation-Channel*string
Channel used for setup/processing flow.
Value in
"hosted"X-Volt-Api-Version*integer
Version of the API used. Currently, version 1 is the only version.
Value in
1Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://gateway.sandbox.volt.io/mandates" \ -H "Idempotency-Key: 85136c79cbf9fe36bb9d05d0639c70c265c18d37" \ -H "X-Volt-Initiation-Channel: hosted" \ -H "X-Volt-Api-Version: 1" \ -H "Content-Type: application/json" \ -d '{ "currency": "AUD", "system": "PAY_TO", "mode": "RECURRING", "purpose": "OTHER", "internalReference": "H35X48Y4FWOD6G3S", "payer": { "reference": "JDOE-101" }, "validity": { "from": "2026-03-01 00:00:00" }, "payTo": { "accountIdentifiers": { "accountName": "John Doe", "payId": "john@doe.com", "payIdType": "EMAIL" }, "limits": { "periodic": { "period": "MONTH", "maxPaymentsCount": 3 }, "payment": { "maxAmount": 70000 } }, "description": "Coffee subscription #123123" }, "device": { "ip": "192.168.0.1", "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X x.y; rv:42.0) Gecko/20100101 Firefox/42.0", "fingerprint": "2aae6c35c94fcfb415dbe95f408b9ce91ee846ed" }, "communication": { "notification": { "url": "https://mywebsite.com/notifications" }, "return": { "urls": { "unified": { "url": "https://mywebsite.com/process" } } } } }'{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"currency": "AUD",
"system": "PAY_TO",
"mode": "RECURRING",
"purpose": "OTHER",
"internalReference": "H35X48Y4FWOD6G3S",
"payer": {
"reference": "JDOE-101",
"firstName": null,
"lastName": null,
"email": null,
"accountIdentifiers": {
"accountName": "John Doe",
"payId": "john@doe.com",
"payIdType": "EMAIL"
}
},
"beneficiary": {
"name": "Jane Doe"
},
"validity": {
"from": "2026-03-01 00:00:00",
"to": null
},
"payTo": {
"accountIdentifiers": {
"accountName": "John Doe",
"payId": "john@doe.com",
"payIdType": "EMAIL"
},
"limits": {
"periodic": {
"period": "MONTH",
"maxPaymentsCount": 3
},
"payment": {
"maxAmount": 70000
}
},
"description": "Coffee subscription #123123"
},
"device": {
"ip": "192.168.0.1",
"userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X x.y; rv:42.0) Gecko/20100101 Firefox/42.0",
"fingerprint": "2aae6c35c94fcfb415dbe95f408b9ce91ee846ed"
},
"status": {
"status": "AWAITING_AUTHORISATION",
"details": null
},
"mandateSetupFlow": {
"status": "PROCESSING"
}
}{
"code": "MISSING_HTTP_HEADER",
"message": "Missing \"X-Volt-Initiation-Channel\" HTTP header."
}{
"code": "UNAUTHORISED",
"message": "Unauthorised."
}{
"code": "ACCESS_DENIED",
"message": "Access denied."
}{
"code": "IDEMPOTENCY_CONFLICT",
"message": "Idempontency key already used."
}{
"code": "VALIDATION_FAILURE",
"message": "Validation failed.",
"errors": [
{
"type": "TOO_LONG",
"propertyPath": "payTo.accountIdentifiers.bsb",
"message": "BSB must have a maximum of 6 characters"
}
]
}{
"code": "INTERNAL_SERVER_ERROR",
"message": "Something went wrong. Please, contact support. TraceId: b8cfd344-093c-4b8c-8fd4-f0e406060c3c. Timestamp: 1723193467."
}