Payment Link

Payment Link records contain link information, generated for the Ecommerce pages.

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

POST

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

Request Parameters

Property	Mandatory	Description
amount	False	See Note 2.
auddis	False	See Note 2.
bank_account	See Note 1	Bank Account ID.
bank_account_custom_reference	False	See Note 2. Maximum 100 characters.
card_payment_custom_reference	False	See Note 2. Maximum 100 characters.
customer_account	See Note 1	Customer Account ID.
customer_custom_reference	False	See Note 2. Maximum 100 characters.
description	False	See Note 2. Maximum 255 characters.
ecommerce_page	True	ecommerce_page id for the link generation.
end_date	False	See Note 2.
first_collection_amount	False	See Note 2.
first_collection_date	False	See Note 2.
mandate	See Note 1	Mandate ID.
metadata	False	String for custom metadata. Maximum 1000 characters.
metadata_account_validation	False	String for custom metadata to be set on Account Validation record. Maximum 1000 characters.
metadata_bank_account	False	String for custom metadata to be set on Bank Account record. Maximum 1000 characters.
metadata_card	False	String for custom metadata to be set on Card record. Maximum 1000 characters.
metadata_customer_account	False	String for custom metadata to be set on Customer Account record. Maximum 1000 characters.
metadata_mandate	False	String for custom metadata to be set on Mandate record. Maximum 1000 characters.
metadata_recurrence_schedule	False	String for custom metadata to be set on Recurrence Schedule record. Maximum 1000 characters.
recurrence_schedule_custom_reference	False	See Note 2. Maximum 100 characters.
recurrence_schedule	See Note 1	Recurrence Schedule ID.
return_url	False	See Note 2. Maximum 2048 characters.
start_date	False	See Note 2.

Note 1: Which ID is required will depend on the Ecommerce Page Setup as to what it is expecting.

Note 2: Optional parameters may be used to override values set either automatically by the system, such as Auddis reference for a Mandate or start date for a schedule, or defined in the Ecommerce Page, such as Amount or description. Which parameters that are available to override will depend on the Ecommerce Page Setup options selected.

Notes for “return_url”

The link must start with "https://" and be no longer than 2048 characters.
The link cannot contain a parameter called “page”, as this is always appended to the url. The “page” parameter contains the Ecommerce page record id used to signup.
The link cannot contain a parameter called “payment”, as this will be appended to the url if the link is created from an existing record. The “payment” parameter contains the payment link record id used to signup.

Request Sample

{
 "payment_link": 
  {
   "ecommerce_page": "EP02AB12CD34EF56GH78",
   "customer_account": "CA0112AB34CD56EF78GH"
  }
}

Response Parameters

Property	Description
account_validation_callback	Link requires Account Validation. Can be “true”, “false”.
amount	Link Amount, if set.
auddis	Mandate AUDDIS reference, if set.
bank_account	Bank Account ID, if set.
bank_account_custom_reference	Bank account customer reference, if set.
card_payment_custom_reference	Card Payment Custom reference, if set.
completed_at	Link completed at, if set.
created_at	Link creation date.
customer_account	Customer Account ID, if set.
description	Description in the link, if set.
ecommerce_page	Ecommerce Page ID.
end_date	Schedule end date, if set.
expiry	Link expiry date, if set.
first_collection_amount	Schedule first collection amount, if set.
first_collection_date	Schedule first collection date, if set.
id	Unique identifier for the record.
mandate	Mandate ID, if set.
metadata	String for custom metadata
metadata_account_validation	String for custom metadata to be set on Account Validation record
metadata_bank_account	String for custom metadata to be set on Bank Account record
metadata_card	String for custom metadata to be set on Card record
metadata_customer_account	String for custom metadata to be set on Customer Account record
metadata_mandate	String for custom metadata to be set on Mandate record
metadata_recurrence_schedule	String for custom metadata to be set on Recurrence Schedule record
recurrence_schedule	Schedule ID, if set.
recurrence_schedule_custom_reference	Schedule custom reference, if set.
return_url	Link return URL, if set.
start_date	Schedule start date, if set.
status	Link status. Can be “active”, “expired”.
url	Link URL.
visited_at	Link visited at date, if set.

