Token System Integration & Protocol Guideline (Server & Direct)

Transcription

1 Token System Integration & Protocol Guideline (Server & Direct)

2 Token System Protocol and Integration Guideline Content Welcome to the Sage Pay Token System integration... 2 General overview of how the Token System works... 3 Registering a Token... 3 Using a Token... 4 Step by step of process... 5 Registering a Token... 5 Using a Token... 7 Appendix A - The Sage Pay Token System Protocol: Accepted REGISTRATION Protocol - using SERVER Integration method Protocol for USING a Token - using SERVER Integration method REGISTRATION Protocol - using DIRECT Integration method Protocol for USING a Token - using DIRECT Integration method Protocol for REMOVING a Token URLs Version 1.1 (01/02/2013) 1

3 Token System Protocol and Integration Guideline Welcome to the Sage Pay Token System integration The Sage Pay payment system provides the functionality for you to tokenise card details. By generating an alias, you can store customer card details securely on your system and feel reassured that this information is meaningless to anyone else other than Sage Pay. The following integration and protocol guideline details how to integrate with the Sage Pay Token System using a two step process where a card is first registered and a token is generated before it can be sent to Sage Pay for authorisation. This process is ideal in situations where you would like to provide your shoppers with the option to associate a card with their account, store card details in a safe format to be authorised at a later date or to simply have secure access to card information for recurring payments. You can also generate a token automatically on the back of a payment transaction after it has been authorised. If you prefer to use the Sage Pay Token System in this way, you simply instruct the Sage Pay payment system when you submit a Payment registration POST. Please refer to protocol version 3.0 of either the Server or Direct integration and protocol guideline for details on how to do this. Please note that there is an additional cost on top of the monthly regular service fees for using this service. Please contact tellmemore@sagepay.com for more information on the pricing. Version 1.1 (01/02/2013) 2

4 Token System Protocol and Integration Guideline General overview of how the Token System works The Token system is a two part process which requires the Registration of the token, that is; converting a card number into a Token to then be stored, and the Use of a Token, that is; taking the stored Token and using it to create a type of Payment. Registering a Token The first part of the process when using the Token system is to register the card detail with the Sage Pay Token system for the card number to be converted and for a token to be generated. No shopping or customer information needs to be submitted to Sage Pay at this stage of the process and any shopping/customer information you capture at this stage will be to store within your database. This means that you can register a card for a token before your customer selects and chooses any products (such as when your customer registers on your website). Alternatively, the shopping process can still be as per the usual payment process where the shopper will go through your website, selecting their chosen item and going through the checkout process however, you would simply store all this information until after you have registered the token. In order for the Token to be generated, the customer s card details will need to be captured. Once the card details have been provided, the Sage Pay server will validate the information and generate the token, which will be sent back to your servers for you to store along with all the other customer details. Please note that the Sage Pay Token system does not validate any customer information associated with the Token and therefore it is important for you to store the correct token with the customer s details to ensure that payment is taken from the correct card. At this point, there is no link with the banking network and the only communication here is between your server and the Sage Pay server. The Token system is ideally suited where there is customer profile for the shopper where you are able to associate the token with the customer, as no record of the customer is kept with the Token at Sage Pay. The below diagram shows the flow of the card information through the registering part of the Token System. Version 1.1 (01/02/2013) 3

5 Token System Protocol and Integration Guideline Using a Token The second part of the process is to use the token which has been generated, to submit for authorisation and to obtain the funds. This can be initiated by the shopper or automatically by your server depending on how you wish to use the Token System. Your server would simply submit the Token with the normal Payment registration post to the Sage Pay servers. It would be at this stage that all the customer details which you captured (such as customer name, address, billing & delivery address) would be submitted to Sage Pay. Once received, Sage Pay will validate all the information sent and use the token provided to locate the card number from the Sage Pay database to send onto the bank for authorisation. A response regarding the outcome of the authorisation will be returned back to you along with all the usual checks. It is important to note that when you use a token, you will need to indicate whether you wish for the Token to be stored for use again. The following sections explain the integration process in more detail for both the Server and Direct. The complete Token System integration protocol is attached in the appendix, providing a detailed breakdown of the contents of the HTTPS messages sent between your servers and ours during a Token transaction. Version 1.1 (01/02/2013) 4

