iFrame Integrator Document | How to Integrate | Sage Pay

1. Introduction

  • Sage Connected Services is designed to allow Sage Pay system data to be presented in real time within a remote application with HTML content
  • It is strongly recommended that the Sage Pay functions are displayed in a frameless popup window of 560w x 650h (in pixels) within the remote application (the “iFrame”)
  • Integration is initiated from the remote software. The Sage Connected Services within the remote application controls the functions available within the iFrame.
  • “Base pages” have been developed to provide customised service offerings to remote payroll and accounting software applications.
  • Permission settings applied to the Sage Pay account are also applicable to the content of the iFrame

2. How to integrate

  • Only active, valid Sage Pay accounts may integrate. Authentication is by means of the login credentials allocated to the Sage Pay account:
    • Username
    • Password
    • Pin
  • The login credentials must be stored in the remote application in a non-readable format and used to access Sage Connected Services (to open the iFrame on the remote application).
  • A restore/password reminder service for these credentials must not be provided to the user. The login credentials must be updated on the user’s Sage Pay account and re-captured into the remote application.
  • The Sage Connected Services infrastructure is accessed via a FORM POST to https://mobi.sagepay.co.za/authenticate.aspx?
  • The form post requires two parameters appended to the URL:
    • Key
    • Message

    Where the “Key’ is the Sage Pay username (unencrypted) and the “Message” is an encrypted XML string
    EG: https://mobi.sagepay.co.za/authenticate.aspx?key={SagePayUsername}&message={EncryptedXMLString}

  • The message parameter is encrypted using a custom Sage Pay encryption algorithm with the user’s PIN as the encryption key.

3. Message

3.1 Mandatory fields

The following fields are mandatory for every request: –

Field name Mandatory (Y/N) Explanation
Username Y The user credentials needed to log into the Sage Pay system
Password Y The user credentials needed to log into the Sage Pay system
Pin Y The user credentials needed to log into the Sage Pay system
Software Vendor Key Y This is to identify the software origin of the transactions. IE: the key issued by Sage Pay to the remote application vendor.
Base Page Y Based on the permissions for the user, below are the various pages on which the user can view or make changes once they are logged from the remote application.

  • Payroll Services
  • Accounting Services
  • Employee
  • Debtors
  • Creditors

3.2 Client-specific mandatory fields

The following fields are mandatory and must be appended to the above where Sage Connected Services is launched from within a client page:

Field name Mandatory (Y/N) Explanation
Account Reference Y This can be Creditor Reference/Employee Reference/Debtors Reference
Identifier Y This can be either South-African ID Number or a Company Registration Number

3.3 Non-Mandatory fields

These fields are optional and can be used to supply any additional data specific to the remote application:

Field name Mandatory (Y/N) Explanation
Extra 1                      N This field is used to enter any additional information. It can hold up to 50 characters.
Extra 2                      N This field is used to enter any additional information. It can hold up to 50 characters.
Extra 3                      N This field is used to enter any additional information. It can hold up to 50 characters.

4. Base pages

The iFrame will open on the base page specified in the message. The options in the base page are tailored according to the user permissions set on the Sage Pay account.

Enumeration index Base page Explanation
              0 Payroll services All functions of the payroll service will be made available to the users based on their permissions.
              1 Accounting services All functions of the accounting service will be made available to the users based on their permissions.
              2 Employee Functions specific to operations within the selected employee account.
              3 Debtors Functions specific to operations within the selected debtor account.
              4 Creditors Functions specific to operations within the selected creditors account.

5. Working principle:

  • Before accessing the Sage Connected Services, the user should have all the mandatory data.
    (Please see the “Mandatory Field” table)
  • The remote application binds the relevant data to the XML schema and serialises it. The unused xml tags in the xml schema will be omitted.
  • The XML schema and XSD are available at
  • Since the message contains sensitive data, the XML Schema is encrypted using the Sage Pay Encryption algorithm.
  • The remote application posts the unencrypted ‘Username’ (the Key) and the encrypted XML data (the Message) to the Sage Pay system.
  • Using the Key, the Sage Pay system can determine the PIN which is used to decrypt the XML message.
  • Only if the decryption is successful and the login credentials are valid, will the base page be displayed.
  • The user credentials are used to apply the permissions as they are set on the Sage Pay website.

6. Notes:

  • User credentials cannot be reset or restored from the iframe. The user has to reset his user credentials on the Sage Pay website https:\\merchant.sagepay.co.za and recaptured into the remote application.
  • All applications should follow the recommendation to open the Sage Connected Services in a frameless pop up window of the specified size.
  • The mandatory fields in 3a are required every time Sage Connected Services is accessed from the remote application.
  • The client-specific mandatory fields in 3b are required only when Sage Connected Services is accessed from within a Debtor/Creditor/Employee record in the remote application.
  • The non-mandatory fields are not required, but any data included in these fields will be posted back to the remote application.