Mandate
Mandate represent the Direct Debit mandate with a customer. SmarterPay will notify you via a webhook whenever the state of a Mandate changes.
If a Mandate is cancelled any payments, or credits, currently set to “pending_submission” will be updated and set to “cancelled” with a zero amount, and update notifications will be sent via payment or credit Webhooks. For example, if the mandate AUD0012345678 is set to cancelled and two payments are still to be collected, the reply will detail the Cancelled Mandate, and two Payment Webhooks will be sent, one for each payments. On a cancellation of a mandate any recurring schedules attached to the mandate will also be made inactive with notification by webhook.
Inserting mandates will now reference a client bank account. This can be optional on insert or can be specified, however if it is blank on insert it will set the default bank account attached to the default sun for the client.
It is not possible to create a mandate with a non enabled bank account, this will return a bad request error.
| Method | Purpose |
|---|---|
| POST | Create a Mandate |
| PUT | Update a Mandate |
| GET (Singular) | Return Mandate details |
| GET (List) | Return Mandate details in a list |
POST
Action: Create a Mandate.
Method: POST
URL: https://api.smarterpaycloud.com/service.svc/mandate
Request Parameters
| Property | Mandatory | Description |
|---|---|---|
| customer_bank_account | True | ID Of a customer bank account |
| auddis | False | The Mandate reference, commonly known as AUDDIS. If no reference is provided then one will be auto-generated. |
| client_bank_account_id | False | The client bank account the mandate will be registered to, if blank or not supplied it will default to the default bank account on the default sun. |
| dd_status | False | Status of the mandate. Can be set to: “on hold”, “new instruction”, “first collection”, “ongoing collection” or “cancelled”. |
| account_validation | False | Provide the property, with a value of “true”, to request, if enabled, account validation on the Mandate. |
| metadata | False | String for Custom metadata |
Request Sample
{
"Mandate":
{
"customer_bank_account":"BANK00003432",
"auddis":"AUD00003343",
"client_bank_account_id":"CBA-000001",
"account_validation":true,
"metadata":""
}
}
Response Parameters
| Property | Description |
|---|---|
| I_am_the_only_account_holder | True, if the Mandate was not setup using joint signatories. |
| Sun_name | Friendly name attached to a sun. |
| Sun_Number | Sun that is attached to this mandate. |
| account_name | Name on the account. |
| account_number | Account number supplied from bank account record. |
| auddis | Mandate reference, commonly known as Auddis. |
| bank_name | Name of the bank. |
| client_bank_account_id | Uniquer identifier for the attached client bank account. |
| created_at | Datetime formatted as ISO8601. |
| customer_account | Customer account ID if one has been created. |
| customer_bank_account | Customer bank account ID. |
| dd_status | Status of the direct debit created. Can be: “await validation”, “cancelled”, “cancelled by originator”, “cancelled by payer”, “expired”, “failed validation”, “first collection”, “new instruction”, “on hold”, “ongoing collection”. |
| id | Unique identifier for the record. |
| originator_account_number | Originator account number that the mandate is connected to. |
| originator_sort_code | Orginator sort code that the mandate is connected to. |
| sort_code | Sort code supplied from bank account record. |
| account_validation_url | If enabled, and requested, the URL to be used to complete the Account Validation process. |
| account_validation_id | The ID of the Associated Acount Validation record. |
| metadata | Returns optional, custom, metadata, if set |
Response Sample
{
"Mandate": {
"I_am_the_only_account_holder": "false",
"Sun_Name": "Smarterpay Test",
"Sun_Number": "100263",
"account_name": "J Hetfield",
"account_number": "75849855",
"auddis": "FBMAN00000373",
"bank_name": "BARCLAYS BANK PLC",
"client_bank_account_id": "CBA-0000002",
"created_at": "2023-03-14T15:07:41Z",
"customer_account": "CA0175OW1YJV3Y8X29LV",
"customer_bank_account": "BA01EXYR6K8KXYP4ZLQV",
"dd_status": "await validation",
"id": "M01RZO41Y8DL3J0GNLW",
"originator_account_number": "10020645",
"originator_sort_code": "834600",
"sort_code": "200052",
"account_validation_url": "https://accountvalidation.smarterpaycloud.com",
"account_validation_id": "AV01X5137EJ746J4QOMY",
"metadata":""
}
}
PUT
Action: Update a Mandate.
Method: PUT
URL: https://api.smarterpaycloud.com/service.svc/mandate/{ID}
{ID} denotes ID of record.
Request Parameters
| Property | Mandatory | Description |
|---|---|---|
| auddis | True | AUDDIS reference of the mandate |
| dd_status | True | Status of the mandate. Can be set to either : “on hold”, “new instruction”, “first collection”, “ongoing collection” or “cancelled”. |
| metadata | False | String for Custom metadata |
Request Sample
{
"Mandate":
{
"auddis":"AUD00003343",
"dd_status":"cancelled",
"metadata":""
}
}
Response Parameters
| Property | Description |
|---|---|
| I_am_the_only_account_holder | True, if the Mandate was not setup using joint signatories. |
| Sun_name | Friendly name attached to a sun. |
| Sun_Number | Sun that is attached to this mandate. |
| account_name | Name on the account. |
| account_number | Account number supplied from bank account record. |
| auddis | Mandate reference, commonly known as Auddis. |
| bank_name | Name of the bank. |
| client_bank_account_id | Uniquer identifier for the attached client bank account. |
| created_at | Datetime formatted as ISO8601. |
| customer_account | Customer account ID if one has been created. |
| customer_bank_account | Customer bank account ID. |
| dd_status | Status of the direct debit created. Can be: “await validation”, “cancelled”, “cancelled by originator”, “cancelled by payer”, “expired”, “failed validation”, “first collection”, “new instruction”, “on hold”, “ongoing collection”. |
| id | Unique identifier for the record. |
| originator_account_number | Originator account number that the mandate is connected to. |
| originator_sort_code | Orginator sort code that the mandate is connected to. |
| sort_code | Sort code supplied from bank account record. |
| account_validation_url | If enabled, and requested, the URL to be used to complete the Account Validation process. |
| account_validation_id | The ID of the Associated Acount Validation record. |
| metadata | Returns optional, custom, metadata, if set |
Response Sample
{
"Mandate": {
"I_am_the_only_account_holder": "false",
"Sun_Name": "Smarterpay Test",
"Sun_Number": "100263",
"account_name": "J Hetfield",
"account_number": "75849855",
"auddis": "FBMAN00000373",
"bank_name": "BARCLAYS BANK PLC",
"client_bank_account_id": "CBA-0000002",
"created_at": "2023-03-14T15:07:41Z",
"customer_account": "CA0175OW1YJV3Y8X29LV",
"customer_bank_account": "BA01EXYR6K8KXYP4ZLQV",
"dd_status": "await validation",
"id": "M01RZO41Y8DL3J0GNLW",
"originator_account_number": "10020645",
"originator_sort_code": "834600",
"sort_code": "200052",
"account_validation_url": "https://accountvalidation.smarterpaycloud.com",
"account_validation_id": "AV01X5137EJ746J4QOMY",
"metadata":""
}
}
GET (Singular)
Action: Return Mandate details.
Method: GET
URL: https://api.smarterpaycloud.com/service.svc/mandate/{ID}
{ID} denotes ID of record.
Response Parameters
| Property | Description |
|---|---|
| I_am_the_only_account_holder | True, if the Mandate was not setup using joint signatories. |
| Sun_name | Friendly name attached to a sun. |
| Sun_Number | Sun that is attached to this mandate. |
| account_name | Name on the account. |
| account_number | Account number supplied from bank account record. |
| auddis | Mandate reference, commonly known as Auddis. |
| bank_name | Name of the bank. |
| client_bank_account_id | Uniquer identifier for the attached client bank account. |
| created_at | Datetime formatted as ISO8601. |
| customer_account | Customer account ID if one has been created. |
| customer_bank_account | Customer bank account ID. |
| dd_status | Status of the direct debit created. Can be: “await validation”, “cancelled”, “cancelled by originator”, “cancelled by payer”, “expired”, “failed validation”, “first collection”, “new instruction”, “on hold”, “ongoing collection”. |
| id | Unique identifier for the record. |
| originator_account_number | Originator account number that the mandate is connected to. |
| originator_sort_code | Orginator sort code that the mandate is connected to. |
| sort_code | Sort code supplied from bank account record. |
| account_validation_url | If enabled, and requested, the URL to be used to complete the Account Validation process. |
| account_validation_id | The ID of the Associated Acount Validation record. |
| metadata | Returns optional, custom, metadata, if set |
Response Sample
{
"Mandate": {
"I_am_the_only_account_holder": "false",
"Sun_Name": "Smarterpay Test",
"Sun_Number": "100263",
"account_name": "J Hetfield",
"account_number": "75849855",
"auddis": "FBMAN00000373",
"bank_name": "BARCLAYS BANK PLC",
"client_bank_account_id": "CBA-0000002",
"created_at": "2023-03-14T15:07:41Z",
"customer_account": "CA0175OW1YJV3Y8X29LV",
"customer_bank_account": "BA01EXYR6K8KXYP4ZLQV",
"dd_status": "await validation",
"id": "M01RZO41Y8DL3J0GNLW",
"originator_account_number": "10020645",
"originator_sort_code": "834600",
"sort_code": "200052",
"account_validation_url": "https://accountvalidation.smarterpaycloud.com",
"account_validation_id": "AV01X5137EJ746J4QOMY",
"metadata":""
}
}
GET (List)
Action: Return Mandate details in a list.
Method: GET
URL: https://api.smarterpaycloud.com/service.svc/mandates
Optional Parameters and filters are available, please see below.
Response Parameters
| Property | Description |
|---|---|
| I_am_the_only_account_holder | True, if the Mandate was not setup using joint signatories. |
| Sun_name | Friendly name attached to a sun. |
| Sun_Number | Sun that is attached to this mandate. |
| account_name | Name on the account. |
| account_number | Account number supplied from bank account record. |
| auddis | Mandate reference, commonly known as Auddis. |
| bank_name | Name of the bank. |
| client_bank_account_id | Uniquer identifier for the attached client bank account. |
| created_at | Datetime formatted as ISO8601. |
| customer_account | Customer account ID if one has been created. |
| customer_bank_account | Customer bank account ID. |
| dd_status | Status of the direct debit created. Can be: “await validation”, “cancelled”, “cancelled by originator”, “cancelled by payer”, “expired”, “failed validation”, “first collection”, “new instruction”, “on hold”, “ongoing collection”. |
| id | Unique identifier for the record. |
| originator_account_number | Originator account number that the mandate is connected to. |
| originator_sort_code | Orginator sort code that the mandate is connected to. |
| sort_code | Sort code supplied from bank account record. |
| account_validation_url | If enabled, and requested, the URL to be used to complete the Account Validation process. |
| account_validation_id | The ID of the Associated Acount Validation record. |
| metadata | Returns optional, custom, metadata, if set |
Response Sample
{
"Mandates": [
{
"I_am_the_only_account_holder": "false",
"Sun_Name": "Smarterpay Test",
"Sun_Number": "100263",
"account_name": "J Hetfield",
"account_number": "75849855",
"auddis": "FBMAN00000374",
"bank_name": "BARCLAYS BANK PLC",
"client_bank_account_id": "CBA-0000002",
"created_at": "2023-03-14T15:07:57Z",
"customer_account": "CA0175OW1YJV3Y8X29LV",
"customer_bank_account": "BA01EXYR6K8KXYP4ZLQV",
"dd_status": "new instruction",
"id": "M01O6YQRDJZZOJVL359",
"originator_account_number": "10020645",
"originator_sort_code": "834600",
"sort_code": "200052",
"metadata":""
},
{
"I_am_the_only_account_holder": "false",
"Sun_Name": "Smarterpay Test",
"Sun_Number": "100263",
"account_name": "J Hetfield",
"account_number": "75849855",
"auddis": "FBMAN00000373",
"bank_name": "BARCLAYS BANK PLC",
"client_bank_account_id": "CBA-0000002",
"created_at": "2023-03-14T15:07:41Z",
"customer_account": "CA0175OW1YJV3Y8X29LV",
"customer_bank_account": "BA01EXYR6K8KXYP4ZLQV",
"dd_status": "await validation",
"id": "M01RZO41Y8DL3J0GNLW",
"originator_account_number": "10020645",
"originator_sort_code": "834600",
"sort_code": "200052",
"account_validation_url": "https://accountvalidation.smarterpaycloud.com",
"account_validation_id": "AV01X5137EJ746J4QOMY",
"metadata":""
}
]
}
Optional Parameters and filters
Optional parameters can be added to the GET URL by using a “?” in front of the first parameter and “&” in front of subsequent parameters, for example https://api.smarterpaycloud.com/Service.svc/BankAccounts?limit=2&page_no=1
| Parameter | Description |
|---|---|
| limit | Limits the number of records returned by the request. Default=40 when not specified. Minimum=1. Maximum=500. |
| page_no | Specifies which page of records are returned by the request. Default=1 when not specified. |
| sort_field | specifies which field to sort on. Options are: “reference”,“sort_code”,“account_number”,“id”,“account_name”,“created_at” (Default when not specified),“customer_id” |
| sort_order | Specifies which order to sort on. Options are asc (ascending. Default when not specified) or desc (descending). |
| Filter | Description |
|---|---|
| account_name | Filter the list using the account_name. Matches will contain the provided value. |
| account_number | Filter the list using the account_number. Matches will contain the provided value. |
| created_from | Filter the list with records created after the datetime supplied. Format is YYYY-MM-DD HH:MM:SS (2022-05-13 10:15:00). |
| created_to | Filter the list with records created before the datetime supplied. Format is YYYY-MM-DD HH:MM:SS (2022-05-13 10:15:00). |
| customer_bank_account_id | Filter the list using the customer_bank_account_id. Matches will exactly match the provided value. |
| customer_id | Filter the list using the customer_id. Matches will exactly match the provided value. |
| id | Filter the list using the id. Matches will exactly match the provided value. |
| reference | Filter the list using the reference (Auddis reference). Matches will contain the provided value. |
| sort_code | Filter the list using the custom_reference. Matches will contain the provided value. |
| status | Filter the list using the status of the record. Can be a comma seperated list of required values. Options are “await validation”, “cancelled”, “cancelled by originator”, “cancelled by payer”, “expired”, “failed validation”, “first collection”, “new instruction”, “on hold”, “ongoing collection”. |