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.

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].c1.hostedpci.com/iSynSApp/paymentFileDispatch.action

Key Parameters

apiVersion This parameter is required for making API calls to HPCI, and should be set to the value “1.0.1”
apiType This parameter is required for making API calls to HPCI, and this parameter should be set as “pxyhpci”
userName This information is provided by HPCI and is required in order to determine which vault is being used.
userPassKey This 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.profileName This 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.contentType This parameter provides details about the content type for the File Dispatch the request to the destination. Example: urlencode / xml / html / plain / json
dispatchRequest.request This 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.

Sample

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.

jQuery("#filedispatchBtn").click(function(){
          
          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());
          
          jQuery.ajax({
          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<String, String> 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.setDoOutput(true);
      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<String, String> 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);
            writer.append(CRLF);
            writer.append(paramEntry.getValue()).append(CRLF).flush();
          }
  
          // 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);
          writer.append(CRLF).flush();
          BufferedReader reader = null;
          try {
              reader = new BufferedReader(new InputStreamReader(new FileInputStream(dispatchFile), charset));
          		for (String line; (line = reader.readLine()) != null;) {
                  writer.append(line).append(CRLF);
              }
          } finally {
              if (reader != null) try { reader.close(); } catch (IOException logOrIgnore) {}
          }
          // End of multipart/form-data.
          writer.append("--" + boundary + "--").append(CRLF);
          writer.flush();
          
          // Get the response
          BufferedReader rd = new BufferedReader(new InputStreamReader(connection.getInputStream()));
          String line;
          while ((line = rd.readLine()) != null) {
          	urlReturnValue = urlReturnValue + line;
          }
          rd.close();

      } finally {
          if (writer != null) writer.close();
      }		
    
    } catch (Exception e) {
      e.printStackTrace();
      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<String, String> paramMap = new HashMap<String, String>();
    paramMap.put(PXYPARAM_APIVERSION, PXYPARAM_APIVERSION_NUM);
    paramMap.put(PXYPARAM_APITYPE, PXYPARAM_APITYPE_PXYHPCI);
    paramMap.put(PXYPARAM_USERNAME, userName);
    paramMap.put(PXYPARAM_USERPASSKEY, userPassKey);
    paramMap.put(PXYPARAM_DISPATCHREQUEST_PROFILENAME, "DISPATCHEXAVAULT");
    if(destFileName != null && !destFileName.isEmpty())
      paramMap.put(PXYPARAM_DISPATCHREQUEST_DESTFILENAME, destFileName);
      
      logMessage("========================================================");
    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<String, String> 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.

status The 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.responseStatus The 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.
authId is an enteral number provided by HostedPCI for your records only.
pxyResponse.processorType This parameter provides you with the type of response being provided, the value will always be fileDispatchResponse
pxyResponse.fileRowCount This 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.code This parameter provides you with an alphanumeric code that can assist with understanding the response being provided back as well as debugging.
pxyResponse.responseStatus.description This parameter will provide a brief description of the response being provided, which can assist with any errors that may occur.
pxyResponse.dispatchResp The dispatch response variable contains the scrubbed response from the dispatch endpoint, the value will be dispatch response.