6 Token System Protocol and Integration Guideline Step by step of process Registering a Token This is the first part of the process and needs to be done each time a Token is needed. Please note that when registering a Token, no communication is made to the bank at this point. Registration for a Token using the Server integration method 1. The shopper visits your website and selects the products they wish to purchase. 2. When you are ready to register for a token, your server makes a post to the Sage Pay server using the specified protocol with the TxType=TOKEN. 3. Once the information has been received, Sage Pay will validate the POST. If it is invalid, your server will be notified and we would recommend that you check and repost. 4. If the POST is valid, Sage Pay will return a response and pass a NextURL back to you. 5. You will then be able to redirect your customer to the payment page using the NextURL provided. 6. Your customer will then be redirected to the NextURL to enter their credit card details, expiry and CV2 on the Sage Pay payment page. 7. Sage Pay will then validate the entry of these details. As per current protocol, Sage Pay will allow for 3 attempts. 3 failed attempts to register the card details will result in a failure notification being sent back to your server. 8. If the details the customer enters are valid as per current card checks and validation rules, then Sage Pay will store the card number, expiry date, CV2 and generate a token*. 9. Sage Pay will then send a Notification POST to your NotificationURL provided in your transaction registration with the results of the transaction and the Token details (including the expiry date, last 4 digits of the card and card type). 10. Your server will then need to respond to the Notification POST with a status and a redirect URL. If the status is anything other than OK, Sage Pay will delete the token along with the card number, expiry and CV Once a notification response has been received, Sage Pay will redirect the customer to the RedirectURL provided in step 10. Version 1.1 (01/02/2013) 5

7 Token System Protocol and Integration Guideline Registration for a Token using the Direct integration method 1. The shopper visits your website and selects the products they wish to purchase and enters their card details directly on your website when you are ready to register a card for a token. 2. Your server makes a post to the Sage Pay server using the specified protocol using the TxType=TOKEN. 3. Sage Pay validates the POST. If it is invalid, your server will be notified and we would recommend that you check and repost. 4. If the POST is valid as per current card checks and validation rules, Sage Pay will store the card number, expiry date, CV2 and generate a token*. 5. In the transaction response POST back to your server, Sage Pay will include the unique token as well as the results of the tokenisation for storage. *The CV2 value is only stored prior to authorisation. After the initial use of the token the CV2 will be deleted to comply with industry regulations. If you have AVS/CV2 checks enabled on your account, you will need to obtain this information from the customer each time the token is used. Version 1.1 (01/02/2013) 6

8 Token System Protocol and Integration Guideline Using a Token For this part of the process, the bank is now contacted for authorisation and therefore needs to be done each time you wish to use a token to authorise and take funds. Using a Token through the Server integration method 1. Returning shopper visits your website where you are able to associate the customer with a pre registered token. 2. Your server creates and submits a standard transaction registration POST including the Token and a primary payment type (PAYMENT, DEFERRED, AUTHENTICATE) as well as all the other required protocol values and including any optional protocol values you wish to submit. This is then POSTed to the usual Sage Pay transaction registration payment URL. 3. Sage Pay will validate the token against your account. If the token is invalid, your server will be notified and we would recommend that you check the Token and repost. 4. If the token is valid, Sage Pay will validate the rest of the POST, as per the normal Server guidelines. If the POST is invalid, your server will be notified and you will have to check the information sent and repost. 5. If the POST is valid, Sage Pay will pass your server the Next URL. 6. You will need to redirect the customer to the payment page using the NextURL. 7. At this point, Sage Pay will obtain the credit card information associated with the Token provided in step 2 8. If a CV2 value is also available, Sage Pay will pull this from the Token database. If no CV2 value is available and it is required on your account, then the shopper will be given the opportunity to re enter their CV2 number on the payment page, which will be an adjusted version of the normal payment page, with only a CV2 entry box. If no CV2 is entered and none exists on the Sage Pay Token database and the account in question requires a CV2 check, then the transaction will be rejected and your server will be notified. 9. If step 8 completes and a CV2 is available on the Token database OR the customer is given the opportunity to enter the CV2 and does so then Sage Pay will take the card details and CV2 and approach the 3D secure directory. Version 1.1 (01/02/2013) 7

