Payment

Payments can only be setup against active Mandate, the dd_status values must be “new_instructions”, “first_collection”, “ongoing_collection” or “final_collection”, if the dd_status is set to “cancelled”, “cancelled by payer” or “cancelled by originator”, then a Payment cannot be setup.Records with a “payment_type” set to “first_collection”, “ongoing_collection” or “final_collection” are all standard payment records, “payment_type” set to “represent” are those that are sent after an initial payment was returned unpaid, these payments will also have “related_payment” set to the “id” of the previously failed payment.

Payment against Cancelled Mandates
If SmarterPay Cloud receives a Payment POST message and the Mandate dd_status is set to “cancelled”, “cancelled by payer” or “cancelled by originator”, then the payment will be recorded as cancelled with a zero amount. For example the following payment request is being made against Mandate AUD0012345678, and the dd_status of that mandate is set to “cancelled by payer”, the returned amount and status is 0 and cancelled.

Invalid Payment dates
If SmarterPay Cloud receives a Payment POST message with collection_date set to before today, then a 400 BAD REQUEST will be returned. If SmarterPay Cloud receives a Payment POST message with collection_date set to a non-banking date (weekend or national bank holiday), or is not 3 clear banking days into the future, SmarterPay Cloud will record/store the Payment record with next available banking day (that it can be collected – mindful of 3 banking days), and return this date in the response. For example the following POST request, sets the “collection_date” to Friday 30th March (this is the Easter Bank Holiday weekend), and both Friday 30th and Monday 2nd are national bank holidays, and the so the date stored and returned is Tuesday 3rd April.

Updating payments
If SmarterPay Cloud receives a Payment PUT message to cancel a Payment, and the payment has already set to “submitted”, “successful” or indeed “failed”, then the service will reply with existing status of the Payment. For example, if PUT request, sets the amount to 0, and the specific Payment has already been submitted, the status in the response will submitted and the amount will be as is, The SmarterPay portal will record that the request was attempted.

Record types
There are two types of record types within Smarterpay Cloud, posting payments via the API will default to record type “direct_debit” however it is possible to use a GET to retrieve payments with the record type “card_payment”.

Method Purpose
POST (Singular) Create a Payment
POST (List) Create Payments from a list
PUT Update a Payment
GET (Singular) Return Payment details
GET (List) Return Payment details in a list

POST (Singular)

Action: Create a Payment.
Method: POST
URL: https://api.smarterpaycloud.com/service.svc/payment

Request Parameters

Property Mandatory Description
auddis True The unique AUDDIS reference.
amount True Amount in pence – no decimal point
description True Reference description – will be included in outgoing email. Maximum 45 characters.
collection_date True Date to receive payment - 10 digit date in the format of “YYYY-MM-DD”
custom_reference False Custom reference set on record. Maximum 100 characters.
default_narrative False Text, associated with the transaction, which will be displayed in the customer's bank account. Maximum 18 characters.
metadata False String for Custom metadata. Maximum 1000 characters.

Request Sample 

{
 "payment":
  {
   "amount":100,
   "collection_date":"2018-08-25",
   "description":"metered bill",
   "auddis":"AUD00003435",
   "custom_reference":"XYZ",
   "default_narrative": "SP22-01",
   "metadata": ""
  }
}

Response Parameters

Property Description
amount Amount
auddis Auddis reference
collection_date Date to receive payment - 10 digit date in the format of “YYYY-MM-DD”, corrected, if the date received by the service is a none banking day, weekend or national bank holiday
created_at Datetime formatted as ISO8601
custom_reference Custom reference set on record
default_narrative Text, associated with the transaction, which will be displayed in the customer's bank account. Maximum 18 characters.
description Reference description – will be included in outgoing email
id Unique identifier
mandate ID of the parent Mandate
payment_type Can be: “first_collection”, “ongoing_collection”, “final_collection”, “represent”, “ecommerce” or “MOTO”
record_type Can be: “direct_debit” or “card_payment”
related_payment This is the Payment id of the initial Failed Payment, only applicable for represented payments
status Can be: “pending_submission” ,“submitted”, “failed”, “successful” or “cancelled”
metadata Returns optional, custom, metadata, if set

Response Sample 

{
    "payment": {
        "amount": "2532",
        "auddis": "FBMAN02814872",
        "collection_date": "2022-05-19",
        "created_at": "2022-05-17T12:15:00Z",
        "custom_reference": "",
        "default_narrative": "",
        "description": "",
        "id": "P01YZ96J1D7WDK8NEWD",
        "mandate": "M01741EJ519Y51P3XGL",
        "payment_type": "ongoing collection",
        "record_type": "direct_debit",
        "related_payment": " ",
        "status": "successful",
        "metadata": ""
    }
}

POST (List)

Action: Create Payments from a list.
Method: POST
URL: https://api.smarterpaycloud.com/service.svc/payments

Note: Bulk inserts of transactions for same-day submission can only be guaranteed before 9pm. After 9pm, the transactions may be submitted the next banking day.

Request

Action: Create Payments from a list.
Request Parameters

Property Mandatory Description
amount True Amount in pence. No decimal point.
collection_date True Date to receive payment. 10 digit date in the format of “YYYY-MM-DD”.
custom_reference False Custom reference set on record. Maximum 100 characters.
default_narrative False Text, associated with the transaction, which will be displayed in the customer's bank account. Maximum 18 characters.
description True Reference description. Maximum 45 characters.
mandate_id True Mandate record Id that the payment belongs to.
metadata False String for Custom metadata. Maximum 1000 characters.

Request Sample 

{
 "payments":
 [
  {
   "amount":100,
   "collection_date":"2024-10-10",
   "description":"Payment",
   "mandate_id":"M0112AB34CD56EF781"
  },
  {
   "amount":200,
   "collection_date":"2024-10-10",
   "description":"Payment",
   "mandate_id":"M01187FE65DC43BA21"
  }
 ]
}

Response - Validation Successful

Response Parameters

Property Description
id The ID of the Record.
status Status of the API Request. Will be set as “Inserting”.
created_at Datetime formatted as ISO8601.
edited_at Datetime formatted as ISO8601.

Response Sample 

{
    "id": "RR0112AB34CD56EF78GH",
    "status": "Inserting",
    "created_at": "2024-10-08T15:57:14Z",
    "edited_at": "2024-10-08T15:57:14Z"
}

Note: The request would recieve a “202 Accepted” response - this means that the request itself has been successfully accepted, but at this point none of the line items have been processed.

Response - Validation Failed

If the request fails initial validation details will be provided on the reason. Up to 10 errors can be displayed.

In this example there is a problem with the first item in the list, identified by the system as position 1.
Position 2 would be the 2nd item in the list, etc.

Response Sample 

{
    "errors": [
        {
            "position": 1,
            "message": "date is in the past",
            "field": "credit_date"
        }
    ]
}

PUT

Action: Update a Payment.
Method: PUT
URL: https://api.smarterpaycloud.com/service.svc/payment/{ID}

{ID} denotes ID of record.

Request Parameters

Property Mandatory Description
auddis True The unique AUDDIS reference.
amount True Amount in pence – no decimal point
description True Reference description – will be included in outgoing email. Maximum 45 characters.
collection_date True Date to receive payment - 10 digit date in the format of “YYYY-MM-DD”
bacs_code False Bacs Code to apply to record, and related records, based on Rejection Profile actions. Can be an ARUDD Code or DDICA Code (Case insensitive, no space in code, for example “ddica3”) or empty (“”) to clear “bacs_reason_code”, “bacs_description”, “bacs_reference” and “bacs_filename” fields/values.
custom_reference False Custom reference set on record. Maximum 100 characters.
metadata False String for Custom metadata. Maximum 1000 characters.
status False Set the status of the payment. If bacs_code is also supplied this property will be ignored.

Request Sample 

{
 "payment":
  {
   "amount":100,
   "collection_date":"2018-08-25",
   "description":"metered bill",
   "auddis":"AUD00003435",
   "bacs_code":"ddica3",
   "custom_reference":"XYZ",
   "status":"failed",
   "metadata":""
  }
}

Response Parameters

Property Description
amount Amount
auddis Auddis reference
collection_date Date to receive payment - 10 digit date in the format of “YYYY-MM-DD”, corrected, if the date received by the service is a none banking day, weekend or national bank holiday
created_at Datetime formatted as ISO8601
custom_reference Custom reference set on record
default_narrative Text, associated with the transaction, which will be displayed in the customer's bank account. Maximum 18 characters.
description Reference description – will be included in outgoing email
id Unique identifier
mandate ID of the parent Mandate
payment_type Can be: “first_collection”, “ongoing_collection”, “final_collection”, “represent”, “ecommerce” or “MOTO”
record_type Can be: “direct_debit” or “card_payment”
related_payment This is the Payment id of the initial Failed Payment, only applicable for represented payments
status Can be: “pending_submission” ,“submitted”, “failed”, “successful” or “cancelled”
metadata Returns optional, custom, metadata, if set

Response Sample 

{
    "payment": {
        "amount": "2532",
        "auddis": "FBMAN02814872",
        "collection_date": "2022-05-19",
        "created_at": "2022-05-17T12:15:00Z",
        "custom_reference": "",
        "default_narrative": "",
        "description": "",
        "id": "P01YZ96J1D7WDK8NEWD",
        "mandate": "M01741EJ519Y51P3XGL",
        "payment_type": "ongoing collection",
        "record_type": "direct_debit",
        "related_payment": " ",
        "status": "successful",
        "metadata": ""
    }
}

GET (Singular)

Action: Return Payment details.
Method: GET
URL: https://api.smarterpaycloud.com/service.svc/payment/{ID}

{ID} denotes ID of record.

Response Parameters

