Credit

Credit records represent a BACS Credit, this is not a refund against any one Direct Debit collection. Credits can be used for Bill payments, payroll or indeed to make a genuine refund.

If SmarterPay Cloud receives a Credit message with credit_date set to a none banking date (weekend or national bank holiday), SmartyerPay Cloud will record/store the Payment record with next available banking day, and return this date in the response. For example the following POST request, sets the “credit_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.

When creating a credit you must supply an AUDDIS ID or a Client Bank Account ID, if neither is supplied the default SUN and default Client Bank Account for your client will be attached to the credit

Method Purpose
POST Create a Credit
PUT Update a Credit
GET (Singular) Return Credit details
GET (List) Retrieve Credit details in a list

POST

Action: Create a Credit.
Method: POST
URL: https://api.smarterpaycloud.com/service.svc/credit

Action: Create a Credit.
Request Parameters

Property Mandatory Description
auddis See Notes The unique AUDDIS ref.
client_bank_account_id See Notes The ID of the client bank account
amount True Amount in pence – no decimal point
description True Reference description – will be included in outgoing email
credit_date True Date to receive payment - 10 digit date in the format of “YYYY-MM-DD”
default_narrative False Text, associated with the transaction, which will be displayed in the customers Bank Account. Maximum 18 characters.
bank_account See Notes This is the customers bank account record, this is mandatory if no auddis is supplied
reference False Custom reference set on record
rti False Is used for Payroll Credits. Maximum of 4 characters. Can only contain “/” Slash, “A–Z” uppercase Alpha characters, “0–9” Numeric characters or “.” Full stop.
submission_reference False The Credit reference that will be sent to bacs. Minumum of 6 characters. Maximum of 18 characters. Valid characters A–Z (Alpha characters), 0–9 (Numeric characters), “.” (Full stop), “&” (Ampersand), “/” (Slash), “-” (Hyphen), “ ” (Blank space). Non-valid characters will be replaced with spaces.
metadata False String for Custom metadata

Notes:

In order for a credit to be created, the system needs to know which Client Bank Account and which Customer Bank Account to use.

  • Auddis:
    • “auddis”, if supplied will link the Credit to the Mandate.
  • Client Bank Account - The system can get this from:
    • The default Client Bank Account on the default SUN, if “auddis” and “client_bank_account_id” are not supplied.
    • The “auddis”, if supplied.
    • The “client_bank_account_id”, if supplied.
    • NOTE: If “auddis” and “client_bank_account_id” are both supplied, the system will use “client_bank_account_id”.
  • Customer Bank Account - The system can get this from:
    • The “auddis”, if supplied.
    • The “bank_account”, if supplied.
    • NOTE: If “auddis” and “bank_account” are supplied, the system will use “auddis”.

Valid data combinations of “auddis”, “bank_account” and “client_bank_account_id” to supply Client Bank Account and Customer Bank Account details:

  • “auddis” only:
    • Link the Credit to the Mandate.
    • Use the Client Bank Account from the Mandate.
    • Use the Customer Bank Account from the Mandate.
  • “auddis” and “client_bank_account_id:
    • Link the Credit to the Mandate.
    • Use the Customer Bank Account from the Mandate.
    • Override the Client Bank Account with the one specified.
  • “bank_account” only:
    • Don't link to a Mandate.
    • Use the default Client Bank Account set in the system.
    • Use the Customer Bank Account specified.
  • “bank_account” and “client_bank_account_id”:
    • Don't link to a Mandate.
    • Use the Customer Bank Account specified.
    • Use the Client Bank Account specified.

Request Sample 

{
 "credit":
  {
   "amount":100,
   "credit_date":"2018-08-25",
   "description":"metered bill",
   "auddis":"AUD00003435",
   "client_bank_account_id":"CBA-0000003",
   "bank_account":"CBA-0000003",
   "reference": "manual refund",
   "default_narrative": "SP22-01",
   "rti":"/123",
   "submission_reference": "abc123def",
   "metadata": ""
  }
}

Response Parameters

