Payment API Guides - Hosted PCI

Payment API Guide

A HostedPCI checkout Web Services API can be accessed by any e-commerce system that needs to process credit card transactions with the use of the HPCI credit card token.
HPCI Web Service API can be used in any programming language that supports HTTPS calls. Examples include Java, PHP, and C #.Net.

Two things to keep in mind when making requests with parameters:

Parameter values should be UTF-8
Requests to the endpoints can be sent as NVP (Name-Value Pair)

Prerequisite

API userName	Provided by HPCI after the activation of the HPCI account.
API userPasskey	Provided by HPCI after the activation of the HPCI account.
HPCI Tokens	Have been generated and ready to use (implementation of HPCI iFrame Checkout Web Service )
HPCI HOST NAME	Provided by HPCI after the activation of the HPCI account.

Setting up API calls

API calls to HPCI are made over HTTPS to the provided endpoint URL.
Parameters are passed through the standard HTTP POST method.
Name-Value pairs are separated by ‘&’ character and are URL Encoded.

The java code will set up and call HPCI API URLs.
PHP and C# .Net have similar methods for POSTing HTTP URLs.
Full source code is available on file ‘ProxyHPCIProcessorApp.java’

public static String callUrl(String urlString, Map paramMap) { 
  String urlReturnValue = "";
  try {
    // Construct data
    StringBuffer dataBuf = new StringBuffer();
    boolean firstParam = true;
    for (String paramKey : paramMap.keySet()) {
      if (!firstParam) dataBuf.append("&");
      dataBuf.append(URLEncoder.encode(paramKey, "UTF-8")).append("=")
      .append(URLEncoder.encode(paramMap.get(paramKey), "UTF-8"));
      firstParam = false;
    }
    String data = dataBuf.toString();
    // Send data
    URL url = new URL(urlString);
    URLConnection conn = url.openConnection();
    conn.setDoOutput(true);
    OutputStreamWriter wr = new OutputStreamWriter(conn.getOutputStream());
    wr.write(data);
    wr.flush();
    // Get the response
    BufferedReader rd = new BufferedReader(new InputStreamReader(conn.getInputStream()));
    String line;
    while ((line = rd.readLine()) != null) {
      urlReturnValue = urlReturnValue + line;
    }
    wr.close();
    rd.close();
  } catch (Exception e) {
    e.printStackTrace();
    urlReturnValue = "";
  } 
  return urlReturnValue;
 } //END: callUrl

Required Parameters for Setting up API Calls:

Parameter	Value
apiVersion	[ 1.0.1]
apiType	[pxyhpci]
userName	[API UserId]
userPassKey	[API Passkey]
pxyTransaction.txnPayName	[Name of the Payment profile in use]

Some advanced configuration allows multiple payment gateways to be set up with HPCI and specified over API Calls. The above parameter can be used to specify the name. Default value is [DEF]. Profile names must be pre-arranged with the HPCI team.

Reading Results from API Calls

The result is returned in Name-Value pair format with URL Encoded Values
The java code on the side will read the result from HPCI API Calls and convert to String Map container object.

