File Dispatch Web Services API Guide

The hostedPCI File Dispatch Web Services API can be accessed by any ecommerce or call centre system that need to submit files of credit card transactions to a 3rd party web service or processors with the use of the HPCI credit card token. Tokens can be obtained through the implementation of the HPCI Iframe solution or the HPCI IVR solution. This document assumes that HPCI tokens have been generated and available for use with the HPCI File Dispatch Web Service API.

We have implemented services with Chase Account Updater and Auric System..

Implementation Platforms

HPCI Dispatch 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 account setup. Parameters are passed to HCPI through standard the HTTPS POST method. Name-Value pairs are separated by & characters and are URL Encoded.

File Dispatch API Action URL

“https://api-[venue name]

apiVersionThis parameter is required for making API calls to HPCI, and should be set to the value “1.0.1”
apiTypeThis parameter is required for making API calls to HPCI, and this parameter should be set as “pxyhpci”
userNameThis information is provided by HPCI and is required in order to determine which vault is being used.
userPassKeyThis information is provided by HPCI and is required to confirm the vault that is being used.

Specifying the File Dispatch Profile Name

HostedPCI allows for multiple endpoints to be configured using our solution, and are specified using the profile name. The parameter listed below is required for all File Dispatch API calls made to HostedPCI.

dispatchRequest.profileNamehis parameter is required for making API calls regardless of the number of profiles, and the “profile name ” must be pre-arranged with the HostedPCI team.

Additional Required Parameters

When using the File Dispatch API it is important to ensure that all required parameters are being used, if a required parameter is missing the API action will result in an error.

File Dispatch Related Parameters

dispatchRequest.contentTypeThis parameter provides details about the content type for the File Dispatch the request to the destination. Example: urlencode / xml / html / plain / json
dispatchRequest.requestThis parameter is the fully prepared message for delivery to destination with place holders for Credit Card and CVV tokens

Preparing and Sending Files to HostedPCI

Sample File

The layout and contents of a file will be decided between the customer and the 3rd party processor. HostedPCI only cares about the token field for mapping. Below is a basic example of a possible file. The type of file being sent also does not matter to HostedPCI as long as we know where to grab the token and place the credit card.


Card Number, Expiry, Amount
4242000000104242, 05/16, 45.45
4111000000301111, 09/17, 65.23
4444000000051111, 10/18, 56.79

Front End Processing