Property Description
amount Amount
auddis Auddis reference
collection_date Date to receive payment - 10 digit date in the format of “YYYY-MM-DD”, corrected, if the date received by the service is a none banking day, weekend or national bank holiday
created_at Datetime formatted as ISO8601
custom_reference Custom reference set on record
default_narrative Text, associated with the transaction, which will be displayed in the customer's bank account. Maximum 18 characters.
description Reference description – will be included in outgoing email
id Unique identifier
mandate ID of the parent Mandate
payment_type Can be: “first_collection”, “ongoing_collection”, “final_collection”, “represent”, “ecommerce” or “MOTO”
record_type Can be: “direct_debit” or “card_payment”
related_payment This is the Payment id of the initial Failed Payment, only applicable for represented payments
status Can be: “pending_submission” ,“submitted”, “failed”, “successful” or “cancelled”
metadata Returns optional, custom, metadata, if set

Response Sample 

{
    "payment": {
        "amount": "2532",
        "auddis": "FBMAN02814872",
        "collection_date": "2022-05-19",
        "created_at": "2022-05-17T12:15:00Z",
        "custom_reference": "",
        "default_narrative": "",
        "description": "",
        "id": "P01YZ96J1D7WDK8NEWD",
        "mandate": "M01741EJ519Y51P3XGL",
        "payment_type": "ongoing collection",
        "record_type": "direct_debit",
        "related_payment": " ",
        "status": "successful",
        "metadata": ""
    }
}

GET (List)

Action: Return Payment details in a list.
Method: GET
URL: https://api.smarterpaycloud.com/service.svc/payments

Optional Parameters and filters are available, please see below.

Response Parameters

Property Description
amount Amount
auddis Auddis reference
collection_date Date to receive payment - 10 digit date in the format of “YYYY-MM-DD”, corrected, if the date received by the service is a none banking day, weekend or national bank holiday
created_at Datetime formatted as ISO8601
custom_reference Custom reference set on record
default_narrative Text, associated with the transaction, which will be displayed in the customer's bank account. Maximum 18 characters.
description Reference description – will be included in outgoing email
id Unique identifier
mandate ID of the parent Mandate
payment_type Can be: “first_collection”, “ongoing_collection”, “final_collection”, “represent”, “ecommerce” or “MOTO”
record_type Can be: “direct_debit” or “card_payment”
related_payment This is the Payment id of the initial Failed Payment, only applicable for represented payments
status Can be: “pending_submission” ,“submitted”, “failed”, “successful” or “cancelled”
metadata Returns optional, custom, metadata, if set

Response Sample 

{
    "payments": [
        {
            "amount": "1000",
            "auddis": "F05AR10M00000001",
            "collection_date": "2022-05-17",
            "created_at": "2022-05-12T11:27:35Z",
            "custom_reference": "",
            "default_narrative": "",
            "description": "Created By File Upload",
            "id": "P01RM9OPEGQR9W8024D",
            "mandate": "M017ZGLJLWL43QPW53E",
            "payment_type": "ongoing collection",
            "record_type": "direct_debit",
            "related_payment": " ",
            "status": "successful",
            "metadata": ""
        },
        {
            "amount": "1000",
            "auddis": "F05AR10M00000002",
            "collection_date": "2022-05-17",
            "created_at": "2022-05-12T11:27:35Z",
            "custom_reference": "",
            "default_narrative": "",
            "description": "Created By File Upload",
            "id": "P01Q0KN8XRYN7Q8OXZG",
            "mandate": "M013ZN7JWDQMN5PGEX5",
            "payment_type": "ongoing collection",
            "record_type": "direct_debit",
            "related_payment": " ",
            "status": "successful",
            "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: “custom_reference”,“id”,“status”,“card_id”,“mandate_id”,“created_at” (Default when not specified),“record_type”,“collection_date”,“customer_id”.
sort_order Specifies which order to sort on. Options are asc (ascending. Default when not specified) or desc (descending).
Filter Description
card_id Filter the list using the card_id. Matches will exactly match the provided value.
collection_date_from Filter the list with Collection date after the datetime supplied. Format is YYYY-MM-DD HH:MM:SS (2022-05-13 10:15:00).
collection_date_to Filter the list with Collection date before the datetime supplied. Format is YYYY-MM-DD HH:MM:SS (2022-05-13 10:15:00).
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_id Filter the list using the customer_id. Matches will exactly match the provided value.
custom_reference Filter the list using the custom_reference. Matches will contain the provided value.
id Filter the list using the id. Matches will exactly match the provided value.
mandate_id Filter the list using the mandate_id. Matches will exactly match the provided value.
record_type Filter the list using the record_type of the record. Can be a comma seperated list of required values. Options are “direct_debit”, “card_payment”.
status Filter the list using the status of the record. Can be a comma seperated list of required values. Options are “cancelled_by_payer”, “cancelled”, “error”, “failed”, “pending_submission”, “submitted”, “indemnity_claimed”, “successful”.
transaction_code Filter the list using the transaction_code of the record. Can be a comma seperated list of required values. Options are “01”, “17”, “18”, “19”
  • Last modified: 2024/10/16 16:51