Welcome to HostedPCI API documentation portal.  Two things to keep in mind when making requests with parameters.

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

Getting Started

All companies and organizations that deal with credit card information must adhere to PCI DSS. If your company takes credit card payments online, or through a call center, PCI DSS is a must.

PCI DSS Objectives and Requirements

Control ObjectivesRequirements
Build and maintain a secure network1. Install and maintain a firewall configuration to protect cardholder data
2. Do not use vendor-supplied defaults for system passwords and other security parameters
Protect cardholder data3. Protect stored cardholder data
4. Encrypt transmission of cardholder data across open, public networks
Maintain a vulnerability management program5. Use and regularly update anti-virus software
6. Develop and maintain secure systems and applications
Implement strong access control measures7. Restrict access to cardholder data by business need-to-know
8. Assign a unique ID to each person with computer access
9. Restrict physical access to cardholder data
Regularly monitor and test networks10. Track and monitor all access to network resources and cardholder data
11. Regularly test security systems and processes
Maintain an information security policy12. Maintain a policy that addresses information security for all personnel

These 6 objectives may sound straight forward at first, but when you dig deeper into the standard, the 12 section SAQ (Self Assessment Questionnaire) can become fairly complicated. There are over 200 questions to answer in the SAQ. Failing only one of them could put your PCI Compliance status at risk. Download the SAQ here to take a look.PCI Compliance doesn’t have to be so difficult. We created HostedPCI to make compliance a straight forward task. At the heart of all of the HostedPCI modules is the Payment Vault which includes our Tokenization technology. If you accept credit card data online, take a look at the Checkout Express Edition. For call and contact centers, HostedPCI offers the Call Center Edition **Getting Started

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.

Express Checkout solution is designed to integrate with any ecommerce site that requires credit card and CVV information capture. The express checkout solution uses an iframe module that is installed on the main ecommerce sites payment pages.

List the meaning of all the common error codes.


Watch the video to learn more about how HostedPCI can help you.

Code Samples

Code for common use cases in a variety of languages to help you get going on your project.

Advance Materials

Dispatch Web Services API can be accessed by any ecommerce system that needs to submit credit card transactions to a 3rd party web service with the use of the HPCI credit card token.

This guide provides implementation details to setup a telephonic call session and get the mapped credit card for the credit card entered via the telephone.

iFrame HTML Guide

Checkout Web Services API

Payment API Guide

  • A HostedPCI checkout Web Services API can be accessed by any eCommerce system that needs to process credit card transactions with the use of 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)


Provided by HPCI after the activation of the HPCI account.
API PasskeyProvided by HPCI after the activation of the HPCI account.
HPCI TokensHave 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 ‘’
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();
    OutputStreamWriter wr = new OutputStreamWriter(conn.getOutputStream());
    // Get the response
    BufferedReader rd = new BufferedReader(new InputStreamReader(conn.getInputStream()));
    String line;
    while ((line = rd.readLine()) != null) {
      urlReturnValue = urlReturnValue + line;
  } catch (Exception e) {
    urlReturnValue = "";
  return urlReturnValue;
 } //END: callUrl

Required Parameters for Setting up API Calls:

apiVersion[ 1.0.1]
userName[API UserId]
userPassKey[API Passkey]

Optional Parameters for specifying the payment profile name:

pxyTransaction.txnPayName[Name of Payment pfoile to use]

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

Reading Results from API Calls

  • Result are 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:
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:
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]
User Related Parameters:
ParametersValues[Customer Email Address]
pxyCustomerInfo.customerId[Customer User ID]
Billing Address Related Parameters:
pxyCustomerInfo.billingLocation.firstName [Customer First Name]
pxyCustomerInfo.billingLocation.lastName [Customer Last Name]
pxyCustomerInfo.billingLocation.address[Customer Billing Street Address] [Customer Billing City]
pxyCustomerInfo.billingLocation.state [Customer Billing State]
pxyCustomerInfo.billingLocation.zipCode [Customer Billing Zipcode] [Customer Billing Country]
pxyCustomerInfo.billingLocation.phoneNumber[Customers Billing Phone Number]
Shipping Address Related Parameters:
pxyCustomerInfo.shippingLocation.firstName [Customer First Name for Shipping]
pxyCustomerInfo.shippingLocation.lastName [Customer Last Name for Shipping]
pxyCustomerInfo.shippingLocation.address[Customer Shipping Street Address] [Customer Shipping City]
pxyCustomerInfo.shippingLocation.state [Customer Shipping State]
pxyCustomerInfo.shippingLocation.zipCode [Customer Shipping Zipcode] [Customer Shipping Country]
pxyCustomerInfo.shippingLocation.phoneNumber[Customers Shipping Phone Number]
Other Optional Parameters:
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=&
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=& 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=

Credit Card Capture Transaction (CAPTURE)

API End point: HPCI_API_HOSTNAME/iSynSApp/paymentCapture.action
Additional Required Parameters:
Transaction Amount Related Parameters:
pxyTransaction.txnAmount[Transaction Amount to Capture]
pxyTransaction.txnCurISO[ “USD” or other ISO Currency Code]
pxyTransaction.merchantRefId[Merchant Reference Number (order Id)]
Processor ID Parameters:
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:
CAPTURE Response example:


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
pxyTransaction.txnAmount[Transaction Amount to VOID]
pxyTransaction.txnCurISO[“USD” or other ISO Currency Code]
pxyTransaction.merchantRefId[Merchant Reference Number (order Id)]
Processor ID Parameters:
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:
VOID Response example:

Credit Card Credit Transaction (CREDIT)

API End point URL: HPCI_API_HOSTNAME/iSynSApp/paymentCredit.action
Additional Required Parameters:
Transaction Amount Related Parameters:
pxyTransaction.txnAmount [Transaction Amount to Credit]
pxyTransaction.txnCurISO[ “USD” or other ISO Currency Code]
pxyTransaction.merchantRefId[Merchant Reference Number (order Id)]
Processor ID Parameters:
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:
CREDIT Response example:

Gateway Tokenization

API endpoint: HPCI_API_HOSTNAME/iSynSApp/paymentGatewayToken.action
Tokenization Related Parameters:
pxyCreditCard.creditCardNumber,value [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]

API Response Variables

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

NameValueAdditional 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.
[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 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).

NameValue[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.

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’ prior to 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.
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.

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 to pass mapped values for AVST, AVSZ, CVVR, UDF according to the Kount documentation.


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 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.


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


Kount also allows for User Defined Field (UDF) which can be added to the request similarly 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.


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

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

  • The Authorization (and Sale) API’s 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.
[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.]
[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]
[The 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 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.
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. Ue the following parameters to initiate the PIN verification call:
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 Transaction steps (Auth / Sale)

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

The e-commerce site needs to pass the following parameters 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:


After receiving “3D Secure” response status the e-commerce site needs to presend 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.]