Introduction

In Spindle Document Distribution v9 Draycir introduced PayThem 2, an improved method for requesting payments via documents distributed through Spindle Document Distribution. As a result, the original PayThem functionality in Spindle Document Distribution is now known as 'Legacy PayThem'

Draycir PayThem has two methods for creating a payment request, which can be broadly summarised as the Invoice method and the Basic Statement method.

The Invoice method

Draycir PayThem 2 functions in the same way as Legacy PayThem, in that all details of the request are provided, Amount, Customer details, Customer address details, delivery address details, currency, payment terms etc. and a single payment request is created. The request is registered with a Transaction Custom Host ID.

You would use this method for any document that has a single defined amount to pay, typically invoices, pro formas etc.

The Basic Statement method

When using a Basic Statement document type in PayThem, we only provide basic information for each invoice on the statement. Part of this is the Transaction Custom Host Id for the invoice in question. PayThem will create a new request that encompasses the previously processed invoices. This allows the customer to pay the whole of the statement in one go, or to select the invoices to be paid individually. 

You would use this method for documents that group multiple invoices, such as Statements and credit control letters.

Note that the invoices referred to on the document must already be present in PayThem.

This method was introduced in Spindle Document Distribution v10.3

Requirements

• Spindle Document Distribution or Spindle Document Management v9 and later (v10.3+ required for the Statement document type)
• A Draycir account login (contact licences@draycir.com)
• Login Details for the chosen payment provider

Note for users migrating from Legacy PayThem to PayThem 2 using Opayo as a payment provider:

To allow card payments to be received, you must enable 3DSecure in your Opayo / SagePay admin portal. If you have not previously enabled 3DSecure, please contact Opayo support. Please be advised that this process can take a number of days.

Process

Overview of the process

• Create the PayThem 2 company
  • Company Details and website details
  • Logo
  • Configure Payment Provider
  • Configure Preferences
  • Adding users
  • Configure Email Notifications
• Add PayThem method to the Document Operation
  • Connect PayThem 2 to Spindle Document Distribution
  • Link the ERP document to Spindle Document Distribution
  • Spindle Document Distribution Commands
  • Placing the Pay Now button

Create the PayThem 2 company

Open the Draycir PayThem portal at https://my.paythem.co 

Log in to the Draycir account system with the credentials obtained from Draycir Administration

A Default Dataset will be created for you . We will not use this dataset, instead we will create a new dataset.

Click Companies from the menu in the left hand side.

Add a new company

For Sage 200 sites, set the Host ID and the Custom ID to the company number as shown in Sage 200 Administration. For other ERPs, set a unique identifier for each company in the ERP. You will need to populate the ##DATASETID...## command on the document with this value.

Click Add and the company will be initialised and created. This will take a few moments.

Once active, select the company from the list in the upper right:

(Note: Please do not ignore the above step. If it is ignored, all config will be applied to the Default Dataset, which is not used by the user. The company must be selected before adding the details)

You are now ready to start configuring PayThem

Company Settings

Enter company information and add a company logo. This is shown in on the customer payment screens, to give confidence to your customers that they are paying your company.

Company settings can be found under the Management section in the bottom left-hand corner of the menu. Click on the icon and when the menu appears click on Company Settings 

Please note that the website must include http:// or https://

Configure Payment Provider

Next, configure the payment provider in the portal. Click on Payment Providers and choose New Provider Configuration:

Each provider has its own configuration methods, but these are laid out in the pages displayed:

Transsafe

Stripe

Opayo (formerly SagePay)

For Opayo as a payment provider, there is an additional Options panel:

This allows you to set the VendorTxCode that is passed to Opayo and appears in the Opayo Portal. 

Random Characters will use a 35-character GUID, for example: 7dd1987c-eb55-4fad-b979-48419eca6cfa

Payment Reference will use a number derived from the account reference and the invoice number.

Using account ABB001 and invoice INV12345 as the account number and invoice number:

• For the initial payment of a request, the ID will be ABB001INV12345. If that payment is the only one, then that is it.
• Any additional payment of the same request would generate an ID such as  ABB001INV12345-sTw (ie, it will have a random 3-character code appended).
  • Behind the scenes, the system makes a call to Opayo with ABB001INV12345, gets notified that this payment already exists and then tries again with the suffix appended. As there are 238,328 (62^3) combinations of three alphanumeric characters, it is extremely unlikely that the random 3-letter code will already exist and so we only need to make two calls to the Opayo server. The software is designed to make up to 20 such retries and the likelihood of it hitting 20 successive pre-existing IDs is practically nil, but if that does happen, the system will drop back to using a GUID.
