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.

Introduction

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

Testing

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

Technical Information

This specification is designed for Software vendors to integrate Sage Connected Services functionality from Sage Pay into a host 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 host 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).

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 permission are controlled by the Sage Pay Merchant Account. Please refer to Sage Connect for details regarding storage of the Sage Pay website user credentials for usage in this technical specification.

Acces to the production environment

The 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 refer to Sage Connect for details regarding storage of the Sage Pay website user credentials for usage in this technical specification.

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 user login details should be securely stored in the host application in a non-readable/encrypted format and updated when the user changes login details on the Sage Pay web site via Administrator login in the host system.

Process

The host 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 via the Administrator login from the host system.
  • 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

View change log