Response Sample

{
    "payment_link": {
        "id": "PL01GOVWD48GD28N0M76",
        "url": "https://smarterpay-test-ecommerce.azurewebsites.net?setup=MJS44ChfVVOPuN68nbOvp9bsZrYtO6n1IAX9yKJAI4HtNxTPqJmj2PM%2BlSvd1Nv4vURbLe9s7EFtv5L0egYxV10Kuja5TM5xTtVnjKh5qGbNvJ2Ty%2BzIZp%2FnpHSgysP9&payment=KkaGURMTwUIAFcDQhNgVZv32B3%2Bn0uRPnvnvPLvffr8Q6ZVlBdsc1yjHFqyBxZd%2Fw7WQywzhG4B%2Bkvh%2FSYdWpWUC75uxF0IeaqK3cc6ZprUkM9pg2znX00jhejBBnrWx&page=455030324B4F354430473830584D504552573456",
        "amount": "2750",
        "description": "Payment Plan",
        "bank_account_custom_reference": null,
        "recurrence_schedule_custom_reference": null,
        "card_payment_custom_reference": null,
        "auddis": null,
        "customer_account": "CA01OQW39P4GY7J56NXL",
        "bank_account": null,
        "mandate": null,
        "recurrence_schedule": null,
        "ecommerce_page": "EP02KO5D0G80XMPERW4V",
        "status": "active",
        "expiry": "never",
        "return_url": null,
        "visited_at": null,
        "completed_at": null,
        "created_at": "2023-07-13 11:12:45",
        "account_validation_callback": false,
        "start_date": null,
        "end_date": null,
        "first_collection_amount": null,
        "first_collection_date": null,
        "metadata": null,
        "metadata_account_validation": null,
        "metadata_bank_account": null,
        "metadata_card": null,
        "metadata_customer_account": null,
        "metadata_mandate": null,
        "metadata_recurrence_schedule": null
    }
}

PUT

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

{ID} denotes ID of record.

Request Parameters

Property	Mandatory	Description
metadata	False	String for custom metadata. Maximum 1000 characters.
metadata_account_validation	False	String for custom metadata to be set on Account Validation record. Maximum 1000 characters.
metadata_bank_account	False	String for custom metadata to be set on Bank Account record. Maximum 1000 characters.
metadata_card	False	String for custom metadata to be set on Card record. Maximum 1000 characters.
metadata_customer_account	False	String for custom metadata to be set on Customer Account record. Maximum 1000 characters.
metadata_mandate	False	String for custom metadata to be set on Mandate record. Maximum 1000 characters.
metadata_recurrence_schedule	False	String for custom metadata to be set on Recurrence Schedule record. Maximum 1000 characters.
status	False	“expired” sets the link to be expired

Request Sample

{
 "payment_link": 
  {
   "status":"expired"
  }
}

Response Parameters

Property	Description
account_validation_callback	Link requires Account Validation. Can be “true”, “false”.
amount	Link Amount, if set.
auddis	Mandate AUDDIS reference, if set.
bank_account	Bank Account ID, if set.
bank_account_custom_reference	Bank account customer reference, if set.
card_payment_custom_reference	Card Payment Custom reference, if set.
completed_at	Link completed at, if set.
created_at	Link creation date.
customer_account	Customer Account ID, if set.
description	Description in the link, if set.
ecommerce_page	Ecommerce Page ID.
end_date	Schedule end date, if set.
expiry	Link expiry date, if set.
first_collection_amount	Schedule first collection amount, if set.
first_collection_date	Schedule first collection date, if set.
id	Unique identifier for the record.
mandate	Mandate ID, if set.
metadata	String for custom metadata
metadata_account_validation	String for custom metadata to be set on Account Validation record
metadata_bank_account	String for custom metadata to be set on Bank Account record
metadata_card	String for custom metadata to be set on Card record
metadata_customer_account	String for custom metadata to be set on Customer Account record
metadata_mandate	String for custom metadata to be set on Mandate record
metadata_recurrence_schedule	String for custom metadata to be set on Recurrence Schedule record
recurrence_schedule	Schedule ID, if set.
recurrence_schedule_custom_reference	Schedule custom reference, if set.
return_url	Link return URL, if set.
start_date	Schedule start date, if set.
status	Link status. Can be “active”, “expired”.
url	Link URL.
visited_at	Link visited at date, if set.

Response Sample

{
    "payment_link": {
        "id": "PL01GOVWD48GD28N0M76",
        "url": "https://smarterpay-test-ecommerce.azurewebsites.net?setup=MJS44ChfVVOPuN68nbOvp9bsZrYtO6n1IAX9yKJAI4HtNxTPqJmj2PM%2BlSvd1Nv4vURbLe9s7EFtv5L0egYxV10Kuja5TM5xTtVnjKh5qGbNvJ2Ty%2BzIZp%2FnpHSgysP9&payment=KkaGURMTwUIAFcDQhNgVZv32B3%2Bn0uRPnvnvPLvffr8Q6ZVlBdsc1yjHFqyBxZd%2Fw7WQywzhG4B%2Bkvh%2FSYdWpWUC75uxF0IeaqK3cc6ZprUkM9pg2znX00jhejBBnrWx&page=455030324B4F354430473830584D504552573456",
        "amount": "2750",
        "description": "Payment Plan",
        "bank_account_custom_reference": null,
        "recurrence_schedule_custom_reference": null,
        "card_payment_custom_reference": null,
        "auddis": null,
        "customer_account": "CA01OQW39P4GY7J56NXL",
        "bank_account": null,
        "mandate": null,
        "recurrence_schedule": null,
        "ecommerce_page": "EP02KO5D0G80XMPERW4V",
        "status": "active",
        "expiry": "never",
        "return_url": null,
        "visited_at": null,
        "completed_at": null,
        "created_at": "2023-07-13 11:12:45",
        "account_validation_callback": false,
        "start_date": null,
        "end_date": null,
        "first_collection_amount": null,
        "first_collection_date": null,
        "metadata": null,
        "metadata_account_validation": null,
        "metadata_bank_account": null,
        "metadata_card": null,
        "metadata_customer_account": null,
        "metadata_mandate": null,
        "metadata_recurrence_schedule": null
    }
}

GET (Singular)

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

{ID} denotes ID of record.

Response Parameters

Property	Description
account_validation_callback	Link requires Account Validation. Can be “true”, “false”.
amount	Link Amount, if set.
auddis	Mandate AUDDIS reference, if set.
bank_account	Bank Account ID, if set.
bank_account_custom_reference	Bank account customer reference, if set.
card_payment_custom_reference	Card Payment Custom reference, if set.
completed_at	Link completed at, if set.
created_at	Link creation date.
customer_account	Customer Account ID, if set.
description	Description in the link, if set.
ecommerce_page	Ecommerce Page ID.
end_date	Schedule end date, if set.
expiry	Link expiry date, if set.
first_collection_amount	Schedule first collection amount, if set.
first_collection_date	Schedule first collection date, if set.
id	Unique identifier for the record.
mandate	Mandate ID, if set.
metadata	String for custom metadata
metadata_account_validation	String for custom metadata to be set on Account Validation record
metadata_bank_account	String for custom metadata to be set on Bank Account record
metadata_card	String for custom metadata to be set on Card record
metadata_customer_account	String for custom metadata to be set on Customer Account record
metadata_mandate	String for custom metadata to be set on Mandate record
metadata_recurrence_schedule	String for custom metadata to be set on Recurrence Schedule record
recurrence_schedule	Schedule ID, if set.
recurrence_schedule_custom_reference	Schedule custom reference, if set.
return_url	Link return URL, if set.
start_date	Schedule start date, if set.
status	Link status. Can be “active”, “expired”.
url	Link URL.
visited_at	Link visited at date, if set.

Response Sample