public static Map parseQueryString(String queryStr) {
 Map map = new HashMap();
 if (queryStr == null)
   return map;
 String[] params = queryStr.split("&"); 
 for (String param : params) {
   String name = "";
   String value = "";
   String[] paramPair = param.split("=");
   if (paramPair != null && paramPair.length > 0) {
     name = paramPair[0];
     if (paramPair.length > 1 && paramPair[1] != null) {
       try {
         value = URLDecoder.decode(paramPair[1], "UTF-8");
       } catch (UnsupportedEncodingException e) {
         logMessage("Could not decode:" + paramPair[1]);
       }
     }
   }
   map.put(name, value);
 } 
 return map;

Credit Card Authorization Transaction (AUTH)

API Endpoint: http://HPCI_API_HOSTNAME/iSynSApp/paymentAuth.action

Additional Required Parameters:

Card Number Related Parameters:

Parameters	Values
pxyCreditCard.cardType	[Type of Credit Card Used]
pxyCreditCard.creditCardNumber	[HPCI Token Representing Credit Card]
pxyCreditCard.expirationMonth	[Credit Card Expiry Month]
pxyCreditCard.expirationYear	[Credit Card Expiry Year]
pxyCreditCard.cardCodeVerification	[HPCI Token Representing CVV Code]

Transaction Amount Related Parameters:

Parameters	Values
pxyTransaction.txnAmount	[Amount to Authorize]
pxyTransaction.txnCurISO	[ “USD” or “CAD” or other ISO Currency Code]
pxyTransaction.merchantRefId	[Merchant Reference Number (order Id?)]
pxyTransaction.txnPayName	[“DEF” or a payment profile name]
pxyTransaction.txnComment	[Empty string or short comment not longer than 50 characters]
pxyTransaction.txnExtraParam1	[Not required for all gateways, please ask HPCI support for more details]
pxyTransaction.txnExtraParam2	[ Not required for all gateways, please ask HPCI support for more details]
pxyTransaction.txnExtraParam3	[Not required for all gateways, please ask HPCI support for more details]
pxyTransaction.txnExtraParam4	[Not required for all gateways, please ask HPCI support for more details]
pxyTransaction.txnExtraParam5	[Not required for all gateways, please ask HPCI support for more details]
pxyTransaction.txnInstallmentCount	[For installment count for the transaction amount not required for all gateways, optional for Global Collect gateway]
pxyTransaction.txnLangCode	[For language code for transaction, not required for all gateways, optional for Global Collect gateway]
pxyTransaction.txnDuplicateWindowSeconds	[For defining duplicate transaction validation window in seconds, not required for all gateways, optional for Authorize.net]

User Related Parameters:

Parameters	Values
pxyCustomerInfo.email	[Customer Email Address]
pxyCustomerInfo.customerId	[Customer User ID]

Billing Address Related Parameters:

Parameters	Values
pxyCustomerInfo.billingLocation.firstName	[Customer First Name]
pxyCustomerInfo.billingLocation.lastName	[Customer Last Name]
pxyCustomerInfo.billingLocation.address	[Customer Billing Street Address]
pxyCustomerInfo.billingLocation.city	[Customer Billing City]
pxyCustomerInfo.billingLocation.state	[Customer Billing State]
pxyCustomerInfo.billingLocation.zipCode	[Customer Billing Zipcode]
pxyCustomerInfo.billingLocation.country	[Customer Billing Country]
pxyCustomerInfo.billingLocation.phoneNumber	[Customers Billing Phone Number]

Shipping Address Related Parameters:

Parameters	Values
pxyCustomerInfo.shippingLocation.firstName	[Customer First Name for Shipping]
pxyCustomerInfo.shippingLocation.lastName	[Customer Last Name for Shipping]
pxyCustomerInfo.shippingLocation.address	[Customer Shipping Street Address]
pxyCustomerInfo.shippingLocation.city	[Customer Shipping City]
pxyCustomerInfo.shippingLocation.state	[Customer Shipping State]
pxyCustomerInfo.shippingLocation.zipCode	[Customer Shipping Zipcode]
pxyCustomerInfo.shippingLocation.country	[Customer Shipping Country]
pxyCustomerInfo.shippingLocation.phoneNumber	[Customers Shipping Phone Number]

Other Optional Parameters:

Parameters	Values
pxyCustomerInfo.customerIP	[Customer IP Address]
pxyOrder.invoiceNumber	[Additional Merchant Identifier (order Id)]
pxyOrder.description	[Order Description]
pxyOrder.totalAmount	[Total Amount of Order]

AUTH Request example:

pxyTransaction.txnPayName=DEF_WIRE&apiVersion=1.0.1&apiType=pxyhpci&userName=[API-USER]&userPassKey=[API_PASSKEY]&pxyCreditCard.creditCardNumber=[4200********1542].&pxyCreditCard.expirationMonth=10&pxyCreditCard.expirationYear=2024&pxyCreditCard.cardCodeVerification=200&pxyTransaction.txnAmount=0.95&pxyTransaction.txnCurISO=EUR&pxyTransaction.merchantRefId=[Merchant-ID]&pxyCustomerInfo.billingLocation.firstName= &pxyCustomerInfo.billingLocation.lastName=Livecareer&pxyCustomerInfo.customerId=2188000&pxyCustomerInfo.profileAction=add&pxyCustomerInfo.billingLocation.address=&pxyCustomerInfo.billingLocation.city=&pxyCustomerInfo.billingLocation.state=&pxyCustomerInfo.billingLocation.zipCode=&pxyCustomerInfo.billingLocation.country=&pxyTransaction.merchantPhoneNum=1800283878&pxyCustomerInfo.customerIP=52.242.23.44

AUTH Response example:

status=success&operId=&saleId=527389371&pxyResponse.threeDSEnrolled=&pxyResponse.threeDSAcsUrl=&pxyResponse.threeDSErrorDesc=&pxyResponse.processorRefId=5756ea78-19a8-41ba-8fad-27a1bc559da8&pxyResponse.processorType=wirecardResponse&pxyResponse.threeDSMessageId=&pxyResponse.threeDSSessionId=&pxyResponse.cardOnFileIssuerId=&pxyResponse.mappedParams=txnResponse.ccTypeEst=VISA&pxyResponse.threeDSARS=&pxyResponse.threeDSOrderId=&pxyResponse.gatewayToken.status=&pxyResponse.responseStatus.name=&pxyResponse.responseAVS2=&pxyResponse.responseStatus=approved&pxyResponse.gatewayToken=&pxyResponse.responseAVS1=&pxyResponse.responseAVS4=&pxyResponse.responseStatus.description=3d-acquirer:The resource was successfully created.&pxyResponse.threeDSCAVV=&pxyResponse.responseAVS3=&pxyResponse.gatewayToken.fullNativeResp=&pxyResponse.threeDSXid=&pxyResponse.threeDSProtoVersion=&pxyResponse.responseStatus.reasonCode=&pxyResponse.threeDSPARequest=&pxyResponse.responseCVV1=&pxyResponse.threeDSECI=&pxyResponse.responseCVV2=&pxyResponse.fullNativeResp=status-code=201.0000&status-description=3d-acquirer%3AThe+resource+was+successfully+created.&merchant-account-id=1b3be510-a992-48aa-8af9-6ba4c368a0ac&transaction-id=5756ea78-19a8-41ba-8fad-27a1bc559da8&request-id=2657335642007935744&transaction-type=purchase&transaction-state=success&completion-time-stamp=2020-05-05T15%3A32%3A16.000Z&requested-amount=0.95&account-holder=Livecareer&ip-address=52.242.23.44&descriptor=1800283878&payment-methods=&authorization-code=792301&api-id=elastic-api&provider-account-id=70010&pxyResponse.threeDSAcsPageData=&pxyResponse.gatewaySubToken2=&pxyResponse.threeDSTransactionId=&pxyResponse.gatewaySubToken1=&pxyResponse.gatewaySubToken3=&pxyResponse.merchantRefId=&pxyResponse.threeDSErrorId=&pxyResponse.txnPayName=DEF_WIRE&pxyResponse.responseStatus.code=201.0000&pxyResponse.threeDSSRS=

Credit Card Capture Transaction (CAPTURE)

API End point: HPCI_API_HOSTNAME/iSynSApp/paymentCapture.action

Additional Required Parameters:

Transaction Amount Related Parameters:

Parameters	Value
pxyTransaction.txnAmount	[Transaction Amount to Capture]
pxyTransaction.txnCurISO	[ “USD” or other ISO Currency Code]
pxyTransaction.merchantRefId	[Merchant Reference Number (order Id)]

Processor ID Parameters:

Parameters	Value
pxyTransaction.processorRefId	[Processor ID provided from Authorization or Sale]

The pxyTransaction.processorRefId is returned from AUTH (authorization) transaction and must be provided for funds to be captured.

CAPTURE Request example:

apiVersion=1.0.1&pxyTransaction.processorRefId=[AUTH_REF_ID]&userPassKey=[API-PASSKEY]&pxyTransaction.txnAmount=45.45&userName=[API-USERNAME]&pxyTransaction.txnCurISO=USD&apiType=pxyhpci&pxyTransaction.merchantRefId=[MerchantID]

CAPTURE Response example:


status=success&operId=&captureId=[CAPTURE_REF_ID]&pxyResponse.threeDSEnrolled=&pxyResponse.threeDSAcsUrl=&pxyResponse.threeDSErrorDesc=&pxyResponse.processorRefId=[AUTH_REF_ID]&pxyResponse.processorType=anetResponse&pxyResponse.threeDSMessageId=&pxyResponse.threeDSSessionId=&pxyResponse.cardOnFileIssuerId=&pxyResponse.mappedParams=txnResponse.ccTypeEst%3DMASTER_CARD&pxyResponse.threeDSARS=&pxyResponse.threeDSOrderId=&pxyResponse.gatewayToken.status=&pxyResponse.responseStatus.name=APPROVED&pxyResponse.responseAVS2=&pxyResponse.responseStatus=approved&pxyResponse.gatewayToken=&pxyResponse.responseAVS1=P&pxyResponse.responseAVS4=&pxyResponse.responseStatus.description=This+transaction+has+been+approved.&pxyResponse.threeDSCAVV=&pxyResponse.responseAVS3=&pxyResponse.gatewayToken.fullNativeResp=&pxyResponse.threeDSXid=&pxyResponse.threeDSProtoVersion=&pxyResponse.responseStatus.reasonCode=1&pxyResponse.threeDSPARequest=&pxyResponse.responseCVV1=&pxyResponse.threeDSECI=&pxyResponse.responseCVV2=&pxyResponse.fullNativeResp=txnResponse.target.transactionId%3D40048550306%26txnResponse.declined%3DN%26txnResponse.review%3DN%26txnResponse.responseReasonCode.notes%3D%26txnResponse.approved%3DY%26txnResponse.responseReasonCode.reasonText%3DThis%2Btransaction%2Bhas%2Bbeen%2Bapproved.%26txnResponse.responseText%3DThis%2Btransaction%2Bhas%2Bbeen%2Bapproved.%26txnResponse.responseCode.name%3DAPPROVED%26txnResponse.error%3DN%26txnResponse.responseCode.code%3D1%26txnResponse.responseCode.description%3DThis%2Btransaction%2Bhas%2Bbeen%2Bapproved.%26txnResponse.target.authorizationCode%3D3KG7PD%26txnResponse.responseReasonCode.responseReasonCode%3D1&pxyResponse.threeDSAcsPageData=&pxyResponse.gatewaySubToken2=&pxyResponse.threeDSTransactionId=&pxyResponse.gatewaySubToken1=&pxyResponse.gatewaySubToken3=&pxyResponse.merchantRefId=&pxyResponse.threeDSErrorId=&pxyResponse.txnPayName=DEF&pxyResponse.responseStatus.code=1&pxyResponse.threeDSSRS=

Credit Card Sale Transaction (SALE)

API End point: HPCI_API_HOSTNAME/iSynSApp/paymentSale.action

The SALE API call is performed exactly the same way as an AUTH, with a different API endpoint. The funds from a SALE operation will be immediately captured and a CAPTURE operation will not need to follow a SALE operation. However, CAPTURE operations should always follow AUTH operations in order to fully complete a credit card transaction when using AUTH

Credit Card Void Transaction (VOID)

API Endpoint: HPCI_API_HOSTNAME/iSynSApp/paymentVoid.action

Additional Required Parameters:

Transaction Amount Related Parameters

Parameters	Value
pxyTransaction.txnAmount	[Transaction Amount to VOID]
pxyTransaction.txnCurISO	[“USD” or other ISO Currency Code]
pxyTransaction.merchantRefId	[Merchant Reference Number (order Id)]

Processor ID Parameters:

Parameters	Value
pxyTransaction.processorRefId	[Processor ID provided from Authorization or Sale]

The pxyTransaction.processorRefId is returned from AUTH (authorization) transaction and must be provided for funds specified (partial or full) to be voided and funds relinquished back to the original credit card in question.

VOID Request example:

apiVersion=1.0.1&pxyTransaction.processorRefId=[AUTH_REF_ID]&userPassKey=[API-PASSKEY]&pxyTransaction.txnAmount=45&userName=[API-USER_NAME]&pxyTransaction.txnCurISO=USD&apiType=pxyhpci&pxyTransaction.merchantRefId=[MERCHANT-ID]

VOID Response example:

status=success&operId=&voidId=[VOID_REF_ID]&pxyResponse.threeDSEnrolled=&pxyResponse.threeDSAcsUrl=&pxyResponse.threeDSErrorDesc=&pxyResponse.processorRefId=[AUTH_REF-ID]&pxyResponse.processorType=anetResponse&pxyResponse.threeDSMessageId=&pxyResponse.threeDSSessionId=&pxyResponse.cardOnFileIssuerId=&pxyResponse.mappedParams=txnResponse.ccTypeEst%3D&pxyResponse.threeDSARS=&pxyResponse.threeDSOrderId=&pxyResponse.gatewayToken.status=&pxyResponse.responseStatus.name=APPROVED&pxyResponse.responseAVS2=&pxyResponse.responseStatus=approved&pxyResponse.gatewayToken=&pxyResponse.responseAVS1=P&pxyResponse.responseAVS4=&pxyResponse.responseStatus.description=This+transaction+has+been+approved.&pxyResponse.threeDSCAVV=&pxyResponse.responseAVS3=&pxyResponse.gatewayToken.fullNativeResp=&pxyResponse.threeDSXid=&pxyResponse.threeDSProtoVersion=&pxyResponse.responseStatus.reasonCode=1&pxyResponse.threeDSPARequest=&pxyResponse.responseCVV1=&pxyResponse.threeDSECI=&pxyResponse.responseCVV2=&pxyResponse.fullNativeResp=txnResponse.target.transactionId%3D40048550306%26txnResponse.declined%3DN%26txnResponse.review%3DN%26txnResponse.responseReasonCode.notes%3D%26txnResponse.approved%3DY%26txnResponse.responseReasonCode.reasonText%3DThis%2Btransaction%2Bhas%2Bbeen%2Bapproved.%26txnResponse.responseText%3DThis%2Btransaction%2Bhas%2Bbeen%2Bapproved.%26txnResponse.responseCode.name%3DAPPROVED%26txnResponse.error%3DN%26txnResponse.responseCode.code%3D1%26txnResponse.responseCode.description%3DThis%2Btransaction%2Bhas%2Bbeen%2Bapproved.%26txnResponse.target.authorizationCode%3D3KG7PD%26txnResponse.responseReasonCode.responseReasonCode%3D1&pxyResponse.threeDSAcsPageData=&pxyResponse.gatewaySubToken2=&pxyResponse.threeDSTransactionId=&pxyResponse.gatewaySubToken1=&pxyResponse.gatewaySubToken3=&pxyResponse.merchantRefId=&pxyResponse.threeDSErrorId=&pxyResponse.txnPayName=DEF&pxyResponse.responseStatus.code=1&pxyResponse.threeDSSRS=

Credit Card Credit Transaction (CREDIT)

API End point URL: HPCI_API_HOSTNAME/iSynSApp/paymentCredit.action

Additional Required Parameters:

Transaction Amount Related Parameters:

Parameters	Value
pxyTransaction.txnAmount	[Transaction Amount to Credit]
pxyTransaction.txnCurISO	[ “USD” or other ISO Currency Code]
pxyTransaction.merchantRefId	[Merchant Reference Number (order Id)]

Processor ID Parameters:

Parameters	Value
pxyTransaction.processorRefId	[Processor ID provided from Authorization or Sale]

The pxyTransaction.processorRefId is returned from AUTH (authorization) transaction and must be provided for funds specified (partial or full) to be credited back to the original credit card in question.

CREDIT Request example:

apiVersion=1.0.1&pxyTransaction.processorRefId=[AUTH_REF_ID]&userPassKey=[API_PASSKEY]&pxyTransaction.txnAmount=22&userName=[API_USERNAME]&pxyTransaction.txnCurISO=USD&apiType=pxyhpci&pxyTransaction.merchantRefId=[MERCHANT_ID]

CREDIT Response example:

status=success&operId=&creditId=529326875&pxyResponse.threeDSEnrolled=&pxyResponse.threeDSAcsUrl=&pxyResponse.threeDSErrorDesc=&pxyResponse.processorRefId=40048764072&pxyResponse.processorType=anetResponse&pxyResponse.threeDSMessageId=&pxyResponse.threeDSSessionId=&pxyResponse.cardOnFileIssuerId=&pxyResponse.mappedParams=txnResponse.ccTypeEst%3DMASTER_CARD&pxyResponse.threeDSARS=&pxyResponse.threeDSOrderId=&pxyResponse.gatewayToken.status=&pxyResponse.responseStatus.name=APPROVED&pxyResponse.responseAVS2=&pxyResponse.responseStatus=approved&pxyResponse.gatewayToken=&pxyResponse.responseAVS1=P&pxyResponse.responseAVS4=&pxyResponse.responseStatus.description=This+transaction+has+been+approved.&pxyResponse.threeDSCAVV=&pxyResponse.responseAVS3=&pxyResponse.gatewayToken.fullNativeResp=&pxyResponse.threeDSXid=&pxyResponse.threeDSProtoVersion=&pxyResponse.responseStatus.reasonCode=1&pxyResponse.threeDSPARequest=&pxyResponse.responseCVV1=&pxyResponse.threeDSECI=&pxyResponse.responseCVV2=&pxyResponse.fullNativeResp=txnResponse.target.transactionId%3D40048764072%26txnResponse.declined%3DN%26txnResponse.review%3DN%26txnResponse.responseReasonCode.notes%3D%26txnResponse.approved%3DY%26txnResponse.responseReasonCode.reasonText%3DThis%2Btransaction%2Bhas%2Bbeen%2Bapproved.%26txnResponse.responseText%3DThis%2Btransaction%2Bhas%2Bbeen%2Bapproved.%26txnResponse.responseCode.name%3DAPPROVED%26txnResponse.error%3DN%26txnResponse.responseCode.code%3D1%26txnResponse.responseCode.description%3DThis%2Btransaction%2Bhas%2Bbeen%2Bapproved.%26txnResponse.target.authorizationCode%3D%26txnResponse.responseReasonCode.responseReasonCode%3D1&pxyResponse.threeDSAcsPageData=&pxyResponse.gatewaySubToken2=&pxyResponse.threeDSTransactionId=&pxyResponse.gatewaySubToken1=&pxyResponse.gatewaySubToken3=&pxyResponse.merchantRefId=&pxyResponse.threeDSErrorId=&pxyResponse.txnPayName=DEF&pxyResponse.responseStatus.code=1&pxyResponse.threeDSSRS=

Gateway Tokenization

API endpoint: HPCI_API_HOSTNAME/iSynSApp/paymentGatewayToken.action

Tokenization Related Parameters:

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]

Along with these Parameters, there are some additional parameters required by certain Gateways. To find the complete parameters please look at the corresponding gateways page. The list can be found in the gateways section of Documentation.

Automated Clearing House (ACH)

API endpoint: HPCI_API_HOSTNAME/iSynSApp/paymentACH.action

In order to enable using ACH tokens returned by HPCI iFrame in the API call, please enable ACH Token (Y or N) in the payment profile setup.

Currently, We offer ACH payment API with Elavon and IATS .

ACH Related Parameters:

PARAMETERS	VALUE
pxyACHRecord.bankAccountNumber	Tokenized ACH number value returned by HPCI iFrame
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]
pxyTransaction.txnAmount	[amount]

Automated Clearing House API Call:

Request:

apiVersion=1.0.1&apiType=pxyhpci&userName=[API_Uname}&userPassKey=[API-Pword]&PxyACHRecord.bankAccountNumber=11000000100000000000004569&pxyTransaction.txnAmount=2.02&pxyTransaction.txnCurISO=CAD&pxyTransaction.merchantRefId=e9fbb16c-d2c8-4&pxyTransaction.txnPayName=DEF_ELV_ACH&pxyCustomerInfo.email=user%40testemail.com&pxyCustomerInfo.customerId=72c10e80-cdc4-4&pxyCustomerInfo.billingLocation.firstName=Ont&pxyCustomerInfo.billingLocation.lastName=Admin&pxyCustomerInfo.billingLocation.address=22+Hilltop+St&pxyCustomerInfo.billingLocation.city=Poinsan&pxyCustomerInfo.billingLocation.state=ON&pxyCustomerInfo.billingLocation.zipCode=M9K8U6&pxyCustomerInfo.billingLocation.country=CAN

Response:

status=success&operId=&authId=71900&pxyResponse.threeDSEnrolled=&pxyResponse.threeDSAcsUrl=&pxyResponse.threeDSErrorDesc=&pxyResponse.processorRefId=080922ED4-51F1721C-17C4-422D-A2D8-35B38B6FB7A8&pxyResponse.processorType=elavonResponse&pxyResponse.threeDSMessageId=&pxyResponse.threeDSSessionId=&pxyResponse.cardOnFileIssuerId=&pxyResponse.threeDSDDCPageData=&pxyResponse.threeDSARS=&pxyResponse.threeDSOrderId=&pxyResponse.threeDSAcsTxnId=&pxyResponse.gatewayToken.status=&pxyResponse.threeDSErrorSubId=&pxyResponse.responseStatus.name=&pxyResponse.threeDSReasonDesc=&pxyResponse.responseAVS2=&pxyResponse.responseStatus=approved&pxyResponse.gatewayToken=&pxyResponse.responseAVS1=&pxyResponse.responseAVS4=&pxyResponse.responseStatus.description=APPROVAL&pxyResponse.threeDSCAVV=&pxyResponse.responseAVS3=&pxyResponse.gatewayToken.fullNativeResp=&pxyResponse.threeDSXid=&pxyResponse.threeDSProtoVersion=&pxyResponse.responseStatus.reasonCode=APPROVAL&pxyResponse.threeDSPARequest=&pxyResponse.threeDSDDCUrl=&pxyResponse.responseCVV1=&pxyResponse.threeDSECI=&pxyResponse.responseCVV2=&pxyResponse.cardOnFileSettlementDate=&pxyResponse.threeDSErrorSubIdType=&pxyResponse.threeDSAcsPageData=&pxyResponse.gatewaySubToken2=&pxyResponse.threeDSTransactionId=&pxyResponse.gatewaySubToken1=&pxyResponse.gatewaySubToken3=&pxyResponse.declineSource=&pxyResponse.threeDSCavvAlgorithm=&pxyResponse.merchantRefId=&pxyResponse.threeDSErrorId=&pxyResponse.responseStatus.code=APPROVAL&pxyResponse.threeDSReasonCode=&pxyResponse.threeDSSRS=

API Response Variables

The API will call responds with the following name-value pairs.

Parameter	Value	Additional Info.
status	[success \| error]	The Status response variable indicates if the API call is well-formed, with an appropriate result. An error result will indicate that either the request was not well-formed or that the transaction was not successful. A success result will indicate that the request was well-formed and that the attempted transaction was successful.
pxyResponse.responseStatus	[approved I declined \| error \| review \| 3dsecure]	The only transaction response considered successful for pxyResponse.responseStatus is the approved status. Any other response should be considered an error. In case of a successful transaction, the authorization code may be obtained as per the following response variable:
pxyResponse.processorRefId	[Valid Authorization Code from Credit Card Processor]	Once the authorization code is obtained through pxyResponse.processorRefId it should be used for subsequent calls for the following operations: CAPTURE, CREDIT, and VOID. See the documentation for these operations below.
pxyResponse.processorType	[name of payment processor or gateway processing the transaction]	The response value will be one of: pflResponse – Paypal Payflow Processor cybResponse – CyberSource Processor strResponse – Star Card Processor anetResponse – Authorize.Net Processor monResponse – Moneris Response psiResponse – PSiGate Response ponResponse – Paymentech Orbital Processor wproResponse – Paypal Website PaymentPro Processor snetResponse – SecureNet Processor ipayResponse – Planet Payment iPay Processor prismpayResponse – Prism Pay Processor worldpayResponse – WorldPay Processor optimalResponse – Optimal Processor globalcResponse – Global Collect Processor rakutenResponse – Rakuten Processor ogoneResponse – Ogone Processor 3dsecResponse – 3D Secure response msgDispatchResponse – Message Dispatch response fileDispatchResponse – File Dispatch response

