Contact support

Integrations & Payroll Export

Squid - Schools Integration Web Service Specification

Squid - Schools Integration Web Service Specification V1.22

Copyright information

The information contained within this document is strictly confidential. This document may contain information that relates to technical and financial information that is proprietary and confidential to Smart Transaction Limited. Disclosure of such information could result in material or financial loss. Therefore the disclosure of the information contained within this document to any other party and/or the use for any other purpose is strictly prohibited without the prior written consent of Smart Transactions Ltd. © 2010 Copyright Smart Transactions Ltd

Contents

  1. Document Details ....................................................................................................................... 3
    • 1.1 Contact point......................................................................................................................... 3
    • 1.2 Document conventions ......................................................................................................... 3
    • 1.3 Revision of current edition .................................................................................................... 3
  2. Introduction ................................................................................................................................ 5
  3. Web services .............................................................................................................................. 6
    • 3.1 Web services summary ........................................................................................................ 6
    • 3.2 Register for Virtual Purse ..................................................................................................... 8
    • 3.2.1 Overview .................................................................................................................. 8
    • 3.2.2 Input parameters ...................................................................................................... 8
    • 3.2.3 Output ...................................................................................................................... 8
    • 3.2.4 Business Validations / Exceptions ........................................................................... 9
    • 3.3 Register virtual purse with perso data ................................................................................10
    • 3.3.1 Overview ................................................................................................................10
    • 3.3.2 Input parameters ....................................................................................................10
    • 3.3.3 Output ....................................................................................................................10
    • 3.3.4 Business validations / exceptions ..........................................................................11
    • 3.4 Register virtual purse against card .....................................................................................12
    • 3.4.1 Overview ................................................................................................................12
    • 3.4.2 Input parameters ....................................................................................................12
    • 3.4.3 Output ....................................................................................................................12
    • 3.4.4 Business validations / exceptions ..........................................................................13
    • 3.5 Register virtual purse against card with perso data ...........................................................14
    • 3.5.1 Overview ................................................................................................................14
    • 3.5.2 Input parameters ....................................................................................................14
    • 3.5.3 Output ....................................................................................................................15
    • 3.5.4 Business Validations / Exceptions .........................................................................15
    • 3.6 Update perso data ..............................................................................................................16
    • 3.6.1 Overview ................................................................................................................16
    • 3.6.2 Input parameters ....................................................................................................16
    • 3.6.3 Output ....................................................................................................................16
    • 3.6.4 Business Validations / Exceptions .........................................................................17
    • 3.7 Collect RPU's......................................................................................................................18
    • 3.7.1 Overview ................................................................................................................18
    • 3.7.2 Input parameters ....................................................................................................18
    • 3.7.3 Output ....................................................................................................................18
    • 3.7.4 Business validations / exceptions ..........................................................................19
    • 3.8 Collect RPU's With ACK .....................................................................................................20
    • 3.8.1 Overview ................................................................................................................20
    • 3.8.2 Input parameters ....................................................................................................20
    • 3.8.3 Output ....................................................................................................................20
    • 3.8.4 Business validations / exceptions ..........................................................................20
    • 3.9 Acknowledge RPUs ............................................................................................................21
    • 3.9.1 Overview ................................................................................................................21
    • 3.9.2 Input parameters ....................................................................................................21
    • 3.9.3 Output ....................................................................................................................21
    • 3.9.4 Business validations / exceptions ..........................................................................21
    • 3.10 Disassociate card ...............................................................................................................22
    • 3.10.1Overview ................................................................................................................22
    • 3.10.2Input parameters ....................................................................................................22
    • 3.10.3Output ....................................................................................................................22
    • 3.10.4Business validations / exceptions ..........................................................................22
    • 3.11 Send Transaction ...............................................................................................................24
    • 3.11.1Overview ................................................................................................................24
    • 3.11.2Input parameters ....................................................................................................25
    • 3.11.3Output ....................................................................................................................26
    • 3.11.4Business validations / exceptions ..........................................................................26
    • 3.12 Replace Card ......................................................................................................................27
    • 3.12.1Overview ................................................................................................................27
    • 3.12.2Input parameters ....................................................................................................27
    • 3.12.3Output ....................................................................................................................27
    • 3.12.4Business validations / exceptions ..........................................................................28
    • 3.13 School Data Import .............................................................................................................29
    • 3.13.1Overview ................................................................................................................29
    • 3.13.2Input parameters ....................................................................................................29
    • 3.13.3Output ....................................................................................................................29
    • 3.13.4Business validations / exceptions ..........................................................................29
    • 3.14 Retrieve Card Details .........................................................................................................30
    • 3.14.1Overview ................................................................................................................30
    • 3.14.2Input parameters ....................................................................................................30
    • 3.14.3Output ....................................................................................................................30
    • 3.14.4Business validations / exceptions ..........................................................................31

