Checkout Web Services API Guide

The hostedPCI Checkout Web Services API can be accessed by any ecommerce system that needs to process credit card transactions with the use of the HPCI credit card token. Tokens can be obtained through the implementation of the HPCI Express Iframe solution or the HPCI full page proxy solution. This document assumes that HPCI tokens have been generated and available for use with the HPCI Web Service API.

API Transaction services included in this document: AUTH, SALE, CAPTURE, CREDIT, VOID.


Implementation Platforms

HPCI Web Service API can be used in any programming language that supports HTTPS calls. Examples include Java, PHP, and C #.Net.

Setting up API Calls

All API calls to HostedPCI are made over HTTPS to an HPCI hostname that will be provided to you during your account setup. Parameters are passed to HPCI through the standard HTTP POST method. Name-Value pairs are separated by & characters and are URL Encoded.

The following method in Java is designed to set up and call HPCI API URLs (see below). Programming languages such as PHP and C# .Net have similar methods for POSTing HTTP URLs. Source code for the Java example below is available in 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 All API Calls

apiVersion, value “1.0.1”

apiType, value “pxyhpci”

userName, value [API UserId]

userPassKey, value [API Passkey]


Specifying the Payment Profile Name (Optional)

With some advanced configurations, multiple payment gateways can be setup with HPCI and specified per API call. Payment profile names can be specified with the parameter below. This parameter is optional; the default value is DEF. Profile names must be pre-arranged with the HPCI team.

pxyTransaction.txnPayName, value [Name of Payment Profile to use]

Reading Results from API Calls



Once an HTTPS call is made to an HPCI Web Service API, results will be returned in standard Name-Value pair format with URL Encoded values.

The following method in Java is designed to read results from HPCI API calls and return result values in a 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

  • pxyCreditCard.cardType, optional value [Type of Credit Card Used]
  • pxyCreditCard.creditCardNumber, value [HPCI Token Representing Credit Card]
  • pxyCreditCard.expirationMonth, value [Credit Card Expiry Month]
  • pxyCreditCard.expirationYear, value [Credit Card Expiry Year]
  • pxyCreditCard.cardCodeVerification, value [HPCI Token Representing CVV Code]

Transaction Amount Related Parameters (Required)

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

User Related Parameters

  • pxyCustomerInfo.email, value [Customer Email Address]
  • pxyCustomerInfo.customerId, value [Customer User ID]

Billing Address Related Parameters

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

Shipping Address Related Parameters

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

Optional Parameters

The following parameters are not required but maybe useful to the payment gateway in use for fraud detection and other purposes.

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

Credit Card Capture Transaction (CAPTURE)

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

Additional Required Parameters:

Transaction Amount Related Parameters

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

Processor ID Parameters

  • pxyTransaction.processorRefId, value [Processor ID provided from Authorization or Sale]

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

API Response Variables

The API Response variables are the same as for the AUTH transaction. Please see above.

Credit Card Sale Transaction (SALE)

API Endpoint: http://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: http://HPCI_API_HOSTNAME/iSynSApp/paymentVoid.action

Additional Required Parameters:

Transaction Amount Related Parameters

  • pxyTransaction.txnAmount, value [Transaction Amount to Void]
  • pxyTransaction.txnCurISO, value “USD” or other ISO Currency Code
  • pxyTransaction.merchantRefId, value [Merchant Reference Number (order Id)]

Processor ID Parameters

  • pxyTransaction.processorRefId, value [Processor ID provided from Authorization or Sale]

The pxyTransaction.processorRefId is returned from an 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.

API Response Variables

The API Response variables are the same as for the AUTH transaction. Please see above.

Credit Card Credit Transaction (CREDIT)

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

Additional Required Parameters:

Transaction Amount Related Parameters

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

Processor ID Parameters

  • pxyTransaction.processorRefId, value [Processor ID provided from Authorization or Sale]

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

API Response Variables

The API Response variables are the same as for the AUTH transaction. Please see above.

Gateway Tokenization

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

Tokenization Related Parameters

The parameters listed below are required by the Gateway and HostedPCI in order to create a Gateway Token.

  • pxyCreditCard.creditCardNumber,value [HostedPCI Token]
  • pxyCreditCard.cardCodeVerification,value [HostedPCI CVV place holder]
  • pxyCreditCard.expirationMonth,value [Credit Card expire month]
  • pxyCreditCard.expirationYear,value [Credit Card expire year]
  • pxyTransaction.txnPayName,value [Profile Name provided by HostedPCI]
  • pxyCustomerInfo.billingLocation.firstName,value [Client’s first name as it appears on the card]
  • pxyCustomerInfo.billingLocation.lastName,value [Client’s last name as it appears on the card]

