Document Uploads via the ProPay API

There are several reasons you may need to upload documents to ProPay, and provide them to ProPay's Risk team: 
  • Documents requested by ProPay’s Risk team to enable an account previously declined, or as part of a pre-arranged process whereby ProPay agrees to higher-than-normal processing limits for your customers' accounts so long as you provide documentation to help us underwrite them.  (Typically, if you do NOT provide these documents, and it is expected of you, accounts will be shut down very quickly.)
  • Documents requested by ProPay’s Risk team to extend higher processing limits to an existing account.
Document upload service allowed file formats
  • tif, tiff
  • bmp
  • jpg, jpeg
  • gif
  • png
  • doc, docx
Files can be no larger than 5mb, but quality is not a significant concern so files will usually be much smaller.

Chargebacks
ProPay provides a similar, but slightly enhanced document upload API method that can be used to provide documents for the dispute of credit card chargebacks.  Click  here  to learn more.
How to call this method?

Example Request

Example Response

Implementation Details
Request Submission

Response Handling

Request Submission

Response Handling

Request Submission

Response Handling

Request Submission

Response Handling

Request Values
Response Values
How to call this method?

You should submit a post of XML data to the following URL
 
HTTP URL(s)
Example Request

Example Response

<?xml version='1.0'?>
<!DOCTYPE Request.dtd>
<XMLRequest>
<certStr>MyCertStr</certStr>
<class>partner</class>
<XMLTrans>
<transType>47</transType>
<accountNum>123456</accountNum>
<DocumentName>Chargeback 456</DocumentName>
<DocType>doc</DocType>
<Document>08R4kGuEAAAAAAAAAAAAAAAAAAAAA/CQ…</Document>
<DocCategory>Underwriting</DocCategory>
</XMLTrans>
</XMLRequest>
<XMLResponse>
<XMLTrans>
<transType>47</transType>
<status>00</status>
</XMLTrans>
</XMLResponse>
Implementation Details
Request Submission

namespace MSAPI_ProcessTransaction
 {
 using System;
 using System.Collections.Generic;
 using System.IO;
 using System.Linq;
 using System.Net;
 using System.Text;
 using System.Xml;
 using System.Xml.Linq;
 using System.Xml.Serialization;

/*
 ProPay provides the following code “AS IS.”
ProPay makes no warranties and ProPay disclaims all warranties and conditions, express, implied or statutory,
 including without limitation the implied warranties of title, non-infringement, merchantability, and fitness for a particular purpose.
 ProPay does not warrant that the code will be uninterrupted or error free,
 nor does ProPay make any warranty as to the performance or any results that may be obtained by use of the code.
 */
 public class ProcessTransactionTransType47
 {
 public static void ProcessTransaction()
 {
 var processRequest = new XmlTransactionRequest { CertificationString = "YourCertStringGoesHere", TerminalID = "YourTermId", };
 var xmlTransaction = new XmlProcessTransaction
 {
 TransType = "47",
 accountNum = "12345678",
 DcumentName = "chargeback 456",
 DocType = "jpg",
 Document = "asdfasdfasdfasdfasdfasdfasdfasdfasdfasdfasdfasdfasdf...",
 DocCategory = "Underwriting",
 };
 processRequest.Transactions.Add(xmlTransaction);
 string request = XmlSerializer<XmlTransactionRequest>.WriteToString(processRequest);
 SubmitRequest(request);
 }

private static void SubmitRequest(string request)
 {
 byte[] dataToSend = Encoding.UTF8.GetBytes(request);

// Change the following URL to point to production instead of integration
 WebRequest webRequest = WebRequest.Create("https://xmltest.propay.com/API/PropayAPI.aspx");
 webRequest.Method = "POST";
 webRequest.ContentLength = dataToSend.Length;
 webRequest.ContentType = "text/xml";
 Stream dataStream = webRequest.GetRequestStream();
 dataStream.Write(dataToSend, 0, dataToSend.Length);
 dataStream.Close();

string response = string.Empty;

try
 {
 WebResponse apiResponse = webRequest.GetResponse();


using (StreamReader sr = new StreamReader(apiResponse.GetResponseStream()))
 {
 response += sr.ReadToEnd();
 }
 }
 catch (WebException wex)
 {
 HttpWebResponse httpResponse = wex.Response as HttpWebResponse;
 using (Stream responseStream = httpResponse.GetResponseStream())
 using (StreamReader reader = new StreamReader(responseStream))
 {
 response = reader.ReadToEnd();
 }
 }

 ParseResponse(response);
 }

private static void ParseResponse(string response)
 {
 var load = XDocument.Parse(response);
 var transType = Convert.ToInt32(load.Descendants().First(p => p.Name.LocalName == "transType").Value);
 var status = load.Descendants().First(p => p.Name.LocalName == "status").Value;
 }
 }

public class XmlProcessTransaction : XmlTransaction
 {
 [XmlElement("accountNum")]
 public string accountNum = string.Empty;
 [XmlElement("DocumentName")]
 public string DocumentName = string.Empty;
 [XmlElement("DocCategory")]
 public string DocCategory = string.Empty;
 [XmlElement("DocType")]
 public string DocType = string.Empty;
 [XmlElement("Document")]
 public string Document = string.Empty;
 }

public static class XmlSerializer<T>
 {
 public static XmlSerializer Serializer = new XmlSerializer(typeof(T));
 public static string WriteToString(T data)
 {
 return WriteToString(data, Encoding.UTF8);
 }
 public static string WriteToString(T data, Encoding encoding)
 {
 string retVal;
 using (MemoryStream memoryStream = new MemoryStream())
 {
 using (XmlTextWriter xmlTextWriter = new XmlTextWriter(memoryStream, encoding))
 {
 Serializer.Serialize(xmlTextWriter, data);
 }

retVal = encoding.GetString(memoryStream.ToArray());
 }

return retVal;
 }
 }

[XmlInclude(typeof(XmlProcessTransaction))]
 public class XmlTransaction
 {
 [XmlElement("transType")]
 public string TransType = string.Empty;
 }
 [XmlRoot("XMLRequest")]
 public class XmlTransactionRequest
 {
 [XmlElement("certStr")]
 public string CertificationString = string.Empty;
 [XmlElement("termid")]
 public string TerminalID = string.Empty;
 [XmlElement("XMLTrans")]
 public List<XmlTransaction> Transactions = new List<XmlTransaction>();
 }
 }