9 Token System Protocol and Integration Guideline 10. If 3D Secure is available on your account then the relevant 3D secure authentication page (ACSURL) will be provided within the payment page for the customer to enter their details and gain authorisation, or fail, or cancel. 3D failure or cancellations will be checked against the 3D rulebase on your account (if present) and will either be forwarded to step 11, or rejected and your server notified. 11. If no 3D is available on the account, then the transaction continues for bank authorisation. If 3D auth is achieved or 3D auth fails but is allowed by the rulebase, then the transaction will continue for authorisation. 12. If Bank authorisation is achieved and passes the AVS/CV2 checks on your account (if present) then the transaction is authorised and a successful notification is sent to your server. 13. If Bank authorisation fails, or is authorised but failed by the AVS/CV2 rulebase then the transaction is declined, or rejected, and a failure notification is sent to your server. 14. Once a transaction has completed as either Failed after three attempts or Authorised then the token is considered USED and will be deleted. To store the token a request must be sent as per the transaction registration post StoreToken=1. If no value is passed or where StoreToken=0 the Token will be deleted by default. Version 1.1 (01/02/2013) 8

10 Token System Protocol and Integration Guideline Using a Token through the Direct integration method 1. Returning shopper visits your website and you associate the customer with a pre registered token. 2. Your server creates and submits a transaction registration POST including the Token and a primary payment type (PAYMENT, DEFERRED, AUTHENTICATE) as well as all the other required protocol values and including any optional protocol values you wish to submit. This is then POSTed to the usual Sage Pay transaction registration payment URL. 3. Sage Pay validates the token against your account. If the token is invalid, your server will be notified and we would recommend that you check the Token and repost. 4. If the token is valid, Sage Pay will validate the rest of the POST, as per normal guidelines. If the POST is invalid, your server will be notified and you will have to check and repost. 5. If a CV2 value (optional) is passed within the POST then this value will always be used in place of any CV2 value that might be available within the Sage Pay database. 6. If no CV2 value is passed within the POST then Sage Pay will check to see if the Token has been used before. If the token has not been used before, a CV2 value will be pulled from the Token database. 7. If the CV2 value has been used before and none has been supplied in the initial POST, Sage Pay check to see if a CV2 is required for the transaction (ie. for AVS/CV2 checks). If a CV2 value is required but has not been supplied, the transaction will be rejected and your server will be notified. 8. If a CV2 value is supplied in the initial POST or a CV2 is obtained in step 6 from the token database then the card details are forwarded to the 3D secure directory. If no CV2 value is supplied, nor is one available on record and the transaction does not require a CV2 (i.e. no AVS/CV2 checks) then the transaction is also forwarded to the 3D secure directory. 9. Sage Pay pass transaction details to 3D secure directory to obtain normal 3D secure with direct details. Once obtained, an ACS URL will be provided for you to redirect your shopper to, for 3D secure to take place. 10. If the card is not part of the scheme, or if the customer cancels 3D secure, or if the customer fails 3D secure checks, Sage Pay will check your 3D secure rulebase and reject the payment if required or continue. 11. If the customer completes 3D secure, or no 3D secure is available, or 3D secure is cancelled, or 3D secure is failed and your rulebase allows this, the transaction will then be forwarded to the bank for authorisation. 12. If the transaction is authorised by the bank, then Sage Pay will check your AVS/CV2 rulebase. If the checks pass your rulebase then the transaction is authorised and a successful notification is sent back to your server. 13. If the transaction is authorised by the bank and after Sage Pay checks your AVS/CV2 rulebase, the transaction fails to pass this rulebase, then a rejected notification is sent back to your server. If the bank declines the authorisation then a failed notification is sent. 14. Once a transaction has completed as either Failed or Authorised then the token is considered USED. For successful transactions the token is deleted unless a request is made as per the transaction registration post StoreToken=1. For failed transactions the token will continue to be stored unless subsequent attempts are successful or a RemoveToken request is made. NB: It is your responsibility to remove tokens for failed transactions by using the RemoveToken request with TxType=REMOVETOKEN. Version 1.1 (01/02/2013) 9

