SagePay PI (UK)

About SagePay PI:

With sagepay pi you can securely transmit sensitive card data from the customer’s browser to Sage Pay without any details passing through your server. You will need to secure your site with TLS (1.2 or the latest version) and ensure all communications are over HTTPS.

Sage supplies products to all sorts of businesses no matter how big or small the company is.

Implemented Features:

Feature Level of Support
Auth Implemented
Sale (Auth+Capture) Implemented
Capture Implemented
Void Implemented
Credit Implemented
Gateway Tokenization Implemented
3DS Full Integration Implemented

Authentication and Security Credentials:

  • Merchant ID
  • Merchant Key

Supported Parameters:

Key Name Format Mandatory Descriptions
apiVersion Numerical Required “1.0.1”
apiType Alphabetical Required “pxyhpci”
userName Alphanumeric Required API Username
userPassKey Alphanumeric Required API PassKey
pxyCreditCard.creditCardNumber Numerical Required HostedPCI Token Representing Credit Card
pxy.CreditCard.cardCodeVerification Numerical Optional HostedPCI Token Representing CVV Code
pxyCreditCard.expirationMonth Numerical Required Expiration month with 2 digits for example, for December use “12”
pxyCreditCard.expirationYear Numerical Required Expiration year with 4 digits for example, for 2025, use “2025”
pxyTransaction.txnCurISO Alphabetical Required 3 letter ISO Currency Code for example, “USD” or “CAD”
pxyTransaction.txnAmount Numerical Required Amount to Authorize, for example for $10.50 use 10.50
pxyTransaction.merchantRefId Numerical Required Merchant reference number can be order id or invoice id
pxyTransaction.txnPayName Alphanumeric Required HostedPCI payment profile name, for example “DEF”
pxyCustomerInfo.email Alphanumeric Optional Customer’s Email Address
pxyCustomerInfo.billingLocation.firstName Alphabetical Optional Customer’s First Name
pxyCustomerInfo.billingLocation.lastName Alphabetical Optional Customer’s Last Name
pxyCustomerInfo.billingLocation.phoneNumber Numerical Optional Billing Phone Number
pxyCustomerInfo.billingLocation.fax Numerical Optional Billing Fax Phone Number
pxyCustomerInfo.billingLocation.address Alphanumeric Optional Customer’s Billing Address
pxyCustomerInfo.billingLocation.address2 Alphanumeric Optional Secondary Billing Address
pxyCustomerInfo.billingLocation.city Alphabetical Optional Customer’s Billing City
pxyCustomerInfo.billingLocation.state Alphabetical Optional Customer’s Billing State or Province
pxyCustomerInfo.billingLocation.zipCode Numerical Optional Customer’s Billing Zip Code or Postal Code
pxyCustomerInfo.billingLocation.country Alphabetical Optional Customer’s Billing Country
pxyCustomerInfo.shippingLocation.firstName Alphabetical Optional Customer’s First Name for Shipping
pxyCustomerInfo.shippingLocation.lastName Alphabetical Optional Customer’s Last Name for Shipping
pxyCustomerInfo.shippingLocation.address Alphanumeric Optional Customer’s Shipping Address
pxyCustomerInfo.shippingLocation.address2 Alphanumeric Optional Secondary Shipping Address
pxyCustomerInfo.shippingLocation.city Alphabetical Optional Customer’s Shipping City
pxyCustomerInfo.shippingLocation.state Alphabetical Optional Customer’s Shipping State or Province
pxyCustomerInfo.shippingLocation.zipCode Alphabetical Optional Customer’s Shipping Zip Code or Postal Code
pxyCustomerInfo.shippingLocation.country Alphabetical Optional Customer’s Shipping Country
pxyOrder.shippingAmount Numerical Optional Cost for Shipping
pxyOrder.taxAmount Numerical Optional Tax Amount

API Endpoint URL:

https://[HPCI_API_HOSTENAME]/iSynSApp/paymentAuth.action

API Request Body:

apiVersion=1.0.1&apiType=pxyhpci&userName=[APIuserName]&userPassKey=[APIPassKey]&pxyCreditCard.creditCardNumber=[CreditCardToken]&pxyCreditCard.cardCodeVerification=[CVVToken]&pxyCreditCard.expirationMonth=[ExpiryMonth]&pxyCreditCard.expirationYear=[ExpiryYear]&pxyTransaction.txnCurISO=[Currency]&pxyTransaction.txnAmount=[Amount]&pxyTransaction.merchantRefId=[UniqueMerchantRefID]&pxyTransaction.txnPayName=[ProfileName]&pxyTransaction.txnComment=[ShortComment]&pxyCustomerInfo.billingLocation.firstName=[CustomerFirstName]&pxyCustomerInfo.billingLocation.lastName=[CustomerLastName]&pxyCustomerInfo.billingLocation.address=[BillingStreetAddress]&pxyCustomerInfo.billingLocation.city=[BillingCity]&pxyCustomerInfo.billingLocation.state=[State/Province]&pxyCustomerInfo.billingLocation.zipCode=[ZipCode/PostalCode]&pxyCustomerInfo.billingLocation.country=[Country]&pxyCustomerInfo.shippingLocation.firstName=[ShippingFirstName]&pxyCustomerInfo.shippingLocation.lastName=[ShippingLastName]&pxyCustomerInfo.shippingLocation.address=[ShippingStreetAddress]&pxyCustomerInfo.shippingLocation.city=[ShippingCity]&pxyCustomerInfo.shippingLocation.state=[ShippingState/Province]&pxyCustomerInfo.shippingLocation.zipCode=[ShippingZipCode/PostalCode]&pxyCustomerInfo.shippingLocation.country=[ShippingCountry]

SagePay PI Gateway Tokenization:

Parameters Required for Gateway Tokenization:
PARAMETERS VALUE
pxyCreditCard.creditCardNumber [HostedPCI Token]
pxyCreditCard.cardCodeVerification [HostedPCI CVV place holder]
pxyCreditCard.expirationMonth [Credit Card expire month]
pxyCreditCard.expirationYear [Credit Card expire year]
pxyTransaction.txnPayName [Profile Name provided by HostedPCI]
pxyCustomerInfo.billingLocation.firstName [Client’s first name as it appears on the card]
pxyCustomerInfo.billingLocation.lastName [Client’s last name as it appears on the card]
Additional Parameters Required for SagePay PI Gateway Tokenization:
PARAMETERS VALUE
pxyCustomerInfo.billingLocation.city [Billing City]
pxyCustomerInfo.billingLocation.Country [Billing Country]
pxyCustomerInfo.billingLocation.address [Billing street address]
pxyCustomerInfo.billingLocation.State [Billing State]
pxyCustomerInfo.billingLocation.zipCode [Billing Zip/Postal Code]
pxyTransaction.txnCurISO [currency ISO]
SagePay PI Gateway Tokenization API Call:
Request:
pxyCreditCard.creditCardNumber=4000000105559&pxyCustomerInfo.billingLocation.city=Toronto&userPassKey=[APIuserpasskey]&pxyCreditCard.expirationMonth=09&userName=[APIusername]&pxyCreditCard.cardCodeVerification=200&pxyTransaction.txnPayName=sagepay-pi&pxyTransaction.txnCurISO=GBP&pxyCustomerInfo.billingLocation.zipCode=M7H6G5&apiVersion=1.0.1&pxyCreditCard.expirationYear=2022&pxyCustomerInfo.billingLocation.lastName=Customer&pxyCustomerInfo.billingLocation.firstName=Test&pxyCustomerInfo.billingLocation.state=ON&pxyCustomerInfo.billingLocation.address=12596++West+Bayaud+Ave&apiType=pxyhpci&pxyCustomerInfo.billingLocation.country=Canada&pxyTransaction.merchantRefId=124875402698
Response:
status=success&operId=&tokenId=590744723&mappedCC=4000000105559&ccBIN=&pxyResponse.threeDSEnrolled=&pxyResponse.threeDSAcsUrl=&pxyResponse.threeDSErrorDesc=&pxyResponse.processorRefId=FB8C6BA6-64B3-ED87-2914-B8F0C8D5A32D&pxyResponse.processorType=sagepaypiResponse&pxyResponse.threeDSMessageId=&pxyResponse.threeDSSessionId=&pxyResponse.cardOnFileIssuerId=&pxyResponse.mappedParams=txnResponse.ccTypeEst%3DVISA&pxyResponse.threeDSARS=&pxyResponse.threeDSOrderId=&pxyResponse.gatewayToken.status=&pxyResponse.responseStatus.name=&pxyResponse.responseAVS2=NotMatched&pxyResponse.responseStatus=approved&pxyResponse.gatewayToken=1B3948C1-174A-4FF2-A1FE-0F1526A6A262&pxyResponse.responseAVS1=NotMatched&pxyResponse.responseAVS4=&pxyResponse.responseStatus.description=The+Authorisation+was+Successful.&pxyResponse.threeDSCAVV=&pxyResponse.responseAVS3=&pxyResponse.gatewayToken.fullNativeResp=&pxyResponse.threeDSXid=&pxyResponse.threeDSProtoVersion=&pxyResponse.responseStatus.reasonCode=&pxyResponse.threeDSPARequest=&pxyResponse.responseCVV1=Matched&pxyResponse.threeDSECI=&pxyResponse.responseCVV2=&pxyResponse.fullNativeResp=rawHTTPResp%3D201%26rawJSONResp%3D%257B%2522statusCode%2522%253A%25220000%2522%252C%2522statusDetail%2522%253A%2522The%2BAuthorisation%2Bwas%2BSuccessful.%2522%252C%2522transactionId%2522%253A%2522FB8C6BA6-64B3-ED87-2914-B8F0C8D5A32D%2522%252C%2522transactionType%2522%253A%2522Deferred%2522%252C%2522retrievalReference%2522%253A8095875%252C%2522bankResponseCode%2522%253A%252200%2522%252C%2522bankAuthorisationCode%2522%253A%2522999777%2522%252C%2522paymentMethod%2522%253A%257B%2522card%2522%253A%257B%2522cardType%2522%253A%2522Visa%2522%252C%2522lastFourDigits%2522%253A%25225559%2522%252C%2522expiryDate%2522%253A%25220922%2522%252C%2522cardIdentifier%2522%253A%25221B3948C1-174A-4FF2-A1FE-0F1526A6A262%2522%252C%2522reusable%2522%253Atrue%257D%257D%252C%2522amount%2522%253A%257B%2522totalAmount%2522%253A100%252C%2522saleAmount%2522%253A100%252C%2522surchargeAmount%2522%253A0%257D%252C%2522currency%2522%253A%2522GBP%2522%252C%2522fiRecipient%2522%253A%257B%257D%252C%2522status%2522%253A%2522Ok%2522%252C%2522avsCvcCheck%2522%253A%257B%2522status%2522%253A%2522SecurityCodeMatchOnly%2522%252C%2522address%2522%253A%2522NotMatched%2522%252C%2522postalCode%2522%253A%2522NotMatched%2522%252C%2522securityCode%2522%253A%2522Matched%2522%257D%252C%25223DSecure%2522%253A%257B%2522status%2522%253A%2522CardNotEnrolled%2522%257D%257D&pxyResponse.threeDSAcsPageData=&pxyResponse.gatewaySubToken2=&pxyResponse.threeDSTransactionId=&pxyResponse.gatewaySubToken1=&pxyResponse.gatewaySubToken3=&pxyResponse.merchantRefId=&pxyResponse.threeDSErrorId=&pxyResponse.txnPayName=sagepay-pi&pxyResponse.responseStatus.code=0000&pxyResponse.threeDSSRS=

3D secure 2.0 implementation with SagePay PI

  • In order to implement 3D secure 2.0 with sagePay pi, the following parameters are required.
  • The table below contains the additional required parameters for the first API call (verifyenroll).
PARAMETERS VALUES
pxyTransaction.txnPayName [Sage Pay Payment profile name ]
pxyThreeDSecAuth.actionName [verifyenroll]
pcyThreeDSecAuth.callMode [reportall]
pxyCustomerInfo.sessionId [sessionId]
pxyCustomerInfo.browserAcceptHeader [browser accept header]
pcyCustomerInfo.browserUserAgentHeader [browser user agent header]

  • If ‘verifyenroll’ call was successful and 3ds was enrolled the response will return some parameters required for the second API call (verifyresp).

  • The table below contains parameters required for the ‘verifyresp’ call.

PARAMETERS VALUES
pxyThreeDSecAuth.actionName [verifyresp]
pcyThreeDSecAuth.authTxnId [pxyResponse.threeDsTransactionID – response of verifyenroll call]
pxyThreeDSecAuth.paReq [pxyResponse.threeDSPARequest – response ofverifyenroll call]
pxyThreeDSecAuth.authAcsUrl [pxyResponse.threeDSAcsUrl – response ofverifyenroll call]
pxyCustomerInfo.sessionId [same as verifyenroll call]