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 (Singular) | Create a Credit |
| POST (List) | Create Credits from a list |
| PUT | Update a Credit |
| GET (Singular) | Return Credit details |
| GET (List) | Retrieve Credit details in a list |
POST (Singular)
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. Maximum 100 characters. |
| 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 customer's 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. Maximum 45 characters. |
| 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. Minimum 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. Maximum 1000 characters. |
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":""
}
}
POST (List)
Action: Create Credits from a list.
Method: POST
URL: https://api.smarterpaycloud.com/service.svc/credits
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 Credits from a list.
Request Parameters
| Property | Mandatory | Description |
|---|---|---|
| mandate_id | See Notes | The ID of the Mandate record |
| client_bank_account_id | See Notes | The ID of the client bank account record |
| amount | True | Amount in pence – no decimal point |
| description | True | Reference description – will be included in outgoing email. Maximum 100 characters |
| 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 customer's bank account. Maximum 18 characters |
| bank_account | See Notes | This is the customers bank account record, this is mandatory if no auddis is supplied |
| custom_reference | False | Custom reference set on record. Maximum 45 characters |
| 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. Minimum 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. Maximum 1000 characters |
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.
- Mandate ID:
- “mandate_id”, 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 “mandate_id” and “client_bank_account_id” are not supplied.
- The “mandate_id”, if supplied.
- The “client_bank_account_id”, if supplied.
- NOTE: If “mandate_id” 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 “mandate_id”, if supplied.
- The “bank_account”, if supplied.
- NOTE: If “mandate_id” and “bank_account” are supplied, the system will use “mandate_id”.
Valid data combinations of “mandate_id”, “bank_account” and “client_bank_account_id” to supply Client Bank Account and Customer Bank Account details:
- “mandate_id” only:
- Link the Credit to the Mandate.
- Use the Client Bank Account from the Mandate.
- Use the Customer Bank Account from the Mandate.
- “mandate_id” 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
{
"credits":
[
{
"amount":100,
"credit_date":"2024-10-10",
"description":"metered bill",
"client_bank_account_id":"CBA-0000001",
"bank_account":"BA01123456789ABC"
},
{
"amount":200,
"credit_date":"2024-10-10",
"description":"metered bill",
"client_bank_account_id":"CBA-0000002",
"bank_account":"BA01DEF987654321"
}
]
}
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": "collection_date"
}
]
}
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. Maximum 100 characters. |
| credit_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 ARUCS Code or AWACS Code (Case insensitive, no space in code, for example “arucs2”) or empty (“”) to clear “bacs_reason_code”, “bacs_description”, “bacs_reference” and “bacs_filename” fields/values. |
| status | False | This should always start with “pending_submission” and then change to “submitted”, can also be “failed”,“successful” or “cancelled”. If bacs_code is also supplied this property will be ignored. |
| reference | False | Custom reference set on record. Maximum 45 characters. |
| 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. Maximum 1000 characters. |
Request Sample
{
"credit":
{
"amount":100,
"credit_date":"2018-08-25",
"description":"metered bill",
"bacs_code":"arucs2",
"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: 2024/10/16 17:01