11 Appendix A - The Sage Pay Token System Protocol: Accepted This section details the Sage Pay Token System Protocol. It details the contents of the POSTs and responses, between your website and ours. The format and size of each field is given, along with accepted values and. The legend below explains the symbols: Accented Characters New line (Carriage Return and Line Feed) Ampersand character Numbers At sign Plus sign Colon Parentheses Comma Semi colon Curly Brackets Apostrophe (single quote) Full Stop/Period Backslash and Forward Slash Hyphen Space Letters (A Z and a z) Underscore ISO letter country codes Valid Base64 (A Z,a z,0 9,+ and /) Valid 2 letter US States ISO letter Currency codes RFC 1738 compliant HTTP(S) URL All non compliant, including spaces, should be URL Encoded Valid HTML with no active content. Script will be filtered. Includes all valid letters, numbers, punctuation and accented. RFC 5321/5322 (see also RFC 3696) compliant e mail Addresses. 10

12 REGISTRATION Protocol - using SERVER Integration method For registration of a Token using SERVER integration method, the protocol will need to be posted to the following URL:.../gateway/service/token.vsp A1: Request format Name Format Values Comments VPSProtocol in this release. Default or incorrect value is taken to be 3.00 Fixed 4. TxType TOKEN Should be in capital letters. Vendor. Vendor Login Name. Used to authenticate your site. This should contain the Vendor Name supplied by Sage Pay when your account was created. VendortxCode Currency Max 40 3 Vendor Transaction Code Three letter currency code to ISO 4217 Examples: GBP, EUR and USD This should be your own reference code to the transaction. Your servers should provide a completely unique VendorTxCode for each transaction. The currency must be supported by one of your merchant accounts or the transaction will be rejected. NotificationURL Profile Language Max 255 Max 10 Characters Alpha 2 Fully qualified URL (Including or header). Callback URL to which Notification POSTs are sent to (see A3) NORMAL (DEFAULT) or LOW A profile of LOW returns the new simpler Server Payment pages which have only one step and minimal formatting. Designed to run in iframes. Omitting this field or sending NORMAL renders the normal card screen. 2 letter language code The language of the customer will be determined by their browser settings. If this cannot be done it will be taken by the default language set in My Sage Pay unless this field is supplied which will override all settings. It is recommended to allow the users browser settings to set the language. 11

13 Server response to the Initial Token registration POST: A2: Response format: Name Format Values Comments VPSProtocol in this release. Default or incorrect value is taken to be 3.00 Fixed 4. Status OK, MALFORMED, INVALID. StatusDetail Max 255 Human readable text providing extra detail for the status message. You should always check this value if the status is not OK. VPSTxId SecurityKey NextURL Fully qualified URL Max 255 Characacters Sage Pay s ID to uniquely identify the Transaction on our system. A Security key which the gateway uses to generate a MD5 hash to sign the notification message. The signature is called VPSSignature. URL to which the vendor must redirect the customer to enter card details Only present if Status is OK or OK REPEATED. Please Note : curly brackets { } are returned with the VPSTxId These curly brackets should NOT be included for the VPSTxId when constructing your MD5. Should be kept secret from the customer but stored in your database Only present if Status is OK. 12