{
    "payment_link": {
        "id": "PL01GOVWD48GD28N0M76",
        "url": "https://smarterpay-test-ecommerce.azurewebsites.net?setup=MJS44ChfVVOPuN68nbOvp9bsZrYtO6n1IAX9yKJAI4HtNxTPqJmj2PM%2BlSvd1Nv4vURbLe9s7EFtv5L0egYxV10Kuja5TM5xTtVnjKh5qGbNvJ2Ty%2BzIZp%2FnpHSgysP9&payment=KkaGURMTwUIAFcDQhNgVZv32B3%2Bn0uRPnvnvPLvffr8Q6ZVlBdsc1yjHFqyBxZd%2Fw7WQywzhG4B%2Bkvh%2FSYdWpWUC75uxF0IeaqK3cc6ZprUkM9pg2znX00jhejBBnrWx&page=455030324B4F354430473830584D504552573456",
        "amount": "2750",
        "description": "Payment Plan",
        "bank_account_custom_reference": null,
        "recurrence_schedule_custom_reference": null,
        "card_payment_custom_reference": null,
        "auddis": null,
        "customer_account": "CA01OQW39P4GY7J56NXL",
        "bank_account": null,
        "mandate": null,
        "recurrence_schedule": null,
        "ecommerce_page": "EP02KO5D0G80XMPERW4V",
        "status": "active",
        "expiry": "never",
        "return_url": null,
        "visited_at": null,
        "completed_at": null,
        "created_at": "2023-07-13 11:12:45",
        "account_validation_callback": false,
        "start_date": null,
        "end_date": null,
        "first_collection_amount": null,
        "first_collection_date": null,
        "metadata": null,
        "metadata_account_validation": null,
        "metadata_bank_account": null,
        "metadata_card": null,
        "metadata_customer_account": null,
        "metadata_mandate": null,
        "metadata_recurrence_schedule": null
    }
}

GET (List)

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

Optional Parameters and filters are available, please see below.

Response Parameters

Property	Description
account_validation_callback	Link requires Account Validation. Can be “true”, “false”.
amount	Link Amount, if set.
auddis	Mandate AUDDIS reference, if set.
bank_account	Bank Account ID, if set.
bank_account_custom_reference	Bank account customer reference, if set.
card_payment_custom_reference	Card Payment Custom reference, if set.
completed_at	Link completed at, if set.
created_at	Link creation date.
customer_account	Customer Account ID, if set.
description	Description in the link, if set.
ecommerce_page	Ecommerce Page ID.
end_date	Schedule end date, if set.
expiry	Link expiry date, if set.
first_collection_amount	Schedule first collection amount, if set.
first_collection_date	Schedule first collection date, if set.
id	Unique identifier for the record.
mandate	Mandate ID, if set.
metadata	String for custom metadata
metadata_account_validation	String for custom metadata to be set on Account Validation record
metadata_bank_account	String for custom metadata to be set on Bank Account record
metadata_card	String for custom metadata to be set on Card record
metadata_customer_account	String for custom metadata to be set on Customer Account record
metadata_mandate	String for custom metadata to be set on Mandate record
metadata_recurrence_schedule	String for custom metadata to be set on Recurrence Schedule record
recurrence_schedule	Schedule ID, if set.
recurrence_schedule_custom_reference	Schedule custom reference, if set.
return_url	Link return URL, if set.
start_date	Schedule start date, if set.
status	Link status. Can be “active”, “expired”.
url	Link URL.
visited_at	Link visited at date, if set.

Response Sample

