SagePay PI (UK) Payment Integration
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.actionAPI 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=124875402698Response:
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] |