1. Document Details

1.1 Contact point

Questions relating to this document should be addressed to: Justin Gardiner (justin.gardiner@card.co.uk)

1.2 Document conventions

Typeface or symbol Meaning Monospace type Monospaced text represents text as it appears on screen or code. It is also used to represent data that must be input by the user. [ ] Square brackets are used to indicate optional items. Text of this type should not be entered verbatim. Boldface Boldface words are used to represent keywords or command line options. Boldface is also used to emphasise important words or terms. Italics Italics words represent identifiers. Italics are also used to distinguish important words or terms. KEYCAPS This typeface is used to represent a hardware key. For example "Press CANCEL to abort". technical listing This style is used to represent technical listings such as source code or data files. Table 1 Typefaces and symbols

1.3 Revision of current edition

Version Date Change summary

  • 1.0 (Draft) 24 August 2009 Initial Release
  • 1.1 4 September 2009 Added reason codes to outputs of each web service.
  • 1.2 21 September 2009 Added more failure reasons to return value of Send Transactions.
  • 1.3 06 October 2009 Added merchant id to failed transaction response. Added description of values for RPU sequence numbers. Added RPU not found and purse account not active transaction failure reasons. Added transaction number to Send Transactions.
  • 1.4 03 February 2010 Added web service Register-Virtual-Purse-Against-Card.
  • 1.5 15 February 2010 Register virtual purse against ard now allows registration of new cards as well as adding virtual purses to existing cards.
  • 1.6 21 April 2010 Added replace card web service
  • 1.7 5 May 2010 Updated list of failure codes for replace card web service
  • 1.8 27 May 2010 Added RPU id to Collect RPUs and send transactions. Added Acknowledge RPU web service.
  • 1.9 17 Jul 2010 Added Collect RPUs With ACK web service.
  • 1.10 3 Dec 2010 Removed reason code 2003 from register virtual purse against card. Added optional fields' virtual SAM id and VAT to send transactions.
  • 1.11 7 Feb 2011 Added new web services to enable supplying student data when register cards and a web service to update existing student data.
  • 1.12 9 Mar 2011 Corrected input type for registerVirtualPurse and registerVirtualPurseWithPersoData.
  • 1.13 21 Oct 2011 Updated update perso data service to allow purse account number or reference number to be used to identity student.
  • 1.14 24 Oct 2011 Added return code for purse not found to update perso data service.
  • 1.15 29 Nov 2011 Updated update perso data service to create perso data if it is not present.
  • 1.16 07 Feb. 2012 Added failure code to register virtual purse with perso data service.
  • 1.17 19 Mar. 2015 Added schoolDataImport web service
  • 1.18 26 Mar. 2015 Added missing RSN-2027 response code to web services.
  • 1.19 29 Apr. 2015 Added retrieveCardDetails web service.
  • 1.20 05 May. 2015 Added external reference into retrieveCardDetails web service.
  • 1.22 04 June 2015 Added scheme as input to retrieveCardDetails web service.

0Table 2 Document revisions

2. Introduction

This document details the web service design of the integration between sQuid host and a school based cashless payment system. There are a number of such cashless payment systems in the market, some of which are dominant. This document intends to be generic and therefore applicable to all such providers.