Once the file is prepared it must be uploaded to the companies server in order to be sent to HostedPCI.

          var file = jQuery("#filedispatch_file").val();
          var blob = new Blob([file], { type: "text/plain"});
          var formData = new FormData();
          formData.append("tokenFile", blob, "data.csv");
          formData.append("dispatchRequest.destFileName", "data.csv");
          formData.append("dispatchRequest.profileName" , jQuery("#paymentProfile_filedispatch").val());
          url: "FileDispatchServlet",
          type: "POST",
          data: formData,
          processData: false,  // tell jQuery not to process the data
          contentType: false   // tell jQuery not to set contentType
        }).done(function(data) {
          //Process the ajax call result..

Server to Server Call

private static final String PXY_MSGDISPATCH = "/iSynSApp/paymentFileDispatch.action";
private static final String PXYPARAM_APIVERSION = "apiVersion";
private static final String PXYPARAM_APIVERSION_NUM = "1.0.1”;
private static final String PXYPARAM_APITYPE = "apiType";
private static final String PXYPARAM_APITYPE_PXYHPCI = "pxyhpci";
private static final String PXYPARAM_DISPATCHREQUEST_PROFILENAME = "dispatchRequest.profileName";
private static final String PXYPARAM_DISPATCHREQUEST_DESTFILENAME = "dispatchRequest.destFileName";
private static final String PXYPARAM_USERNAME = "userName";
private static final String PXYPARAM_USERPASSKEY = "userPassKey";
public static String callUrl(String urlString, Map paramMap, String fileName,
      File dispatchFile) {
    String urlReturnValue = "";
    String charset = "UTF-8";
    String boundary = Long.toHexString(System.currentTimeMillis()); // Just generate some unique random value.
    String CRLF = "\r\n"; // Line separator required by multipart/form-data.
    try {
      URLConnection connection = new URL(urlString).openConnection();
      connection.setRequestProperty("Content-Type", "multipart/form-data; boundary=" + boundary);
      PrintWriter writer = null;
      try {
          OutputStream output = connection.getOutputStream();
          writer = new PrintWriter(new OutputStreamWriter(output, charset), true);
          // Send normal param.
          for (Entry paramEntry : paramMap.entrySet()) {
            writer.append("--" + boundary).append(CRLF);
            writer.append("Content-Disposition: form-data; name=\"" + paramEntry.getKey() + "\"").append(CRLF);
            writer.append("Content-Type: text/plain; charset=" + charset).append(CRLF);
          // Send text file.
          writer.append("--" + boundary).append(CRLF);
          writer.append("Content-Disposition: form-data; name=\"tokenFile\"; filename=\"" + fileName +"\"").append(CRLF);
          writer.append("Content-Type: text/plain; charset=" + charset).append(CRLF);
          BufferedReader reader = null;
          try {
              reader = new BufferedReader(new InputStreamReader(new FileInputStream(dispatchFile), charset));
              for (String line; (line = reader.readLine()) != null;) {
          } finally {
              if (reader != null) try { reader.close(); } catch (IOException logOrIgnore) {}
          // End of multipart/form-data.
          writer.append("--" + boundary + "--").append(CRLF);
          // Get the response
          BufferedReader rd = new BufferedReader(new InputStreamReader(connection.getInputStream()));
          String line;
          while ((line = rd.readLine()) != null) {
            urlReturnValue = urlReturnValue + line;
      } finally {
          if (writer != null) writer.close();
    } catch (Exception e) {
      urlReturnValue = "";
    return urlReturnValue;
  private String dispatchOnly(String serviceUrl, String userName, String userPassKey, String fileName,
      String destFileName, File dispatchFile) {
    // make the remote call
    String callUrl = serviceUrl + PXY_MSGDISPATCH;
      // prepare the api call
    Map paramMap = new HashMap();
    paramMap.put(PXYPARAM_USERNAME, userName);
    paramMap.put(PXYPARAM_USERPASSKEY, userPassKey);
    if(destFileName != null && !destFileName.isEmpty())
    logMessage("Make the call: " + callUrl);
    logMessage("Call payload: " + paramMap);
    String callResult = callUrl(callUrl, paramMap, fileName, dispatchFile);
    logMessage("Call result:" + callResult);
    // parse the url encoded key value pairs
    Map resultMap = DemoUtil.parseQueryString(callResult);
    // get the network call status
    String callStatus = resultMap.get(PXYRESP_CALL_STATUS);
    if (callStatus != null && callStatus.equals(PXYRESP_CALL_STATUS_SUCCESS)){ 
      logMessage("Successful transaction");
      authId = resultMap.get(PXYRESP_AUTH_ID);
      logMessage("Auth Ref Id:" + authId);
    else {
      logMessage("Unsuccessful transaction");
      String statusCode = resultMap.get(PXYRESP_RESPSTATUS_CODE);
      String statusName = resultMap.get(PXYRESP_RESPSTATUS_NAME);
      String statusDesc = resultMap.get(PXYRESP_RESPSTATUS_DESCRIPTION);
      logMessage("Auth Status Code:" + statusCode);
      logMessage("Auth Status Name:" + statusName);
      logMessage("Auth Status Desc:" + statusDesc);
    return callResult;

API Response Variables

This API call responds with the following name-value pairs. The response being provided back is only of the upload success or failure there will be no status of the credit card processing.

statusThe Status response variable indicates if the API call is well formed, with an appropriate result. It does not guarantee a successful credit card transaction with a complete authorization or capture if the status is returned as success. Other parameters must be checked, see below. The value will either be success or failure.
pxyResponse.responseStatusThe transaction response considered successful for pxyResponse.responseStatus is the approved or dispatched status. Any other response should be considered an error. In case of an error transaction, the error code may be obtained as per the following response variables below. The possible values are either approved, declined, error, review and dispatched.
authIdis an enteral number provided by HostedPCI for your records only.
pxyResponse.processorTypeThis parameter provides you with the type of response being provided, the value will always be fileDispatchResponse
pxyResponse.fileRowCountThis parameter provides you with an update on how many columns have been provided within the file. This will indicated how many tokens were provided to HostedPCI.
pxyResponse.responseStatus.codeThis parameter provides you with an alphanumeric code that can assist with understanding the response being provided back as well as debugging.
pxyResponse.responseStatus.descriptionThis parameter will provide a brief description of the response being provided, which can assist with any errors that may occur.
pxyResponse.dispatchRespThe dispatch response variable contains the scrubbed response from the dispatch endpoint, the value will be dispatch response.

Chase Account Updater

Hosted PCI has integrated with Chase Account Updater. With this Integration our clients will be able to update the cards in their vault and continue to use it to process even if the card numbers, expiry date or other details has been updated.

Chase Account Updater API URL

https://api-[venue name]

Step 1 – Chase Account Updater  Dispatch Call

The first step of the Chase Account Updater Process. The step is making a dispatch call with the file in a specific format. Please take a look at a sample request Dispatch file.

sample of Dispatch File

Please make sure each line length is 121 (put empty space at the end)

Chase Acnt Upt Dispatch File

Dispatch call API Request sample:
apiType=pxyhpci&apiVersion=1.0.1&dispatchRequest.destFileName=PID.FILENAME.format&dispatchRequest.profileName=HPCI profileName&dispatchRequest.reqUserName=AccountUpdUsername&dispatchRequest.reqUserPwd=AccountUptPassword&dispatchRequest.requestMode=dispatch&userName=HPCIUsername&userPassKey=HPCIPasskey
dispatchRequest.destFileName The name of the Dispatch file. As per Chase the name should be: PID.fileID.extension
dispatchRequest.profileName Name of the Chase Account Updater Profile in the Merchant’s Venue.
dispatchRequest.reqUserName Chase Account Updater Dispatch Username.
dispatchRequest.reqUserPwd Chase Account Updater Dispatch Password.
dispatchRequest.requestMode dispatch | listfiles | fetch

Step 2 – Chase Account Updater List Files Call

This is the second step of the Chase Account Updater Process. This step should occur 10 minutes after the dispatch was completed. This call will return the list of the files in the Client’s Chase Account Updater portal. In the response there will be a file with _resp in the file name which will contain detail about the earlier dispatch file.

i.e. PID.fileID_RANDOMNUMS_resp.pgp (DispatchFileName_RandomNums_resp.pgp)

ListFiles call API Request sample:

Step 3 – Chase Account Updater Fetch Call

This is the third step of the Chase Account Updater Process. This process will make a fetch call to the file which name was returned in the list files call (Step 2).

fetch file name: PID.fileID_RANDOMNUMS_resp.pgp

Fetch call API Request sample:
sample of the fetch file (dispatch status)

This is the response file which contains information on the status of the dispatch call.

Chase Acnt Upt Fetch File

This file is same as the Dispatch file with extra details added to the record lines.

Step 4 – Chase Account Updater List Files Call

This is the Fourth step of the Chase Account Updater Process. This step should be done everyday if there are records expected to be returned. This call will return the files in the Client’s Chase Account Updater portal. Please look out for files with the todays date and card brand.

i.e. PID.MID.221220.VAU_resp.txt

The response file name breakdown

PID = Client’s Chase Account Updater PID

MID = Client’s Chase Account Updater Merchant ID

221220 = Today’s date (YYMMDD)

VAU_resp / MAU_resp = VISA Account Update file / MasterCard Account Update response file

txt = file format

ListFiles call API Request sample:

Step 5 – Chase Account Updater Fetch Call

This is the Fifth step of the Chase Account Updater Process. This process will make a fetch call to the file which name was returned in the previous list files call (Step 4).

fetch file name: PID.MID.221220.VAU_resp.txt

Fetch call API Request sample:

Auric System

Dispatch Call

Dispatch call with Auric is the same process as the regular HPCI File Dispatch request. Please see the documentation HERE.

Fetch Call

In order to make fetch call with Auric Please call this Endpoint.

https://api-[venue name]

Sample Auric Fetch call: