Single-Sign-On to Include ProPay Widgets on your Website

The ProPay website can be "white-labeled" so that it looks and feels much like your own. It is also possible to use "Single-Sign-On" so that users already logged in to your portal, can be taken directly to a page on ProPay’s without having to log in. While you can certainly redirect a user to a specific ProPay page, it is typically more effective to place the ProPay interface in an iframe. Our pages don’t redirect users back to your own site, and when you use "Single-Sign-On" all our pages lack a navigation menu. You are given the ability to control that portion of the experience. (Click here to view a manual on the  SSO Pages .)

Just about every page on the ProPay website can be white-labeled, and benefits from Single-Sign-On. Here are the parts that likely provide you, a payment facilitator, with the most benefit.
  • Update account settings, and the on-file direct deposit bank account.
  • Transfer money from the ProPay merchant account to his or her bank.
  • Use Flash Funds to instantly transfer funds from the ProPay merchant account to a debit card.
  • Provide typical "bank statement" reports to your merchants. (You don’t need to build your own reporting.)
  • Create a "chargeback portal" where merchants can upload documents to ProPay.
The chargeback portal deserves a bit more explanation.
While Single-Sign-On to ProPay’s chargeback document upload page is a great way for your merchants to represent a chargeback, the first step is, of course, to make them aware of a need to do so.
  • ProPay can notify merchants directly. (If you want to stay out of the business of dealing with chargebacks.)
  • ProPay can send you a daily chargeback file. Using the information contained in that file will allow you to notify the merchant, and provide him or her with a link to the ProPay document upload page.
  • You can receive a web-hook from ProPay, notify the merchant, and provide him or her with a link to the ProPay page.
How does Single-Sign-On work?
Embedding a ProPay widget into your website using Single-Sign-On, requires two steps:
1. Use the ProPay API to obtain a working key.
  • A working key is created specifically for a single ProPay account, and sign-on only works to the account number contained in your API request.
  • You must also pass an IP address, or range of IP addresses. Sign-on must originate from the specified location.
  • This API request requires client-side x509 certificate authentication.
2. Pass the working key into the website URL as the authToken parameter in the following example: https://propay.merchant-portals.com/[SupportedPage]?authToken=3b9f65d1-d4ea-4af8-ch28-7513091923a1&accountnum=31234567  (The test version of this site is found at https://il01merchantportals.propay.com )

Currently supported pages for single-sign-on

Manage Account Funding

  1. Account/AddUpdateCheckingAccount
    • This page allows account holders to change the bank account on file, (this is the default account for bank transfers, fees, etc.).
  2. Account/ConfirmValidationDeposits
    • This page is used to confirm validation for added or changed bank accounts.
  3. Account/SendValidationDeposits
    • This page initiates account validation deposits.
  4. Account/AddUpdateFlashFundAccount 
    • This page allows the user to add or update bank account information for Flash Funds, or Visa Direct deposits.
  5. ManageFunds/TransferFundsToDebitCard
    • This page allows account holders to send Flash Funds to a Visa or MasterCard debit card account (account must first have a Flash Funds account added).
  6. ManageFunds/TransferFundsToBankAccount
    • This page allows account holders to transfer funds to a bank account (ACH).
  7. ManageFunds/TransferFundsToanotherpropayaccount
    • This page allows merchants to transfer funds to a different ProPay account (both accounts must use the same currency).
  8. ManageFunds/AddFundsToPropayAccount
    • This page allows merchants to add funds to their ProPay account.
  9. ManageFunds/ScheduledTransfers
    • ​​This page allows merchants to schedule transfers out of their account (Flash Funds/Visa Direct and ACH).

Account Maintenance

  1. Profile/EditBusinessInfo
    • ​This page lets merchants edit their essential business information (name, location, etc.). 
  2. Profile/UpdateAddressAndPhone
    • ​This page allows account holders to update or change the account owner's personal contact information.
  3. Profile/UpdateEmail
    • This page allows account holders to update or change the account owner's email address.
  4. ​PaymentMethod/editpaymentmethod
    • This page allows merchants to change the credit card used to pay account renewal fees. 
  5. Profile/UpdatePin
    • This allows account holders to update the PIN on the account.

Manage Attached Debit Card (ProPay MasterCard)

  1. PropayCard/Index
  2. ProPayCard/RequestCard
    • This page allows merchants to request a new ProPay MasterCard for their account. 
  3. ProPayCard/ActivateCard
    • This allows merchants to activate a ProPay MasterCard for their account
  4. PropayCard/LostOrStolenCard
    • This allows merchants to report their ProPay MasterCard as stolen or lost.
  5. ProPayCard/UpdatePin
    • This allows merchants to update the PIN for their ProPay MasterCard. 
  6. ProPayCard/ReissueCard
    • This allows Merchants to order a new ProPay MasterCard for their account. 

Documents and Chargebacks

  1. Document/UploadDocument 
    • This page is used for securely transferring important documents for the merchant to ProPay. (This is mainly used for disputing chargebacks.)
  2. Risk/ListChargeBacks
    • This page lists all the retrieval requests and chargebacks for the merchant's account.

Provide Merchant Reporting (Informational Pages)

  1. Report/AdvancedTransactionSearch
    • This page provides searching for a specific transaction and uses it to generate a report
  2. Report/ConsolidatedFees
    • This page shows a report for all the fees for a given date range.
  3. Report/LimitsRatesAndFees
    • This page displays the account limits, rates, and fees associated with the account. 
  4. Report/TaxInformation
    • This page shows the account summary for the stated financial year. (This report isn't generated until the financial year has ended.) 
  5. Report/TransactionDetails **
    • This page allows merchants to generate a report showing key details for  searched / selected transactions. 
  6. Report/TransactionReport
    • This page allows account holders to view the transactions on their account - both pending and completed.
  7. Report/SweepReport
    • This page shows account holders the different sweeps performed on their account, according to date range.

 Point of Sale Devices

  1. Device/OrderAdditionalDevices
    • This page allows account holders to order devices. This may be initial ordering or may be additional devices for their account.
**Note: The TransactionDetails page presents the user with information specific to a single transaction.  It is necessary, as a result, to pass an additional parameter (the transNum) into the redirect URL.  Simply pass this number as an additional parameter into the URL before continuing with the rest of the name-value pairs. In addition, you can add reportid=1& to add a button that will redirect to the full transaction report. Ex. Report/TransactionDetails/2?reportId=1&authtoken=1236547897e-db5c-49e0-1234-290a2eff760c&accountnum=31234567
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>My certStr</certStr>
<termid>Term Id</termid>
<class>partner</class>
<XMLTrans>
<transType>300</transType>
<accountNum>1111111</accountNum>
<ReferrerUrl>www.myURL.com</ReferrerUrl>
<IpAddress>206.192.156.0</IpAddress>
<IpSubnetMask>255.255.255.0</IpSubnetMask>
</XMLTrans>
</XMLRequest>
<XMLResponse>
<XMLTrans>
<transType>300</transType>
<AuthToken>7f792d71-573e-4168-bdce-a1fc137596e5</AuthToken>
<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 ProcessTransactionTransType300
  {
  public static void ProcessTransaction()
  {
  var processRequest = new XmlTransactionRequest { CertificationString = "YourCertStringGoesHere", TerminalID = "YourTermId", };
  var xmlTransaction = new XmlProcessTransaction
  {
  TransType = "300",
  accountNum = "12345678",
  ReferrerUrl = "www.myurl.com",
  IpAddress = "206.192.156.0",
  IpSubnetMask = "255.255.255.0",
  };
  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";
  webRequest.Headers.Add("X509Certificate", GetBase64Cert(“your certificate thumbprint goes here”));
  webRequest.ProtocolVersion = HttpVersion.Version10;
  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;
  var AuthToken = load.Descendants().First(p => p.Name.LocalName == "AuthToken").Value;
  }
  }

public class XmlProcessTransaction : XmlTransaction
  {
  [XmlElement("accountNum")]
  public string accountNum = string.Empty;
  [XmlElement("ReferrerUrl")]
  public string ReferrerUrl = string.Empty;
  [XmlElement("IpAddress")]
  public string IpAddress = string.Empty;
  [XmlElement("IpSubnetMask")]
  public string IpSubnetMask = 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>();
  }

public string GetBase64Cert(string certificateThumbprint)
 {
 using (X509Store store = new X509Store(StoreName.My, StoreLocation.LocalMachine))
 {
 store.Open(OpenFlags.ReadOnly);
 var foundCertificates = store.Certificates.Find(X509FindType.FindByThumbprint, certificateThumbprint, false);
 if (foundCertificates.Count != 1)
 {
 return null;
 }
 var certByteArray = foundCertificates[0].Export(X509ContentType.Cert);
 store.Close();
 return Convert.ToBase64String(certByteArray);
 }
}

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;
}

/**
* creates custom header value by pulling array from x509 certificate file and converting to base64
* @param string $x509file
* @return $this
*/
public function setx509($x509file) {
$cert = openssl_x509_parse($x509file);
$base64cert = base64_encode($cert);
return $base64cert;
}

/**
* posts XML to the server
* @return $this
*/
public function postXML() {
$header = [
"Content-type:text/xml; charset=\"utf-8\"",
"Accept: text/xml",
"X509Certificate: ".setx509([Put your certificate file name here])
];

$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', 300);
$simpleXML->XMLTrans->addChild('accountNum', 123456789);
$simpleXML->XMLTrans->addChild('referrerUrl', 'www.myurl.com');
$simpleXML->XMLTrans->addChild('IpAddress', '206.192.156.1');
$simpleXML->XMLTrans->addChild('IpSubnetMask', '255.255.255.255');

// 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(64)

 

Required

The account to which you will "log-in"

ReferrerUrl

String

 

Required

The ProPay system requires that your single-sign-on originate from the URL originally provided here.

IpAddress

String

 

Required

The ProPay system requires that your signle sign-on originate from the URL originally provided here. Can supply a range of class c or more restrictive.

IpSubnetMask

String

120

Optional

The ProPay system requires that your signle sign-on originate from the URL originally provided here. Can supply a range of class c or more restrictive.

Response Values

Response Elements

Element

Type

Notes

status

string

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

AuthToken

String

The ProPay transaction identifier. Will be a GUID.

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