Property Description
id The ID of the Record.
Sun_Name Originating SUN Name.
Sun_Number Originiting Service User Number (SUN).
amount Amount, in pence.
auddis Unique auddis identifier.
bank_account Customer Bank Account ID.
client_bank_account_id Originating Bank Account ID.
created_at Datetime formatted as ISO8601.
credit_date Date to send payment - 10 digit date in the format of “YYYY-MM-DD”.
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.
reference Custom reference set on record.
rti Is used for Payroll Credits. Maximum of 4 characters. Can only contain “/” Slash, “A–Z” uppercase Alpha characters, “0–9” Numeric characters or “.” Full stop.
status This should always start with “pending_submission” and then change to “submitted”, can also be “failed”,“successful” or “cancelled”.
submission_reference The Credit reference that is sent to bacs.
metadata Returns optional, custom, metadata, if set

Response Sample 

{
    "credit": {
        "ID": "CR01EXYR6K8K6V84ZLQV",
        "Sun_Name": "Smarterpay Test",
        "Sun_Number": "100263",
        "amount": "100",
        "auddis": "",
        "bank_account": "BA01RM741EJ5QQ83XGLW",
        "client_bank_account_id": "CBA-0000002",
        "created_at": "2023-03-23T16:49:29Z",
        "credit_date": "2023-04-20",
        "default_narrative": "",
        "description": "metered bill",
        "reference": "manual refund",
        "status": "pending_submission",
        "rti": "",
        "submission_reference": "CRR8K6V8",
        "metadata":""
    }
}

PUT

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

{ID} denotes ID of record.

Request Parameters

Property Mandatory Description
amount True Amount in pence – no decimal point
description True Reference description – will be included in outgoing email
credit_date True Date to receive payment - 10 digit date in the format of “YYYY-MM-DD”
status False This should always start with “pending_submission” and then change to “submitted”, can also be “failed”,”successful“ or “cancelled”
reference False Custom reference set on record
rti False Is used for Payroll Credits. Maximum of 4 characters. Can only contain ”/“ Slash, “A–Z” uppercase Alpha characters, “0–9” Numeric characters or ”.“ Full stop.
metadata False String for Custom metadata

Request Sample 

{
 "credit":
  {
   "amount":100,
   "credit_date":"2018-08-25",
   "description":"metered bill",
   "status":"cancelled",
   "reference": "manual refund",
   "rti":"/123",
   "metadata": ""
  }
}

Response Parameters

Property Description
id The ID of the Record.
Sun_Name Originating SUN Name.
Sun_Number Originiting Service User Number (SUN).
amount Amount, in pence.
auddis Unique auddis identifier.
bank_account Customer Bank Account ID.
client_bank_account_id Originating Bank Account ID.
created_at Datetime formatted as ISO8601.
credit_date Date to send payment - 10 digit date in the format of “YYYY-MM-DD”.
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.
reference Custom reference set on record.
rti Is used for Payroll Credits. Maximum of 4 characters. Can only contain “/” Slash, “A–Z” uppercase Alpha characters, “0–9” Numeric characters or “.” Full stop.
status This should always start with “pending_submission” and then change to “submitted”, can also be “failed”,“successful” or “cancelled”.
submission_reference The Credit reference that is sent to bacs.
metadata Returns optional, custom, metadata, if set

Response Sample 

{
    "credit": {
        "ID": "CR01EXYR6K8K6V84ZLQV",
        "Sun_Name": "Smarterpay Test",
        "Sun_Number": "100263",
        "amount": "100",
        "auddis": "",
        "bank_account": "BA01RM741EJ5QQ83XGLW",
        "client_bank_account_id": "CBA-0000002",
        "created_at": "2023-03-23T16:49:29Z",
        "credit_date": "2023-04-20",
        "default_narrative": "",
        "description": "metered bill",
        "reference": "manual refund",
        "status": "pending_submission",
        "rti": "",
        "submission_reference": "CRR8K6V8",
        "metadata":""
    }
}

GET (Singular)

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

{ID} denotes ID of record.

Response Parameters