Response Handling

Request Submission

/**
 * ProPay provides the following code “AS IS.” ProPay makes no warranties and
 * ProPay disclaims all warranties and conditions, express, implied or
 * statutory, including without limitation the implied warranties of title,
 * non-infringement, merchantability, and fitness for a particular purpose.
 * ProPay does not warrant that the code will be uninterrupted or error free,
 * nor does ProPay make any warranty as to the performance or any results that
 * may be obtained by use of the code.
 */


<?php
class ProPayApi
{
/* change this to the production url for going live after testing https://api.propay.com */
private $_apiBaseUrl = 'https://xmltestapi.propay.com';

/* for xml */
/** @var \SimpleXMLElement */
private $_xmlRequestObject;
/** @var \SimpleXMLElement */
private $_xmlResponseObject;
/** @var string */
private $_xmlUrl;

/**
* sets the xml request object
* @param string $xmlData - containing XML
* @return $this
*/
public function setXMLRequestData($xmlData) {
$this->_xmlRequestObject = simplexml_load_string($xmlData);
return $this;
}

/**
* @param string $xmlData - containing XML
* @return $this
*/
public function setXMLResponseData($xmlData) {
$this->_xmlResponseObject = simplexml_load_string($xmlData);
return $this;
}

/**
* @return mixed
*/
public function getXMLRequestObject() {
return $this->_xmlRequestObject;
}

/**
* @return mixed
*/
public function getXMLResponseObject() {
return $this->_xmlResponseObject;
}

/**
* @param \SimpleXMLElement $xmlObject
* @return $this
*/
public function setXMLRequestObject(\SimpleXMLElement $xmlObject) {
$this->_xmlRequestObject = $xmlObject;
return $this;
}

/**
* @param \SimpleXMLElement $xmlObject
* @return $this
*/
public function setXMLResponseObject(\SimpleXMLElement $xmlObject) {
$this->_xmlResponseObject = $xmlObject;
return $this;
}

/**
* sets the url for the XML request
* @param string $xmlUrl
* @return $this
*/
public function setXMLUrl($xmlUrl) {
$this->_xmlUrl = $xmlUrl;
return $this;
}

/**
* posts XML to the server
* @return $this
*/
public function postXML() {
$header = [
"Content-type:text/xml; charset=\"utf-8\"",
"Accept: text/xml"
];


$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => $this->_xmlUrl,
CURLOPT_TIMEOUT => 30,
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => $this->_xmlRequestObject->asXML(),
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => $header,
CURLOPT_SSL_VERIFYPEER => 0,
CURLOPT_SSL_VERIFYHOST => 0,
CURLOPT_HTTPAUTH => CURLAUTH_ANY
]);
$result = curl_exec($curl);
$this->_xmlResponseObject = simplexml_load_string($result);
curl_close($curl);
return $this;
}
}

$proPayAPI = new ProPayApi();
$data = "<?xml version='1.0'?>
<!DOCTYPE Request.dtd>
<XMLRequest>
</XMLRequest>";
$simpleXML = new \SimpleXMLElement($data);
$simpleXML->addChild('certStr','cert string here');
$simpleXML->addChild('termId','terminal id here');
$simpleXML->addChild('class','partner');
$simpleXML->addChild('XMLTrans');
$simpleXML->XMLTrans->addChild('transType', 47);
$simpleXML->XMLTrans->addChild('accountNum', 123456789);
$simpleXML->XMLTrans->addChild('DocumentName', 'Chargeback 456');
$simpleXML->XMLTrans->addChild('DocType', 'Doc');
$simpleXML->XMLTrans->addChild('Document', '08R4kGuEAAAAAAAAAAAAAAAAAAAAA/CQ...');
$simpleXML->XMLTrans->addChild('DocCategory', 'Underwriting');

// returns XML
$result =
$proPayAPI->setXMLUrl('https://xmltest.propay.com/API/PropayAPI.aspx')
->setXMLRequestData($simpleXML->asXML())
->postXML()
->getXMLResponseObject()->asXML();

// if you prefer a simpleXML object you just retrieve the object back to work with that
$result = $proPayAPI->getXMLResponseObject();

Response Handling

Request Submission

Response Handling

Request Submission

Response Handling

Request Values

Element

Type

Max

Required

Notes

accountNum

Int(32)

 

Required

Assigned to each account by ProPay

documentName

String

100

Required

Name the document according to instructions provided to you by ProPay’s Risk team.

DocCategory

String

40

Required

The type of document you've been asked to provide to Propay's Risk team.  Valid values are: Verification, FraudHolds, Underwriting, RetrievalRequest.

docType

String

4

Required

File format. Valid types: tif, tiff, bmp, jpg, jpeg, gif, png, doc, docx, pdf

Document

String

(5mb)

Required

The document data in base64 format.

 

Response Values

Element

Type

Notes

status

string

Result of the transaction request. See Propay Appendix for result code definitions

How to call this method?

Example Request

Example Response

Implementation Details
Request Submission

Response Handling

Request Submission

Response Handling

Request Submission

Response Handling

Request Submission

Response Handling

Request Values
Response Values