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	Create a Payment
PUT	Update a Payment
GET (Singular)	Return Payment details
GET (List)	Return Payment details in a list

POST

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
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
default_narrative	False	Text, associated with the transaction, which will be displayed in the customers Bank Account. Maximum 18 characters.
metadata	False	String for Custom metadata

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 customers 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": ""
    }
}

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
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
metadata	False	String for Custom metadata
status	False	Set the status of the payment

Request Sample

{
 "payment":
  {
   "amount":100,
   "collection_date":"2018-08-25",
   "description":"metered bill",
   "auddis":"AUD00003435",
   "original_payment_id":"PAY00003432",
   "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 customers 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": ""
    }
}

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 customers 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": ""
    }
}

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 customers 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”

Payment

POST

PUT

GET (Singular)

GET (List)