API Response Variables

This API call responds with the following name-value pairs.

  • Status, value [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, value [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, value [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 documentation for these operations below.

  • pxyResponse.processorType, value [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).

    • pxyResponse.responseStatus.name, value [short description of response]
    • pxyResponse.responseStatus.code, value [alphanumeric code representing response]
    • pxyResponse.responseStatus.description, value [long description and informational text of response]
    • pxyResponse.responseStatus.reasonCode, value [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.

    • pxyResponse.fullNativeResp, value [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 allow for passing fraud detection service parameters. The fraud detection service needs to be enabled prior to passing the fraud detection parameters.

    Fraud detection parameters are passed in an array, notated by [ ] array syntax. Repeat the following parameter pairs for each parameter that is required by the service.

    • fraudChkParamList[x]. name, value  [Parameter Name].
    • fraudChkParamList[x]. value, value  [Parameter Value].
    • fraudChkParamList[x]. type, optional value  [Parameter Type, either “data” or “map”].
    • fraudChkParamList[x]. mappedValue,optional value  [Parameter Mapped Value].
    • fraudChkParamList[x]. groupIdx,optional value  [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.

    • frdChkResp.fullNativeResp, value [full response of a call to fraud checking service]

    Kount Related Service Parameters (Optional)

    As part of our Kount integration, HostedPCI allows to pass mapped values for AVST, AVSZ, CVVR and UDF according to the Kount documentation.

    AVST, AVSZ, CVVR

    AVST, AVSZ and 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 than the possible code values for Kount (possible values are “M” or “N”), you need to create mapping for every call that will define the relationship between the gateway codes and the Kount codes.
    For example, if you’re 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 all those values to be passed to Kount as a match then you’re going to populate the following in your request to HostedPCI:

    • 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 Fields (UDF) which can be added to the request similarly to the way we did 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:

    • 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’s response dynamically to a UDF, please contact HostedPCI if you need that.

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

    The Authorization (and Sale) API’s also allow for passing payer authentication information. 3D Secure information is optional and will be required only of the 3D Secure service has been subscribed with the payment gateway.

    • pxyThreeDSecAuth.actionName, value empty string when no 3D Secure action is requested. Pass “verifyenroll” when card enrollment needs to be verified. Pass “verifyresp” when authentication response needs to be verified.
    • pxyThreeDSecAuth.authTxnId, value pass the authentication id received from “verifyenroll” call.
    • pxyThreeDSecAuth.paReq, value pass the payer authentication request value received from “verifyenroll” call.
    • pxyThreeDSecAuth.paRes, value pass the payer authentication response value received from pin verification call.
    • pxyThreeDSecAuth.authSignComboList[x], value  combined statuses of Authentication Result + Signature Result that are acceptable. The results are received after the verification call is completed by HPCI service prior to 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 Related Parameters (Optional)

    The Authorization (and Sale) API’s also allow 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 item in the order that is being processed.

    • pxyOrder.orderItems[x].itemId, value  [Merchant Item ID]
    • pxyOrder.orderItems[x].itemName, value  [Merchant Item Name]
    • pxyOrder.orderItems[x]. itemDescription, value [Merchant Item Description]
    • pxyOrder.orderItems[x]. itemQuantity, value  [item Quantity Ordered]
    • pxyOrder.orderItems[x]. itemPrice, value  [item Price per Unit]
    • pxyOrder.orderItems[x]. itemTaxable, value  [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:

    • pxyResponse.threeDSAcsUrl, value [ACS Url received from the “verifyenroll” call]
    • pxyResponse.threeDSTransactionId, value [Transaction Id received from the “verifyenroll” call]
    • pxyResponse.threeDSPARequest, value [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 Transaction steps (Auth/Sale)

    The following steps are required only if 3D Secure (Verified by Visa, MasterCard SecureCode etc) are enabled for chargeback protection.

    The e-commerce site needs to pass the following parameter during Auth or Sale calls to verify if a card is enrolled in 3D Secure program. If a PIN verification is required for the credit card used, during the call then a status of “3D Secure” is returned back:

    • pxyThreeDSecAuth.actionName, value, pass ”verifyenroll”.

    After receiving “3D Secure” response status the e-commerce site needs to present the PIN verification form. It is recommended that the PIN verification form be presented in an iframe from the HPCI domain and is described in the ExpressHTML Guide.

    The following parameters will be required for initiating a successful PIN verification call:

    • pxyResponse.threeDSTransactionId, the value received in this variable will contain a unique reference provided by the 3D Secure system. You can pass the value from the parent frame to the PIN verification iframe using a suitable url parameter.