Property Description
id The ID of the Record.
Sun_Name Originating SUN Name.
Sun_Number Originiting Service User Number (SUN).
amount Amount, in pence.
auddis Unique auddis identifier.
bank_account Customer Bank Account ID.
client_bank_account_id Originating Bank Account ID.
created_at Datetime formatted as ISO8601.
credit_date Date to send payment - 10 digit date in the format of “YYYY-MM-DD”.
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.
reference Custom reference set on record.
rti Is used for Payroll Credits. Maximum of 4 characters. Can only contain “/” Slash, “A–Z” uppercase Alpha characters, “0–9” Numeric characters or “.” Full stop.
status This should always start with “pending_submission” and then change to “submitted”, can also be “failed”,“successful” or “cancelled”.
submission_reference The Credit reference that is sent to bacs.
metadata Returns optional, custom, metadata, if set

Response Sample 

{
    "credit": {
        "ID": "CR01EXYR6K8K6V84ZLQV",
        "Sun_Name": "Smarterpay Test",
        "Sun_Number": "100263",
        "amount": "100",
        "auddis": "",
        "bank_account": "BA01RM741EJ5QQ83XGLW",
        "client_bank_account_id": "CBA-0000002",
        "created_at": "2023-03-23T16:49:29Z",
        "credit_date": "2023-04-20",
        "default_narrative": "",
        "description": "metered bill",
        "reference": "manual refund",
        "status": "pending_submission",
        "rti": "",
        "submission_reference": "CRR8K6V8",
        "metadata":""
    }
}

GET (List)

Action: Return Credit details in as list.
Method: GET
URL: https://api.smarterpaycloud.com/service.svc/credits

Optional Parameters and filters are available, please see below.

Response Parameters

Property Description
id The ID of the Record.
Sun_Name Originating SUN Name.
Sun_Number Originiting Service User Number (SUN).
amount Amount, in pence.
auddis Unique auddis identifier.
bank_account Customer Bank Account ID.
client_bank_account_id Originating Bank Account ID.
created_at Datetime formatted as ISO8601.
credit_date Date to send payment - 10 digit date in the format of “YYYY-MM-DD”.
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.
reference Custom reference set on record.
rti Is used for Payroll Credits. Maximum of 4 characters. Can only contain “/” Slash, “A–Z” uppercase Alpha characters, “0–9” Numeric characters or “.” Full stop.
status This should always start with “pending_submission” and then change to “submitted”, can also be “failed”,“successful” or “cancelled”.
submission_reference The Credit reference that is sent to bacs.
metadata Returns optional, custom, metadata, if set

Response Sample 

{
    "credits": [
        {
            "ID": "CR01EXYR6K8KXYP4ZLQV",
            "Sun_Name": "Smarterpay Test",
            "Sun_Number": "100263",
            "amount": "0",
            "auddis": "",
            "bank_account": "BA01O6YQRDJZRK8VL359",
            "client_bank_account_id": "CBA-0000002",
            "created_at": "2023-03-16T16:45:57Z",
            "credit_date": "2023-04-04",
            "default_narrative": "",
            "description": "Created By File Upload",
            "reference": "",
            "status": "cancelled",
            "rti": "",
            "submission_reference": "CRR8KXYP",
            "metadata":""
        },
        {
            "ID": "CR01GOVWD48GX2JN0M76",
            "Sun_Name": "Smarterpay Test",
            "Sun_Number": "100263",
            "amount": "0",
            "auddis": "",
            "bank_account": "BA01O6YQRDJZRK8VL359",
            "client_bank_account_id": "CBA-0000002",
            "created_at": "2023-03-17T09:04:46Z",
            "credit_date": "2023-04-04",
            "default_narrative": "",
            "description": "Created By File Upload",
            "reference": "",
            "status": "cancelled",
            "rti": "",
            "submission_reference": "CRR8GX2J",
            "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“,”customer_id“,”bank_account_id“,”created_at“ (Default when not specified),”credit_date“
sort_order Specifies which order to sort on. Options are asc (ascending. Default when not specified) or desc (descending).
Filter Description
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).
credit_date_from Filter the list with Credit date after the datetime supplied. Format is YYYY-MM-DD HH:MM:SS (2022-05-13 10:15:00).
credit_date_to Filter the list with Credit date 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.
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.
status Filter the list using the status of the record. Can be a comma seperated list of required values. Options are “failed”, “pending_submission”, “submitted”, “successful”.
  • Last modified: 2023/12/07 13:55