The purpose of the integration shall allow students to be registered at a school and receive some identification tokens that allow them (or their parents) to register using the sQuid portal. The sQuid portal shall then be used for payment processing where money is to be added to the sQuid account. The portal shall also be used for viewing previous transactions. This top up transaction will be fed to the school where a cached account is maintained against each pupil. Any local payment transactions will take place against this cached account with the transaction being posted to the sQuid host some time later.

The design intends to model existing sQuid concepts as close as possible. As there is no physical card present and no SAM enforcing security rules, the school must be trusted to make legitimate transactions. It is possible for a school system to provide transactions indicating local top ups have taken place which the sQuid host will have to trust. This becomes increasingly important if inter purse transfers or online payments are to be considered in the future.

The sQuid host will provide a number of web services and expose these for access by systems installed at a particular school.

3. Web services

3.1 Web services summary

S No Sequence/Process Web Service Name Web Service Description

  1. Register for virtual purse Register virtual purse Web service request to register a pupil for a card and a linked virtual purse. The design maintains the same model of customers registered to cards linked to purses as is used in the physical sQuid implementation.
  2. Register for virtual purse and record perso data. Register virtual purse with perso data This web service requests for a virtual card and purse to be created and for the supplied student data to be linked to the card.
  3. Register virtual purse against existing card. Register virtual purse against card This web services registers a virtual purse against an existing sQuid card.
  4. Register virtual purse against exist card and record perso data. Register virtual purse against card with perso data This web services registers a virtual purse against an existing sQuid card and links the supplied student data to the card.
  5. Update student data Update perso data. This web service allows the student data associated with a card to be updated.
  6. Collect RPU's Collect RPUs Web service to request pending RPUs for purse accounts associated with a given card issuer.
  7. Collect RPU's Collect RPUs with ACK Web service to request pending RPUs for purse accounts associated with a given card issuer. The same set of RPUs will be sent until an acknowledgement for the RPUs is received.
  8. Acknowledge receipt of RPUs Acknowledge RPUs This web service can be called to acknowledge that RPUs have been successfully received but not yet processed.
  9. Disassociate a card Disassociate card The web service "disassociate card" shall be called to remove the linkage between card issuer and purse account in the case of a pupil leaving.
  10. Send a set of transactions Send transactions This web service shall be used for uploading of transactions to the sQuid server. It shall allow one or more transactions to be posted in a single request.
  11. Replace a card Replace card This web service allows a virtual purse to be moved from a lost card to the replacement card.
  12. School Data Import School Data Import This web service allows school raw data in form of xml to be uploaded into sQuid system.
  13. Retrieve card details Retrieve card Details This web service provides a mechanism for 3rd party systems to retrieval details of cards and purses created for a specified card holder.

Table 3 Web Services

3.2 Register for Virtual Purse

3.2.1 Overview

This web service requests registration of a pupil with a card and a linked virtual purse. The design maintains the same model of customers registered to cards linked to purses as is used in the physical sQuid implementation.

The web service shall contain the following attributes in the request:

  • Card issuer id
  • Card issuer password
  • Card issuer reference - pupil reference number

The web service shall return the following attributes in the response:

  • Card number generated for new card entity.
  • CVV number generated.
  • Collection of purse account numbers.

The school system shall create local purse accounts using the purse account numbers provided in the response. These purse accounts shall have an initial balance of zero. Transactions shall be recorded against a purse account. The card number and CVV code shall be provided to the pupil to allow them to register for a portal account using existing mechanisms. The card number and CVV code shall be stored against the pupil record for local support purposes and for provision in the disassociate card web service.

3.2.2 Input parameters

Field Name Data type Size Description Mandatory Card issuer id Numeric 8 Card issuer id used to uniquely identify a card issuer. (to be assigned by sQuidcard) Yes Card issuer password Alphanumeric 15 Card issuer password Yes Card issuer reference Alphanumeric 50 Pupil reference (to be assigned by school) Yes

3.2.3 Output

