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)


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 ‘’
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:

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:
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 [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:
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]

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 API Call:





API Response Variables

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

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

ParameterValue[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’ 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.
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 us 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 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.


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


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.


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

pxyTransaction.cardOnFileOrigAmt[Original Amount]

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.
[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.]
[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 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.
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:
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.

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.

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”]