• For requests with multiple transactions (eg Statements) or for requests at account level (with no related transactions) the system will just use the Account reference, followed by the random three characters, eg: ABB001-d5L

At any point, if a valid transactionID using the account and/or transaction details cannot be created, the system will fall back to a GUID.

The default for new payment providers is Payment Reference, and we recommend leaving this option selected.

Total Processing

Using multiple payment providers

PayThem allows you to specify multiple payment providers in the portal, and to use filter criteria to present the customer with the most appropriate provider.

For example you may want to only allow Opayo to be used for payments up to £1000, and Total Processing to be used for amounts greater, or you may want to use Stripe for USD customers, and TrueLayer for EUR and GBP customers.

This is configured in the Filters window:

Configure Preferences

In Preferences, configure certain preferences for payment pages; such as default country and changes that customers can make to the payment page.

Default Country - This country will be used if no country is provided on the document.

Can Payments be Edited - This option allows the recipient to modify the amount they will pay for any given payment request. If this is set to allow payments to be edited, then we recommend also setting the usage type to Multiple (see below)

Allow Transaction Currency To Change- Allows a request to be paid with a diferent currency

Default Link Expires Time - You can specify any number of weeks/months/years in which a payment request can be used.

Default Usage Type - Either Single or Multiple, this allows a payment request to be either sinlge-use or accessible multiple times, and if the payments can be edited, we recommend that this is set to Multiple

Users

Users can be found under the Management section in the bottom left-hand corner of the menu. Click on Users. 

To add a user following these steps.

1. Go to Management > Users .
2. Click New User in the bottom left-hand corner.
3. Enter the Name and the Email address of the user you want to add.
4. Select the Role they should be, either an a Administrator or a Standard user (see below for the differences between the user types).
5. Click the Invite User button.
6. You will return back to the user list and a notification bar should appear stating the user has been created.
7. The user should receive an email asking them to accept the invitation to join as a PayThem user.

To edit a user follow these steps.

1. Go to Management > Users 
2. From the user list, click on the three dots to far right of the user's name.
3. Click on Edit 
4. You can edit the Name of the user but you cannot change the email address.
5. You can change the Role of the user
6. Once you are happy with your changes, click Save Changes
7. You will return back to the user list and a notification bar should appear stating the user has been updated.

To remove a user follow these steps.

1. Go to Management > Users (see above).
2. From the user list, click three dots to the far right of the user's name you want to remove.
3. Click on Delete 

Configure Email Notifications

You can configure PayThem to send email notifications when certain events have occurred. These events include successful and failed payments, as well as any pending payments. All PayThem User notifications are turned off by default.

Some customer notifications are enabled by default.

Notification Types

You can change each notification status by clicking on the switch. A yellow switch indicates the notification is on, while a grey switch indicates a notification is off.

Notification Users

A notification user can either be a registered user in the PayThem admin portal (see Users) or simply an email address (for example, accounts@mycompany.com). When a notification event occurs, PayThem will send an email to all notification users in the drop-down list that has that notification enabled.

Add a Notification User

1. Click the Add Notification User button
2. When the dialog appears, select PayThem User or Email Address drop-down
3. Select the user you want to add from the Select PayThem User drop-down or type in the email address
4. Click Add User

Remove a Notification User

1. Select the user you want to remove in the Select User to Configure drop-down.
2. Click the User Options button.
3. Choose Delete Selected User
4. When the confirmation dialog appears, click Delete Selected User

Add PayThem method to the Document Operation

Connect PayThem 2 to Spindle Document Distribution

To link this instance of PayThem 2 to Spindle Document Distribution, you use the Access key.

API Keys can be found under the Management section in the bottom left-hand corner of the menu. Click on API Keys.

Create an API Key

To create an API key follow these steps.

1. Go to Management> API Keys (see above).
2. Click Add API Key in the bottom left-hand corner.
3. The new API key will appear in the on screen list

Copy an API Key

To copy an API key follow these steps.

1. Go to Management > API Keys (see above).
2. Click the Copy Icon to the far right of the key you wish to copy.
3. This key can now be pasted into Spindle

Paste it into the licence window of Server Administration, if using Spindle Document Management:

Or in Spindle Document Distribution Tools, if using Spindle Document Distribution Standalone :

Link the ERP document to Spindle Document Distribution

You will need two integration services in Spindle Document Distribution, one to support Invoice-style documents and one for Statrement-style documents. 

Invoice Style

In Spindle Document Distribution Tools, open Integration Manager and right click to create a new PayThem Service, selecting Draycir PayThem from the drop-down menu:

Name the PayThem service, choose the source application, enable the buttons and links, and optionally set whether the document is to be uploaded to the portal (see Uploading Documents below): 

Next switch to the Configuration tab:

Set the Document Type to Invoice and set the commands that will be used to populate the request to the payment provider. As with Legacy PayThem, red text indicates a required field, but any additional data fields you can populate will improve the end-user experience. The commands to use will depend on the ERP in use and its report designer. We have provided example expressions for Sage 200 below.

The Button tab allows you to specify the appearance of the PayThem button:

The Advanced Tab allows you to specify where on the document PayThem will look for its data:

The top option is our recommendation, the other options are present for backwards compatibility with earlier possible configurations. Unless you know you need to change this, you do not need to change this.

Statements

Create a second Integration service to handle statement data. Select Basic Statement from the dropdown menu:

Note that the statement integration requires fewer fields than the invoice method, as it will be using the data from the existing invoice requests. 

Configure the remaining tabs (Buttton, Advanced) in a similar manner as for Invoices.

Spindle Document Distribution Commands

Sage 200

The commands below are applicable to a default Sage 200 environment. If you have made any modifications to the commands on the layouts, you may need to amend these and the commands used in the Intergration Manager so that they still match. 

Invoices:

"##VAR31 " + SOPInvCredAddresses.C_AddressLine1 + "## ##VAR32 " + SOPInvCredAddresses.C_AddressLine2 + "##
##VAR33 " + SOPInvCredAddresses.C_AddressLine3 + "##
##VAR34 " + SOPInvCredAddresses.PostCode + "## ##VAR35 " + SYSCountryCodes.Code + "##
##VAR36 " + SOPInvCredDelAddresses.Contact + "##
##VAR37 " + SOPInvCredDelAddresses.AddressLine1 + "## ##VAR38 " + SOPInvCredDelAddresses.AddressLine2 + "##
##VAR39 " + SOPInvCredDelAddresses.AddressLine3 + "##
##VAR40 " + SOPInvCredDelAddresses.PostCode + "## ##VAR41 " + SYSCountryCodes.Code + "##
##AMOUNT " + SOPInvoiceCredits.InvoicedGrossValue + "## ##CURRENCY " + SLCustomerAccounts.CurrencyISOCode + "##
##NAME " + SLCustomerAccounts.ContactName + "## ##COMPANY " + SLCustomerAccounts.CustomerAccountName + "##
##DATASETID " + SYSCompanies.CompanyNumber + "##
##ACCOUNTREF " + SLCustomerAccounts.CustomerAccountNumber + "## ##DOCUMENTNO " + SOPInvoiceCredits.DocumentNo + "##
##ERPCOMPANY " + SYSCompanies.CompanyName + "##
##VAR42 " + DateTimeToFormattedString(SOPInvoiceCredits.DocumentDate,"yyyy-MM-dd") + "## ##VAR43 " + SOPInvoiceCredits.SecondReference + "##
##VAR44 " + SOPInvoiceCredits.InvoiceCreditType + "## ##DUEDATE " + DateTimeToFormattedString((SOPInvoiceCredits.DocumentDate + SLCustomerAccounts.PaymentTermsInDays),"yyyy-MM-dd") + "##"

Note: The expression shown above includes a simplistic calculation to arrive at the invoice due date:

"##DUEDATE " + DateTimeToFormattedString((SOPInvoiceCredits.DocumentDate + SLCustomerAccounts.PaymentTermsInDays),"yyyy-MM-dd") + "##"

This simply adds the number of days in the PaymentTermsInDays to the invoice date.

For a more sophisticated calculation of the due date on a Sage 200 invoice, please consult article: KBA-14-02-011 - Calculate the Due Date in Sage 200

Statements

Statements in PayThem 2 allow the customer to pay one, all or any of the invoices on a statement. To allow this, the invoices must first have been processed with PayThem 2 so that the payment requests are already present.

To achieve this, we use the ##MVARxx...## command to pass multiple values to Spindle Document Distribution.

In the statement header, add the following expression (note that some of these commands may already be present on the layout) : 

"##ACCOUNTREF "+ SLCustomerAccounts.CustomerAccountNumber  + "## 
##DATASETID " + SYSCompanies.CompanyNumber  + "## 
##COMPANY "+ SLCustomerAccounts.CustomerAccountName  + "##"

Add the following expression into the transaction detail section (the "Details" band)

SLPostedCustomerTrans.TransactionTypeShortName="SI"?"##MVAR1 [TransactionID = Customer" + SLCustomerAccounts.CustomerAccountNumber + "Invoice" +SLPostedCustomerTrans.TransactionReference+ DateTimeToFormattedString(SLPostedCustomerTrans.TransactionDate,"yyyy-MM-dd")+ "],[AmounttoPay=" + (SLPostedCustomerTrans.GoodsValueInAccountCurrency - SLPostedCustomerTrans.AllocatedValue)+ "]##" : ""

Finally add the text ##PAYTHEM## at the position required for the button.

See article KBA-14-02-007 - Adding PayNow button to Statements for more details.

Sage 50 

Invoices

"##DOCUMENTNO " + INVOICE.INVOICE_NUMBER + "## ##DOCUMENTDATE " + DateTimeToFormattedString(INVOICE.INVOICE_DATE, "yyyy-MM-dd") + "## ##DUEDATE " + DateTimeToFormattedString(( INVOICE.INVOICE_DATE + SALES_LEDGER.PAYMENT_DUE_DAYS),"yyyy-MM-dd")   +  "## ##CURRENCY " + CURRENCY.CODE  +  "##
##AMOUNT " + INVOICE.FOREIGN_INVOICE_GROSS + "## ##ERPCOMPANY " + COMPANY.NAME + "##.
##PAYMENTTERMS " + SALES_LEDGER.PAYMENT_DUE_DAYS + "Days ## ##ACCOUNTREF " + SALES_LEDGER.ACCOUNT_REF + " ## ##COMPANY " + SALES_LEDGER.NAME + "## 
##REFERENCENO " + INVOICE.CUST_ORDER_NUMBER  + "## ##BILLFNAME " + INVOICE.NAME + "##
##BILLADD1 " + INVOICE.C_ADDRESS_1 + "## ##BILLADD2 " + INVOICE.C_ADDRESS_2 + "##
##BILLADD3 " + INVOICE.C_ADDRESS_3 + "## ##BILLCITY " + INVOICE.C_ADDRESS_4 + "##
##BILLSTATE " + INVOICE.C_ADDRESS_5 + "## ##BILLCOUNTRY " + COUNTRY_CODE.CODE + "##
##BILLEMAIL "+ SALES_LEDGER.E_MAIL + "## ##SHIPFNAME " + INVOICE.DEL_NAME + "##
##SHIPADD1 " + INVOICE.DEL_ADDRESS_1 + "## ##SHIPADD2 " + INVOICE.DEL_ADDRESS_2 + "##
##SHIPADD3 " + INVOICE.DEL_ADDRESS_3 + "## ##SHIPCITY " + INVOICE.DEL_ADDRESS_4 + "##
##SHIPSTATE " + INVOICE.DEL_ADDRESS_5 + "## ##SHIPCOUNTRY " + COUNTRY_CODE.CODE + "##
##DATASETNAME " + COMPANY.NAME + "## ##DATASETID " + 1 + "##"

Note: the DATASETID number needs to match the HostID and CustomHostID configured in the PayThem portal

Statements

For Statements, See article KBA-14-02-007 - Adding PayNow button to Statements for more details.

Placing the Pay Now button.

When PayThem 2 is enabled, it can be presented to the customer in two ways, either as a clickable button on the document PDF, or as a link in the Email body text.

To place the button onto the document, use the ##PAYTHEM## command. The button will be located with its upper left corner at the position of the upper left corner of the label containing ##PAYTHEM##. 

Please note that the default button will render as 31mm (1.22in) wide by 11mm (0.43in) tall, so Draycir recommend setting the label to this size to make positioning easier.

To use the payment request link in the body of the email, create a link in the HTML Editor in Spindle Document Distribution Tools and set the URL for the link to be ##PAYTHEMURL##:

Uploading Documents

The PayThem mechanism allows for the invoice or statement document itself to be uploaded so that the customer can view it from the PayThem link. 

To enable this for documents processed through Spindle Document Distribution, simply enable the option in Spindle Document Distribution Tools>Integration Manager:

Link the integrations into the Document Operation

Lastly, in Spindle Document Distribution Tools, open Document Automation>[Document Type]>[Document Operation]>PayThem and select the appropriate integration:

and 

Set the checkbox to ignore failures, especially during the initial phase of use, as this will ensure that the document itself is sent to the customer. If you have not performed a back-fill of invoices to create the payment requests, you will see a number of errors when processing statements, until such time as the invoices are processed.

Migrating from legacy PayThem to PayThem 2

If you are using Legacy PayThem with SagePay/Opayo you can adapt your existing configuration as follows:

• Create two new Integrations in Spindle Document Dictribution Tools, one for Invoices, one for Statements
• Check the commands on the Invoice layout to ensure they match or make sense,
• Add a command for Document Date and any other required fields (typicaly Due date needs to be added)
• Add the MVAR1 command to the detail section of the Statement layout
• Configure the portal as described above
• Switch the PayThem dropdown in the document operations to the relevant newly created integrations

See article KBA-14-02-004 - Migrating from Legacy PayThem to PayThem 2 for details.

KBA Details