The output in this case will be a success or failure. In case of success the card number, CVV and a collection of purse account numbers will be returned. Result Reason code Reason Action to be taken / Response Success RSN-2000 Valid inputs provided Card number, CVV and purse account number returned. Failure RSN-2001 Card issuer verification failure Check configured card issuer id and password. Failure RSN-2002 No schemes mapped to card issuer Contact sQuid to verify host configuration. Failure RSN-2027 Card for reference already registered. Ensure supplied reference is unique.

3.2.4 Business Validations / Exceptions

The web service shall return the following errors in the event of a failure:

  • Card issuer verification failure.
  • No schemes mapped to card issuer.

3.3 Register virtual purse with perso data

3.3.1 Overview

This web service requests registration of a pupil with a card and a linked virtual purse. The supplied perso data will be recorded and linked to the created card.

3.3.2 Input parameters

Field Name Data type Size Description Mandatory Card issuer id Numeric 8 Card issuer id Yes Card issuer password Alphanumeric 15 Card issuer password Yes Card issuer reference Alphanumeric 50 Pupil reference (to assigned by school). be No Perso data PersoData Student perso data No

The PersoData type consists of the following fields Field Name Data type Size Description Mandatory Title Alphanumeric 10 Student title. No Forename Alphanumeric 50 Student forename. Yes Surname Alphanumeric 50 Student surname. No Additional info Alphanumeric 50 Additional information, for school use. No Sub category Alphanumeric 20 Additional field for school use such as for storing class. No Reference number Alphanumeric 20 A value that uniquely identifies this student at the card issuer. Yes Card holder status CardHolderStatusEnum Optional status of the student e.g ACTIVE or INACTIVE. If not supplied then the student will be created ACTIVE. No

3.3.3 Output

The output in this case will be a success or failure. In case of success the card number, CVV and a collection of purse account numbers will be returned. Result Reason code Reason Action to be taken / Response Success RSN-2000 Valid inputs provided Card number, CVV and purse account numbers returned. Failure RSN-0127 Mandatory field not provided Provide all mandatory fields. Failure RSN-2001 Card issuer verification failure Check configured card issuer id and password. Failure RSN-2002 No schemes mapped to card issuer Contact sQuid to verify host configuration. Failure RSN-2027 Card for reference already registered. Ensure supplied reference is unique.

3.3.4 Business validations / exceptions

The web service shall return the following errors in the event of a failure:

  • Card issuer verification failure.
  • No schemes mapped to card issuer

3.4 Register virtual purse against card

3.4.1 Overview

This web service will request that a virtual purse be created and linked to an existing card or that a new card be created with virtual purses linked to it.

The web service shall contain the following attributes in the request:

  • Card issuer id
  • Card issuer password
  • Card issuer reference - pupil reference number
  • Card number
  • CVV number

The web service shall return the following attributes in the response:

  • Collection of purse account numbers.

3.4.2 Input parameters

Field Name Data type Size Description Mandatory Card issuer id Numeric 8 Card issuer id used to uniquely identify a card issuer. (to be assigned by sQuidcard) Yes Card issuer password Alphanumeric 15 Card issuer password Yes Card issuer reference Numeric 12 Pupil reference number (to be assigned by school). No Card number Numeric 16 Card number to link purse against. Yes CVV number Numeric 3 Card CVV number. Yes

3.4.3 Output

The output in this case will be a success or failure. In case of success a collection of purse account numbers will be returned. Result Reason code Reason Action to be taken / Response Success RSN-2000 Valid inputs provided List of purse account numbers returned. Failure RSN-2001 Card issuer verification failure Check configured card issuer id and password. Failure RSN-2002 No schemes mapped to card issuer Contact sQuid to verify host configuration. Failure RSN-2008 Card and CVV numbers do not match. The CVV number does not match the CVV recorded for this card. Failure RSN-2010 Purses already created for this issuer. The card has already had purses for schemes linked to this issuer. Failure RSN-2011 Invalid card number. The card number provided is not valid.