14 Status notification of results for Token registration sent to Notification URL provided in A1: A3: Response format: Name Format Values Comments VPSProtocol in this release. Default or incorrect value is taken to be 3.00 Fixed 4. TxType TOKEN. VendortxCode Max 40 Vendor Transaction Code This should be your own reference code to the transaction. Your servers should provide a completely unique VendorTxCode for each transaction. VPSTxId 38 Sage Pay s ID to uniquely identify the Transaction on our system. Only present if Status is OK or OK REPEATED. Token Status CardType 38 GUID. Alphabetic The token generated by Sage Pay and provided in response to the registration phase OK Card Details Registered ERROR An error occurred at Sage Pay which meant the transaction could not be completed successfully. VISA, MC, DELTA, SOLO, MAESTRO, UKE, AMEX, DC, JCB, LASER, MC is MasterCard, UKE is Visa Electron. MAESTRO should be used for both UK and International Maestro. AMEX and DC (DINERS) can only be accepted if you have additional merchant accounts with those acquirers. Last4Digits Numeric Max 4 The last 4 digits of the card number used in this transaction. This field is supplied to allow merchants using wallet systems to identify the card to their customers 13

15 ExpiryDate Numeric Max 4 The Expiry date (required for ALL cards) in MMYY format. Vendor MUST STORE THIS VALUE AGAINST THE TOKEN! Token will be removed on Expiry of card StatusDetail Max 255 Human readable text providing extra detail for the status message. VPSSignature MD5 signature of the concatenation of the values of: vpstxid+vendortxcode+status+ vendorname+token+securitykey NOTE: MD5 value is returned in UPPER CASE To detect any possible tampering with messages, your site should compute the same MD5 signature (which incorporates the Security key provided at Transaction registration) and check it against VPSSignature. You can then decide what to do with transactions that appear to have been tampered with. Please Note : curly brackets should NOT be included for the VPSTxId when they are constructing your MD5 Signature to ensure that their MD5 Signature matches the VPSSignature returned to you here. Curly brackets SHOULD be included for the Token value. 14

16 Notification response to acknowledge response A3: A4: Response format Name Format Values Comments Status OK, MALFORMED, INVALID. StatusDetail Max 255 Human readable text providing extra detail for the status message. You should always check this value if the status is not OK. RedirectURL Fully qualified URL Max 255 Characacters Fully qualified URL to which you d like the customer redirected on completion of receiving token. This should include the or header. If you wish to pass parameters back to your own site (such as the session id or transaction code), these should be included in the RedirectURL 15

17 Protocol for USING a Token - using SERVER Integration method To use a Token using the SERVER integration method, the following protocol will need to be posted to the usual Payment registration URL:.../gateway/service/vspserver register.vsp B1: Request format Name Format Values Comments VPSProtocol in this release Default or incorrect value is taken to be 3.00 Fixed 4. TxType. PAYMENT, DEFERRED or AUTHENTICATE Should be in capital letters Vendor VendorTxCode Amount. Max 40 Numeric to 100, Vendor Login Name Vendor Transaction Code Amount for the Transaction containing minor digits formatted to 2 decimal places where appropriate. Used to authenticate your site. This should contain the Vendor Name supplied by Sage Pay when your account was created. This should be your own reference code to the transaction. Your servers should provide a completely unique VendorTxCode for each transaction. Must be positive and numeric, and may include a decimal place where appropriate. Minor digits should be formatted to two decimal places. e.g. 5.10, or Values such as will be rejected. Currency 3 Three letter currency code to ISO 4217 Examples: GBP, EUR and USD The currency must be supported by one of your merchant accounts or the transaction will be rejected. Description Max 100 Free text description of goods or services being purchased The description of good purchased is displayed on the Server payment page. 16

18 NotificationURL Max 255 Full qualified URL (including or header). Token The token provided during the token 38 registration phase GUID StoreToken Fixed 0 or 1 Should the Sage Pay system store the token or not? Value must be sent with every transaction DEFAULT=0 BillingSurname BillingFirstnames BillingAddress1 BillingAddress2 BillingCity BillingPostCode Max 20 Max 20 Max 100 Max 100 Max 40 Max 10 Customer s surname Customer s first names First line of billing address Second line of billing address City component of the address The Post/Zip code of the Card Holder s Billing Callback URL to which Notification POSTs are sent (see step A3). This value must be 0 or 1. Default is 0. To store a token after three failed attempts or after a successful payment the StoreToken value must be 1. To store a token repeatedly a value of 1 must be passed with every use of the token. In Protocol 2.23, unlike previous protocols, the Billingxxxxx columns are compulsory. In Protocol 2.23, unlike previous protocols, the Billingxxxxx columns are compulsory. BillingCountry Max 2 ISO country code of the cardholder s billing address 17

19 Optional*: BillingState BillingPhone DeliverySurname DeliveryFirstnames DeliveryAddress1 DeliveryAddress2 DeliveryCity DeliveryPostCode Max 2 Max 20 Max 20 Max 20 Max 100 Max 100 Max 40 Max 10 State code for US customers only* Phone number at billing address Customer s surname Customer s first names First line of delivery address Second line of delivery address City component of the address The Post/Zip code of the Card Holder s delivery address In Protocol 2.23, unlike previous protocols, the Deliveryxxxx columns are compulsory. DeliveryCountry Max 2 ISO country code of the cardholder s delivery address Optional*: DeliveryState Max 2 State code for US customers only* 18

20 DeliveryPhone Customer Basket AllowGiftAid ApplyAVSCV2 Max 20 Max 255 Max 7500 Flag Flag Phone number at delivery address Token System Protocol and Integration Guideline e The customer s e mail address The current version of Server does not send confirmation e mails to the customer (although future versions will). This field is provided for your records only. See the next page for the Format of the Basket field 0 = No Gift Aid Box displayed (default) 1 = Display Gift Aid Box on payment screen. 0 = If AVS/CV2 enabled then check them. If rules apply, use rules. (default) 1 = Force AVS/CV2 checks even if not enabled for the account. If rules apply, use rules. 2 = Force NO AVS/CV2 checks even if enabled on account. 3 = Force AVS/CV2 checks even if not enabled for the account but DON T apply any rules. You can use this field to supply details of the customer s order. This information will be displayed to you in the Admin screens. This flag allows the gift aid acceptance box to appear for this transaction on the payment page. This only appears if your vendor account is Gift Aid enabled. Using this flag you can fine tune the AVS/CV2 checks and rule set you ve defined at a transaction level. This is useful in circumstances where direct and trusted customer contact has been established and you wish to override the default security checks. 19

21 Apply3DSecure Flag 0 = If 3D Secure checks are possible and rules allow, perform the checks and apply the authorisation rules. (default) 1 = Force 3D Secure checks for this transaction if possible and apply rules for authorisation. 2 = Do not perform 3D Secure checks for this transaction and always authorise. 3 = Force 3D Secure checks for this transaction if possible but ALWAYS obtain an auth code, irrespective of rule base. Using this flag you can fine tune the 3D Secure checks and rule set you ve defined at a transaction level. This is useful in circumstances where direct and trusted customer contact has been established and you wish to override the default security checks. AccountType Profile 1 character Max 10 E = Use the e commerce merchant account (default). C = Use the continuous authority merchant account (if present). M = Use the mail order, telephone order account (if present). NORMAL (DEFAULT) or LOW This optional flag is used to tell the Sage Pay System which merchant account to use. If omitted, the system will use E, then M, then C by default. A profile of LOW returns the new simpler Server payment pages which have only one step and minimal formatting. Designed to run in iframes. Omitting this field or sending NORMAL renders the normal card selection screen. 20

22 REGISTRATION Protocol - using DIRECT Integration method For registration of a Token using DIRECT integration method, the protocol will need to be posted to the following URL:.../gateway/service/directtoken.vsp A1: Request format Name Format Values Comments VPSProtocol in this release. Default or incorrect value is taken to be 3.00 Fixed 4. TxType TOKEN Should be in capital letters. Vendor. Vendor Login Name. Used to authenticate you site. This should contain the Sage Pay Vendor Name supplied by Sage Pay when you account was created. Currency 3 Three letter currency code to ISO 4217 Examples: GBP, EUR and USD The currency must be supported by one of your merchant accounts or the transaction will be rejected. CardHolder CardNumber StartDate Max 50 Numeric Max 20 Numeric 4 The card holder s name. The credit or debit card number with no spaces. The Start date (required for some Maestro, Solo and Amex) in MMYY format. This should be the name displayed on the card. The full card number is required. The start date MUST be in MMYY format i.e for June No / or should be included. 21

