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. Maximum 1000 characters.

Click to view Account Validation Flow

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”. If bacs_code is also supplied this property will be ignored.
bacs_code False Bacs Code to apply to record, and related records, based on Rejection Profile actions. Can be an ADDACS Code or AUDDIS Code (Case insensitive, no space in code, for example “addacs2”) or empty (“”) to clear “bacs_reason_code”, “bacs_description”, “bacs_reference” and “bacs_filename” fields/values.
metadata False String for Custom metadata

Notes:

  • When Credit Anti-Fraud is enabled, setting “dd_status” to “ongoing collection” will also change “credits_allowed”, on the Bank Account record, to “true”.

Request Sample 

{
 "Mandate":
  {
   "auddis":"AUD00003343",
   "dd_status":"cancelled",
   "bacs_code":"addacs2",
   "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”.
  • Last modified: 2024/11/05 10:45