3.4.4 Business validations / exceptions

The web service shall return the following errors in the event of a failure:

  • Card issuer verification failure.
  • The web service will create purses for all schemes mapped to the card issuer. If no schemes are mapped to this issuer an error will be returned..
  • The CVV must match that recorded in the database for the requested card.

3.5 Register virtual purse against card with perso data

3.5.1 Overview

This web service is similar to register virtual purse against card but also allows the student data to uploaded and linked to the card.

The web service shall contain the following attributes in the request:

  • Card issuer id
  • Card issuer password
  • Card issuer reference - pupil reference number
  • Card number
  • CVV number
  • Student data

The web service shall return the following attributes in the response:

  • Collection of purse account numbers.

3.5.2 Input parameters

Field Name Data type Size Description Mandatory Card issuer id Numeric 8 Card issuer id used to uniquely identify a card issuer. (to be assigned by sQuidcard) Yes Card issuer password Alphanumeric 15 Card issuer password Yes Card issuer reference Numeric 12 Pupil reference number (to be assigned by school). No Card number Numeric 16 Card number to link purse against. Yes CVV number Numeric 3 Card CVV number. Yes Perso data PersoData Student data No

The PersoData type consists of the following fields Field Name Data type Size Description Mandatory Title Alphanumeric 10 Student title. No Forename Alphanumeric 50 Student forename. Yes Surname Alphanumeric 50 Student surname. No Additional info Alphanumeric 50 Additional information, for school use. No Sub category Alphanumeric 20 Additional field for school use such as for storing class. No Reference number Alphanumeric 20 A value that uniquely identifies this student at the card issuer. Yes Field Name Data type Size Description Mandatory Card holder status CardHolderStatusEnum Optional status of the student e.g ACTIVE or INACTIVE. If not supplied then the student will be created ACTIVE. No

3.5.3 Output

The output in this case will be a success or failure. In case of success a collection of purse account numbers will be returned. Result Reason code Reason Action to be taken / Response Success RSN-2000 Valid inputs provided List of purse account numbers returned. Failure RSN-2001 Card issuer verification failure Check configured card issuer id and password. Failure RSN-2002 No schemes mapped to card issuer Contact sQuid to verify host configuration. Failure RSN-2008 Card and CVV numbers do not match. The CVV number does not match the CVV recorded for this card. Failure RSN-2010 Purses already created for this issuer. The card has already had purses for schemes linked to this issuer. Failure RSN-2011 Invalid card number. The card number provided is not valid.

3.5.4 Business Validations / Exceptions

The web service shall return the following errors in the event of a failure:

  • Card issuer verification failure.
  • The web service will create purses for all schemes mapped to the card issuer. If no schemes are mapped to this issuer an error will be returned..
  • The CVV must match that recorded in the database for the requested card.

3.6 Update perso data

3.6.1 Overview

This web service allows existing student data to be updated. The web service will contain the student data fields to be updated along with the reference number or purse account number that uniquely identifies the student at the calling card issuer. If the perso data is not present for a given student then the web service will create it.

3.6.2 Input parameters

Field Name Data type Size Description Mandatory Card issuer id Numeric 8 Card issuer id used to uniquely identify a card issuer. Yes Card issuer password Alphanumeric 15 Card issuer password Yes Perso data PersoData Student data No

The perso data consists of the following Field Name Data type Size Description Mandatory Title Alphanumeric 10 Student title. No Forename Alphanumeric 50 Student forename. No Surname Alphanumeric 50 Student surname. No Additional info Alphanumeric 50 Additional information, for school use. No Sub category Alphanumeric 20 Additional field for school use such as for storing class. No Reference number Alphanumeric 20 A value that uniquely identifies this student at the card issuer. No Purse account number Numeric 18 Students purse account number. No Card holder status CardHolderStatusEnum Optional status of the student e.g ACTIVE or INACTIVE. If not supplied then the student will be created ACTIVE. No

