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 Default Dataset in the upper right and choose Edit Companies from the list:

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)

With the new company selected, click on Home:

You will see a number of To-Do actions required to configure PayThem 2.

Skipping the payment provider for the time being we can update the company details, logo and website using the Fix this buttons:

Company Details and website details:

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

Logo

These settings can be amended after the fact in the Settings menu on the left hand navigation pane:

Configure Payment Provider

Next, configure the payment provider in the portal. Click Settings>Payment Providers and choose Add 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.

Truelayer

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 Setings>Preferences, configure he options according to the customer's requirements

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

Adding users

add users under Settings>Add Users

Configure Email Notifications

Once users are configured, you can specify which users will be notified of successful, failed and pending payments under Settings>Notifications:

Click Add User to add a new nofication recipient. You can use either a PayThem user or an external email address to receive the notification:

Once added, this user will be visible in the dropdown list:

Use the toggle switches to enable each required notification.

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.

in the portal, click Access keys and click Create Access key:

Copy this key and 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") + "##"

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