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.
  • Last modified: 2024/11/22 11:12