The web service will look up the student data using the card issuer id and either the purse account number or reference number. Any non-empty fields in the perso data will then be updated with the supplied values. If the perso data does not exist then the web service will create a new card holder. In this card the forename and surname and reference number fields must be supplied.

3.6.3 Output

The output will contain one of the following response codes Result Reason code Reason Action to be taken / Response Success RSN-2000 Valid inputs provided Nothing returned. The student data has been updated. Failure RSN-2001 Card issuer verification failure Check configured card issuer id and password. Failure RSN-2009 Card not associated with issuer The card issuer specified is not associated with this card. Failure RSN-2017 Purse number not found A purse number was specified but this was not found in the database.

3.6.4 Business Validations / Exceptions

The web service shall return the following errors in the event of a failure:

  • Card issuer verification failure.
  • Card not associated with issuer.
  • The student reference number or the purse account number must be supplied. The card linked to either of these must be associated with this card issuer. This prevents card issuers changing perso data for students at other schools.

3.7 Collect RPU's

3.7.1 Overview

Web service to request pending RPUs for purse accounts associated with a given card issuer. This web service shall be called on a periodic basis e.g. hourly.

The web service shall contain the following attributes in the request:

  • Card issuer id
  • Card issuer password

The web service shall return the following attributes in the response:

  • Collection of purse accounts
    • Purse account number
    • RPU operation
      • Enumeration of credit, debit, block, unblock, delete, set balance
    • RPU value - amount field depending on operation
    • RPU sequence number.
    • RPU id
  • Flag to indicate more RPUs still to be collected

Response shall be truncated at 100 RPUs. The RPU id uniquely identifies an RPU. The RPU sequence records the last RPU that was applied to the purse. This prevents the same RPU being applied multiple times. An RPU should only be applied to a purse if its sequence number is one greater than the sequence number on the purse. Once the update has been applied the purses RPU sequence number should be incremented. The sequence number is initially zero and after reaching 255 wraps back to 0 again. The RPU id can be used to uniquely identify any RPU.

The school system shall apply each RPU to the local purse account and create a RPU transaction back to the host to indicate that this has been applied. This models the physical RPU world and provides the ability on the sQuid host to mark the RPU as having been applied. The collect purse updates call shall be made repeatedly while more RPUs are indicated via a field in the response. Completion of the download shall be signalled by a response with the flag to indicate more RPUs available set to false. Once the RPUs have been sent they will be marked as delivered on the host and will not be resent in any future call to this service. To guarantee receipt of RPUs use the Collect RPUs with ACK service, this will resend each RPU until the host receives an acknowledgement for the RPU.

3.7.2 Input parameters

Field Name Data type Size Description Mandatory Card issuer id Numeric 8 Used to uniquely identify a card issuer. (to be assigned by sQuidcard) Yes Card issuer password Alpha numeric 15 Card issuer password. Yes

3.7.3 Output

The following information will be returned

  • Collection of purse accounts
    • Purse account number
    • RPU operation
      • Enumeration of credit, debit, block, unblock, set balance.
    • RPU value - amount field depending on operation RPU sequence number.
    • RPU id, a number that uniquely represents this RPU. Flag to indicate more RPU's to be collected.

The number of RPUs will be truncated to 1000 per request with a flag in the response being used to indicate there are more RPUs pending. Result Reason code Reason Action to be taken / Response Success RSN-2000 Valid inputs provided Success collection of RPU's returned. Failure RSN-2001 Card issuer verification failure Check configured card issuer id and password.

3.7.4 Business validations / exceptions

The web service shall return the following errors in the event of a failure: Card issuer verification failure.

Collect RPU's With ACK

Overview

This web service functions similarly to the collect RPUs service, however for this version each of the returned RPUs is kept in the NEW state on the host and will be kept in this state and until an acknowledgment is received. The acknowledgement can consist of a call to the Acknowledge RPUs service or receipt of the corresponding RPU transaction. Until an acknowledgement is received for an RPU it will be sent on every call to the service.

3.8.2 Input parameters

Field Name Data type Size Description Mandatory Card issuer id Numeric 8 Used to uniquely identify a card issu