The following response values are used to determine why a particular transaction has failed for approval (decline, error, or review states).

Parameter	Value
pxyResponse.responseStatus.name	[short description of response]
pxyResponse.responseStatus.code	[alphanumeric code representing response]
pxyResponse.responseStatus.description	[long description and informational text of response]
pxyResponse.responseStatus.reasonCode	[Gateway specific reason code]

This field contains the reason code for a successful or unsuccessful transaction reported by the payment gateway. This field is populated if available.

Parameter	Value
pxyResponse.fullNativeResp	[Gateway specific result set, URL encoded]

This field returns the entire result set from the payment processor or gateway. The actual gateway used can be found by inspecting the pxyResponse.processorType response field. The native response is flattened into name-value pairs, separated with & and URL encoded.

Fraud Detection Service Parameters (Optional)

The Authorization (and Sale) API’s also allows for passing fraud detection service parameters.
Please Enable ‘Fraud Detection Service’ before passing the fraud detection parameters.
Fraud Detection parameters are passed in an array, notated by [] array syntax.
Repeat the following parameters pairs for each parameter that is required by the service.

Parameters	Value
fraudChkParamList[x]. name	[Parameter Name]
fraudChkParamList[x]. value	[Parameter Value]
fraudChkParamList[x]. type	[Optional [Parameter Type, either “data” or “map”]
fraudChkParamList[x]. mappedValue	[optional [Parameter Mapped Value]
fraudChkParamList[x]. groupIdx	[optional [Parameter Group Index]

Where [x] starts at 0 and increases with each parameter name and value added. Please refer respective documentation provided by the supported fraud detection service (Kount, Retail Decision, MaxMind) to find the required parameters for a successful call.

Fraud Service Related Response Fields

The following response values are used to determine the status of a fraud verification call if fraud management was enabled.

Parameters	Value
frdChkResp.fullNativeResp	[full response of a call to fraud checking service]

Kount Related Service Parameters (Optional)

As Part of our Kount Integration, Hosted PCI allows us to pass mapped values for AVST, AVSZ, CVVR, UDF according to the Kount documentation.

AVST, AVSZ, CVVR

AVST, AVSZ, CVVR are used to pass address verification and CVV verification codes from the payment gateway to Kount.

Because the codes from the gateway are going to be different from the possible code values for Kount (possible values are “M” or “N”), you need to create a mapping for every call that will define the relationship between gateway codes and the kount codes.

Example: If you are using PayPal Payflow pro and they are reporting back AVS1 code Y and AVS2 code Y and CVV1 code Y (avs1= Y, avs2 = Y, cvv1=Y) and you want those values to be passed to Kount as a match then you are going to populate the following in your request to HostedPCI.

Parameter	Value
fraudChkParamList[x].name	[AVST]
fraudChkParamList[x].value	[Y]
fraudChkParamList[x].type	[map]
fraudChkParamList[x].mappedValue	[M]
fraudChkParamList[y].name	[AVSZ]
fraudChkParamList[y].value	[Y]
fraudChkParamList[y].type	[map]
fraudChkParamList[y].mappedValue	[M]
fraudChkParamList[z].name	[CVVR]
fraudChkParamList[z].value	[Y]
fraudChkParamList[z].type	[map]
fraudChkParamList[z].mappedValue	[M]

All possible mapping combinations that are applicable to your use case and your payment gateway should be included in the request.

UDF

Kount also allows for User Defined Field (UDF) which can be added to the request similar to the way we did the AVS mapping.

– If we want to pass to Kount 2 UDF’s, one for BILL_COMPANY_NAME, and the second SHIP_COMPANY_NAME, we can pass the following.

Parameter	Value
fraudChkParamList[x].groupIdx	[1]
fraudChkParamList[x].name	[UDFN]
fraudChkParamList[x].value	[BILL_COMPANY_NAME]
fraudChkParamList[x].groupIdx	[1]
fraudChkParamList[x].name	[UDFV]
fraudChkParamList[x].value	[HostedPCI]
fraudChkParamList[x].groupIdx	[2]
fraudChkParamList[x].name	[UDFN]
fraudChkParamList[x].value	[SHIP_COMPANY_NAME]
fraudChkParamList[x].groupIdx	[2]
fraudChkParamList[x].name	[UDFV]
fraudChkParamList[x].value	[HostedPCI]

It’s also possible to pass some values from the gateway response dynamically to a UDF, please contact HostedPCI if you need it.

Accertify Fraud Service

HostedPCI has integrated with Accertify Fraud Service in order to extend out options for the fraud services we work with.

Credentials:

API URL code
API Username
API Password

Credentials on File

HostedPCI’s Credentials on File feature allows merchants the ability to store the issuer ID alongside the credit card to be used for a later date. With Credentials on File, Merchants will be able to charge a customer’s card even when the customer is not present. The Credentials on File can be used along with the 3D Secure feature or as a feature on its own.

The following parameters are required to set up a transaction with the credentials on file feature.

Parameter	Value
pxyTransaction.cardOnFileTxnType	[TxnType]
pxyTransaction.cardOnFileTxnRef	[TxnRedID]
pxyTransaction.cardOnFileIssuerId	[IssuerID]
pxyTransaction.cardOnFileOrigAmt	[Original Amount]
pxyTransaction.cardOnFileFraudIndicator	[FraudIndicator]

These are not the only parameters required for Credentials on File Transaction. Each of the Gateway is different from the other. To get the full list of parameter please look at the corresponding gateway page. It can be found in the gateway list in the Documentation.

3D Secure (Verified by Visa and MasterCard securecode) Parameters (Optional)

The Authorization (and Sale) API also allows for passing payer authentication information.
3D Secure information is OPTIONAL and will be required only if the 3D Secure service has been SUBSCRIBED with the payment gateway.

Parameters	Value
pxyThreeDSecAuth.actionName	[Empty string when no 3D Secure action is requested. Pass “verifyenroll” when card enrollment needs to be verified. Pass “verifyresp” when an authentication response needs to be verified.]
pxyThreeDSecAuth.authTxnId	[Authentication id received from “verifyenroll” call.]
pxyThreeDSecAuth.paReq	[The payer authentication request value received from “verifyenroll” call]
pxyThreeDSecAuth.paRes	[The payer authentication response value received from pin verification call]
pxyThreeDSecAuth.authSignComboList[x]	[The combined statuses of Authentication Result + Signature Result that are acceptable. The results are received after the verification call is completed by HPCI service before requesting an Authorization from the payment gateway. Typical values are “YY”, “AY” and “UY”. Where [x] starts at 0 and increases with each item added.]

Item RelatedParametersOptional)

The Authorization (and Sale) API’s also for the passing of individual order item information.
Line item information is Optional.
Order Items are passed as parameters in an array, notated by [] array syntax. Repeat the following parameters for each order in the order that is being processed.

Parameters	Value
pxyOrder.orderItems[x].itemId	[Merchant Item ID]
pxyOrder.orderItems[x].itemName	[Merchant Item Name]
pxyOrder.orderItems[x]. itemDescription	[Merchant Item Description]
pxyOrder.orderItems[x]. itemQuantity	[item Quantity Ordered]
pxyOrder.orderItems[x]. itemPrice	[item Price per Unit]
pxyOrder.orderItems[x]. itemTaxable	[Is Item Taxable Y/N]

Where [x] starts at 0 and increases with each item added.

3D Secure Related Response Fields

If the response Status is 3D Secure then the 3D Secure PIN verification is required to proceed with authorization.
Please review the ‘3D Secure PIN verification’ section for details. Use the following parameters to initiate the PIN verification call:

Parameters	Value
pxyResponse.threeDSAcsUrl	[ACS Url received from the “verifyenroll” call]
pxyResponse.threeDSTransactionId	[Transaction Id received from the “verifyenroll” call]
pxyResponse.threeDSPARequest	[Payer Authentication Request received from the “verifyenroll” call]

These 3 response variables will be provided verbatim from the payment gateway configured for the HPCI API account. Documentation from the payment gateway should be used to discern the error in question.

3D Secure 1.0 Cardinal Commerce Implementation

HostedPCI offers ThreeD Secure 1.0 implementation with Cardinal Commerce.
The following parameters are required to make a successful 3D secure 1.0 authentication with Cardinal Commerce.
The table below contains parameters required to make a ‘verifyenroll’ call to ensure the credit card is eligible for 3d Secure.
Few different gateways have 3DS flow implemented with Cardinal Commerce including Authorize .Net, Braintree, Chase Paymentech, SafeCharge, and Wirecard.

Parameters	Value
pxyThreeDSecAuth.actionName	verifyenroll
pxyTransaction.txnPayName	3dsPayProfile – Name of the 3d secure payment profile.
pxyThreeDSecAuth.callMode	reportall- will return once 3d secure has been authenticated with credentials for second API call

If the ‘verifyenroll’ call was successful it will return some parameters with data needed for the second API call (verifyresp).
The table below lists the parameters required to make a successful pin verification call for 3DS 1.0 with cardinal commerce.

PARAMETERS	VALUE
pxyTransaction.txnPayName	[3ds payment profile name]
pxyThreeDSecAuth.actionName	[verifyenroll]
pxyThreeDSecAuth.callMode	reportall
pxyThreeDSecAuth.authCAVV	[response from the first API call “pxyResponse.threeDSCAVV”]
pxyThreeDSecAuth.authTxnId	[response from the first API call “pxyResponse.threeDSXid”]
pxyThreeDSecAuth.authAcsUrl	[response from the first API call “pxyResponse.threeDSAcsUrl”]
pxyThreeDSecAuth.paReq	[response from the first API call “pxyResponse.threeDSPARequest”]
pxyThreeDSecAuth.protocolVersion	[response from the first API call “pxyResponse.threeDSProtoVersion”]
pxyThreeDSecAuth.authECI	[response from the first API call “pxyResponse.threeDSECI”]