{
    "payment_links": [
        {
            "id": "PL01EXYR6K8K9Y84ZLQV",
            "url": "https://smarterpay-test-ecommerce.azurewebsites.net?setup=MJS44ChfVVOPuN68nbOvp9bsZrYtO6n1IAX9yKJAI4HtNxTPqJmj2PM%2BlSvd1Nv4vURbLe9s7EFtv5L0egYxV10Kuja5TM5xTtVnjKh5qGbNvJ2Ty%2BzIZp%2FnpHSgysP9&payment=iZ5KexxAyj%2BcFdHVzrgwsQz59pnX%2FfIkAtYvXkA%2B7n0eccbnq5i3qmyZLqpVs2AJQ6wnK5JeuIhR3IQXt3Jhuznoprs7hsFGrkYUS%2BVkvjiLJJIzJbsOommmUSuveAnn&page=455030324B4F354430473830584D504552573456",
            "amount": "2750",
            "description": "Payment Plan",
            "bank_account_custom_reference": null,
            "recurrence_schedule_custom_reference": null,
            "card_payment_custom_reference": null,
            "auddis": null,
            "customer_account": "CA016YQRDJZW9KJVL359",
            "bank_account": "BA01VQY3LJO0NLPE61OG",
            "mandate": null,
            "recurrence_schedule": null,
            "ecommerce_page": "EP02KO5D0G80XMPERW4V",
            "status": "expired",
            "expiry": "2023-07-12 12:48:37",
            "return_url": null,
            "visited_at": null,
            "completed_at": null,
            "created_at": "2023-07-12 12:18:37",
            "account_validation_callback": false,
            "start_date": null,
            "end_date": null,
            "first_collection_amount": null,
            "first_collection_date": null,
            "metadata": null,
            "metadata_account_validation": null,
            "metadata_bank_account": null,
            "metadata_card": null,
            "metadata_customer_account": null,
            "metadata_mandate": null,
            "metadata_recurrence_schedule": null
        },
        {
            "id": "PL01GOVWD48GD28N0M76",
            "url": "https://smarterpay-test-ecommerce.azurewebsites.net?setup=MJS44ChfVVOPuN68nbOvp9bsZrYtO6n1IAX9yKJAI4HtNxTPqJmj2PM%2BlSvd1Nv4vURbLe9s7EFtv5L0egYxV10Kuja5TM5xTtVnjKh5qGbNvJ2Ty%2BzIZp%2FnpHSgysP9&payment=KkaGURMTwUIAFcDQhNgVZv32B3%2Bn0uRPnvnvPLvffr8Q6ZVlBdsc1yjHFqyBxZd%2Fw7WQywzhG4B%2Bkvh%2FSYdWpWUC75uxF0IeaqK3cc6ZprUkM9pg2znX00jhejBBnrWx&page=455030324B4F354430473830584D504552573456",
            "amount": "2750",
            "description": "Payment Plan",
            "bank_account_custom_reference": null,
            "recurrence_schedule_custom_reference": null,
            "card_payment_custom_reference": null,
            "auddis": null,
            "customer_account": "CA01OQW39P4GY7J56NXL",
            "bank_account": null,
            "mandate": null,
            "recurrence_schedule": null,
            "ecommerce_page": "EP02KO5D0G80XMPERW4V",
            "status": "active",
            "expiry": "never",
            "return_url": null,
            "visited_at": null,
            "completed_at": null,
            "created_at": "2023-07-13 11:12:45",
            "account_validation_callback": false,
            "start_date": null,
            "end_date": null,
            "first_collection_amount": null,
            "first_collection_date": null,
            "metadata": null,
            "metadata_account_validation": null,
            "metadata_bank_account": null,
            "metadata_card": null,
            "metadata_customer_account": null,
            "metadata_mandate": null,
            "metadata_recurrence_schedule": null
        }
    ]
}

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: “id”,“type”,“created_at” (Default when not specified).
sort_order	Specifies which order to sort on. Options are asc (ascending. Default when not specified) or desc (descending).

Filter	Description
auddis	Filter the list using the auddis. Matches will contain the provided value.
bank_account_custom_reference	Filter the list using the bank_account_custom_reference. Matches will contain the provided value.
bank_account_id	Filter the list using the bank_account_id. Matches will exactly match the provided value.
card_payment_custom_reference	Filter the list using the card_payment_custom_reference. Matches will contain the provided value.
customer_account_id	Filter the list using the customer_account_id . Matches will exactly match the provided value.
customer_custom_reference	Filter the list using the customer_custom_reference. Matches will contain the provided value.
ecommerce_page_id	Filter the list using the ecommerce_page_id. Matches will exactly match 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.
recurrence_schedule_custom_reference	Filter the list using the recurrence_schedule_custom_reference. Matches will contain the provided value.
recurrence_schedule_id	Filter the list using the recurrence_schedule_id. Matches will exactly match the provided value.