23 ExpiryDate Numeric 4 The Expiry date (required for ALL cards) in MMYY format. The expiry date MUST be in MMYY format i.e for December No / or should be included. IssueNumber CV2 Numeric Max 2 Numeric Max 4 The card Issue Number (some Maestro and Solo cards only) The extra security 3 digits on the signature strip of the card, or the extra 4 digits on the front for American Express Cards The issue number MUST be entered EXACTLY as it appears on the card. e.g. some cards have Issue Number 4, others have 04. CardType VISA, MC, DELTA, SOLO, MAESTRO, UKE, AMEX, DC, JCB, LASER NB: SWITCH is still accepted for UK Maestro but you should use MAESTRO MC is MasterCard, UKE is Visa Electron. MAESTRO should be used for both UK and International Maestro. AMEX and DC (DINERS) can only be accepted if you have additional merchant accounts with those acquirers. 22

24 A2: Response format Name Format Values Comments VPSProtocol in this release. Default or incorrect value is taken to be 3.00 Fixed 4. TxType TOKEN. Status OK, MALFORMED, INVALID. StatusDetail Human readable text providing extra You should always check this value if the status is not OK. Max 255 detail for the status message. Token 38 GUID Token to use for payment 23

25 Protocol for USING a Token - using DIRECT Integration method To use a Token using the DIRECT integration method, the following protocol will need to be posted to the usual Payment registration URL:.../gateway/service/vspdirect register.vsp B1: Request format Name Format Values Comments VPSProtocol in this release. Default or incorrect value is taken to be 3.00 Fixed 4. TxType. PAYMENT, DEFERRED or AUTHENTICATE. See companion document Server and Direct Shared Protocols for other transaction types (such as Refunds, Releases, Aborts and Repeats). Vendor. Vendor Login Name. Used to authenticate your site. This should contain the Vendor Name supplied by Sage Pay when your account was created. VendorTxCode Amount Currency Max 40 Numeric to 100, Vendor Transaction Code. Amount for the Transaction containing minor digits formatted to 2 decimal places where appropriate. Three letter currency code to ISO 4217 Examples: GBP, EUR and USD This should be your own reference code to the transaction. Your servers should provide a completely unique VendorTxCode for each transaction. Must be positive and numeric, and may include a decimal place where appropriate. Minor digits should be formatted to two decimal places. e.g. 5.10, or Values such as will be rejected. The currency must be supported by one of your VSP merchant accounts or the transaction will be rejected. Description Max 100 Free text description of goods or services being purchased. The description of good purchased is displayed in the Administrative screens for your future reference. Token 38 GUID The token provided during the token registration phase 24

26 StoreToken Fixed 0 or 1 Should the SagePay system store the token or not? Value must be sent with every transaction DEFAULT=0 This value must be 0 or 1. Default is 0. To store a token after each successful payment the StoreToken value must be 1 otherwise the token will be deleted. To store a token repeatedly a value of 1 must be passed with every use of the token. NB: Tokens are not deleted by default for failed attempts. CV2 Numeric Max 4 The extra security 3 digits on the signature strip of the card, or the extra 4 digits on the front for American Express Cards NB: If AVS/CV2 is ON for your account this field becomes compulsory. BillingSurname Max 20 Customer s surname NB: If AVS/CV2 is ON for your account, these fields become compulsory. BillingFirstnames Max 20 Customer s first names BillingAddress1 Max 100 First line of billing address BillingAddress2 Max 100 Second line of billing address BillingCity Max 40 City component of the address 25

27 BillingPostCode BillingCountry Optional*: BillingState BillingPhone DeliverySurname DeliveryFirstnames DeliveryAddress1 Max 40 Max 2 Max 2 Max 20 Max 20 Max 20 Max 100 The Post/Zip code of the Card Holder s Billing ISO country code of the cardholder s billing address State code for US customers only Phone number at billing address Customer s surname Customer s first names First line of delivery address DeliveryAddress2 Max 100 Second line of delivery address DeliveryCity Max 40 City component of the address DeliveryPostCode Max 10 The Post/Zip code of the Card Holder s delivery address 26

28 DeliveryCountry Max 2 ISO country code of the cardholder s address Optional*: DeliveryState Max 2 State code for US customers only DeliveryPhone Max 20 Phone number at delivery address Customer Basket Max 255 Max 7500 chars. The customer s e mail address. See Direct Protocol for format of the basket field The current version of Direct integration does not send confirmation e mails to the customer. This field is only for your records You can use this field to supply details of the customer s order. This information will be displayed to you in My Sage Pay. GiftAidPayment Flag 0 = This transaction is not a Gift Aid charitable donation (default) 1 = This payment is a Gift Aid charitable donation and the customer has AGREED to donate the tax. Only of use if your vendor account is Gift Aid enabled. Setting this field means the customer has ticked a box on your site to indicate they wish to donate the tax. ApplyAVSCV2 Flag 0 = If AVS/CV2 enabled then check them. If rules apply, use rules (default). 1 = Force AVS/CV2 checks even if not enabled for the account. If rules apply, use rules. Using this flag you can fine tune the AVS/CV2 checks and rule set you ve defined at a transaction level. This is useful in circumstances where direct and trusted customer contact has been established and you wish to override the default security checks. Continued overleaf... 2 = Force NO AVS/CV2 checks even if enabled on account. 3 = Force AVS/CV2 checks even if not enabled for the account but DON T apply any rules. 27

29 Apply3DSecure Flag 0 = If 3D Secure checks are possible and rules allow, perform the checks and apply the authorisation rules (default). 1 = Force 3D Secure checks for this transaction only (if your account is 3Denabled) and apply rules. 2 = Do not perform 3D Secure checks for this transaction only and authorise. 3 = Force 3D Secure checks for this transaction (if your account is 3Denabled) but ALWAYS obtain an auth code, irrespective of rule base. ClientIPAddress Char. The IP address of the client connecting to your server making the payment. Using this flag you can fine tune the 3D Secure checks and rule set you ve defined, at a transaction level. This is useful in circumstances where direct and trusted customer contact has been established and you wish to override the default security checks. NB: If 3D Secure is ON for your account this field becomes compulsory. The full IP address which you can obtain from your server scripts which we will attempt to Geolocate AccountType 1 character E = Use the e commerce merchant account (default). C = Use the continuous authority merchant account (if present). M = Use the mail order, telephone order account (if present). This optional flag is used to tell the Sage Pay System which merchant account to use. If omitted, the system will use E, then M, then C by default. 28

30 Protocol for REMOVING a Token To remove a Token from the Sage Pay Database with either the Server or Direct integration method, the protocol will need to be posted to the following URL:.../gateway/service/removetoken.vsp C1: Request format Name Format Values Comments VPSProtocol in this release. Default or incorrect value is taken to be 3.00 Fixed 4. TxType REMOVETOKEN Should be in capitals. Vendor. Vendor Login Name. Used to authenticate your site. This should contain the Vendor Name supplied by Sage Pay when your account was created. Token 38 GUID Token that needs to be removed from the system 29

31 C2: Response format Name Format Values Comments VPSProtocol in this release. Default or incorrect value is taken to be 3.00 Fixed 4. Status OK, MALFORMED, INVALID. StatusDetail Max 255 Human readable text providing extra detail for the status message. You should always check this value if the status is not OK. 30

32 Token System Protocol and Integration Guideline URLs To REGISTER Card Details & generating a Token TEST Server Server Direct LIVE Server Server Direct To USE a Token (Standard Payment Gateway URL s) TEST Server Server register.vsp Direct register.vsp LIVE Server Server register.vsp Direct register.vsp To REMOVE a Token TEST Server Server & Direct LIVE Server Server & Direct 31