Integration | Sage Pay | Payments Guide | Connected Services

Programmers guide

To start, please refer our programmer’s guide for more detail on how to apply the required methodology.

Please note:
Sage Pay may provide example/sample/demo code snippets in this technical document. Such snippets are for guidance purposes only and may not function on every developer’s system/s. Sage Pay disclaims any and all liability for the usage of any of the example/sample/demo code snippets provided -and you as the developer must accept full responsibility for the usage of any example/sample and/or demo code.

While every possible effort has been taken to ensure compatibility across multiple system configurations, the example/sample/demo code cannot be guaranteed to work on all systems, with all operating systems and
or with all system configuration/s.

Testing

Please note that testing with live transactional data will incur charges.  Please speak to your Sage Pay account manager for more details.

Introduction

Sage Connected Services is used by Software vendors to integrate Sage Pay services into a remote application with HTML content. The initial data comes from the application and the services are then provided and managed via Sage Connected Services in the application. Base pages have been developed to provide customized service offerings for payroll and accounting software.

Technical Information

Introduction

This specification is designed for Software vendors to integrate Sage Connected Services functionality from Sage Pay into a remote application. The functions are exposed in an ‘iFrame’ context in the application and the content is managed by Sage Pay. The HTML Inline Frame Element (<iframe>) represents a nested browsing context, effectively embedding the Sage Pay HTML page into your infrastructure. The remote application provides the technology as stipulated below -and supplies the initial data to the Sage Pay system via the Sage Connected Services infrastructure.

It is suggested to open Sage Connected Services in a “frameless pop up window” from your application. The dimensions Sage Pay has designed the content for is 560w x 650h (pixels).

Permissions

User permissions

The Sage Pay user’s website login credentials are used in the execution of the command. All user rights -and permissions are managed by the Sage Pay online merchant account. EXAMPLE : If a user can’t authorise a batch online in his Sage Pay Merchant Account due to rights -and permisison restrictions; -he will not have authorization rights via Sage Connected Services in your infrastructure either.
All user rights and permissions are controlled by the Sage Pay Merchant Account. Please refer to Sage Connect for details regarding storage of the Sage Pay website user credentials.

Access

Production environment

The PRODUCTION Sage Connected Services infrastructure is accessed via a form POST to https://mobi.sagepay.co.za/authenticate.aspx?key={SagePayUsername}&message={Encrypted xml message}

The username and serialised, encrypted XML string is appended to the URL when accessing Sage Connected Services.

Please note:

The username should not be encrypted.

Encryption

The {Encrypted xml message} in the string uses a custom Sage Pay encryption algorithm with the user’s PIN as the key.

The username is sent in the clear in order for the Sage Pay system to locate the PIN for decryption of the data string.

Authentication data

Each user accessing the Sage Connected Services infrastructure needs to be a registered user on the Sage Pay web site.
Authentication is by means of:

  • Username
  • Password
  • PIN

These login details should be stored in the application in a non-readable format and updated when the user changes login details on the Sage Pay web site.

Process

The remote application binds the relevant data to the XML schema and passes it to the Sage Pay system as an encrypted string.

The schema is generic and caters for all possible data requirements. Only the data specific to the execution of the required action needs to be populated. Unused XML tags may be omitted.

The XML schema and XSD are available online at:
https://mobi.sagepay.co.za/documentation/SagePayBase.xml
https://mobi.sagepay.co.za/documentation/SagePayRequest.xml
https://mobi.sagepay.co.za/documentation/SagePayRequestExample.xml

Mandatory data

The following data is mandatory for every request:

Mandatory Field Explanation
Yes Username These are the user credentials which will allow access to the Sage Pay web site
Yes Password These are the user credentials which will allow access to the Sage Pay web site
Yes PIN These are the user credentials which will allow access to the Sage Pay web site
Yes Software Vendor Key The key issued by Sage Pay to identify the software origin of transactions. (only used by Sage Pay business partners else use default value: 24ade73c-98cf-47b3-99be-cc7b867b3080)
Yes Base page The initial web page to which the user will be directed:

  • (0) PayrollServices
  • (1) AccountingServices
  • (2) Employee
  • (3) Debtors
  • (4) Creditors

Where Sage Connected Services is launched from within a client page the following mandatory data must be appended:

Mandatory Field Explanation
Yes Account reference Employee / Debtors / Creditors reference
Yes Identifier Consumer: SA ID number
Commercial: Company registration number

Note:

The request will fail if no consumer / commercial identifier is not passed

The following fields are non-mandatory but it is recommended that they are included for tracing:

Mandatory Field Explanation
No Extra 1 Any data which is specific to the remote application can be placed in these fields. Each field holds a maximum of 50 characters.
Example: the unique transaction identifier which will allow the application to update a record from data posted back by the Sage Pay system
No Extra 2 Any data which is specific to the remote application can be placed in these fields. Each field holds a maximum of 50 characters.
Example: the unique transaction identifier which will allow the application to update a record from data posted back by the Sage Pay system
No Extra 3 Any data which is specific to the remote application can be placed in these fields. Each field holds a maximum of 50 characters.
Example: the unique transaction identifier which will allow the application to update a record from data posted back by the Sage Pay system

Any data inserted into these fields can be returned in a postback to a supplied URL.

Sage Connected Services Infrastructure/Control:

  • Login details for the Sage Connected Services infrastructure in Sage Connect is encrypted in Sage Connect and/or the application database. A restore/password reminder service for these credentials must not be made available to the user. The user can reset his/her login details on the Sage Pay website and re-enter them in Sage Connected Services and/or the application database.
  • All applications follow the Sage Pastel Evolution methodology in opening Sage Connected Services  in a “frameless pop up window” / iFrame window from the respective application. The dimensions Sage Pay has designed the content for is 560 x 560 (pixels).

Base pages

The base page is the specific web page to which the user is directed when Sage Connected Services is opened. The base page is determined by the remote application and is sent in the XML request.

Enumeration index Base page Function
0 PayrollServices All functions activated for the merchant, specifically tailored to Payroll applications.
1 AccountingServices All functions activated for the merchant, specifically tailored to Accounting applications.
2 Employee Functions specific to operations within a selected employee account.
3 Debtors Functions specific to operations within a selected debtor account.
4 Creditors Functions specific to operations within a selected creditor/supplier account.

Risk Reports alternate bank name

The Risk Reports XML enum requires a camel-notated bank name in the Bank element. Since this is not acceptable to display on an application, the Sage Connected Services input XML has been extended to include an alternate (user-friendly) bank name.

This allows the software integrator to use either the Risk Reports stipulated bank name or the bank name retrieved from the NIWS_Validation webservice method

The BankAccounts element has been extended to include the new mandatory element AlternateBank
The Bank element will automatically be ignored when data is passed through the AlternateBank element.
Conversely, if the AlternateBank element is blank/empty, the Sage Pay system will use the data contained in the Bank element.

Sage Pay XML example

Version 1.4/2016 last updated 22 Feb 2016