API Boarding

ProPay’s API boarding solution allows you to collect new account data using your own interface.  You can then pass that information to ProPay via HTTPS POST of XML data, or as JSON data to our REST-based web service.  ProPay will respond to your request, after a few seconds, with everything you will need to work with a new merchant.  Namely: 
  • Status – Let’s you know that the signup was successful.  May also indicate that you’ve done something wrong with data you provided, or may indicate that ProPay had to decline the account.
  • A temporary password –Needed if the merchant intends to log into ProPay’s website.  Not required if you intend to send them our way using Single-Sign-On, or if you will host the entirety of their experience on your own platform.
  • The ProPay account number – This is the value that you need to keep in order to interact with the new user via the ProPay API.
You may want to pass optional data.
While there are very few data points that you absolutely need to gather as part of a ProPay API signup, there are a LOT of additional elements that you CAN pass. 
  • The bank account to which funds settle
  • An account that you want to charge fees to
  • Want to collect a signup fee from new merchants?  You can pass their payment details.
And more...

Fields required by our API are few.  You may be obligated by ProPay (via contract) to collect and pass more information.
During the testing phase of the integration, ProPay will ensure that all required data is being passed. This may include data elements which while not technically forced by the API, are communicated to you as required by the ProPay Risk Team. If any data fields are missing, then testing will not be approved and live credentials will not be provided.  The entire list of fields that are most often required, by ProPay’s Risk team can be found  here  

Email is a unique identifier on the ProPay system.
ProPay uses email address that you provide as the username for your new account holder. As such, sourceEmail must be unique across the entire ProPay platform. If you submit a signup request with an already-used email address, you will receive a status response of 87 which indicates that the email address has already been taken. You should then instruct the user to choose another and try again.  

Good data validation is the key to successful signups
In order to create an effective signup experience, a developer needs to quickly adopt the mindset that it is crucial to protect distributors from themselves. Otherwise they will be denied an account when ProPay performs our "Know Your Customer" process. The most common elements that users provide incorrect values for are as follows: 
  • First and Last name – Believe it or not, users often struggle with their own name. Users must provide their full legal name in order to be immediately approved, and are not permitted to establish an account using a nickname or a title.
  • Social Security Number – (US only) The SSN is required only to verify identity. It should go without saying that the use of a spouses social security number instead of one's own will cause an account to be denied.
The double entry of key data fields such as SSN, and birth date, will prevent a user from 'fat fingering' information and failing identity checks. "Help" warnings next to important fields will help remind users of the importance of using correct information.

Additional step required if your merchants process using ProtectPay
One of the key competitive advantages that ProtectPay offers over most tokenization solutions is an ability to process transactions against multiple merchant platforms. Because ProtectPay is "processor agnostic", it cannot use a ProPay-specific account number as a value to define the merchant account onto which it should process transactions.  Payment Facilitators who use ProPay's ProtectPay tokenization solution will need to perform an extra step following the signup API call. This extra step is used to create a unique ProtectPay Merchant Profile ID. Learn how to  Create a Merchant Profile ID  

An additional fraud monitoring step might be required.
ProPay may require additional fraud monitoring while boarding new merchants.  ProPay's merchant boarding API supports ThreatMetrix® application monitoring.  This works when you provide "Merchant Threat Risk Assessment Information" elements during boarding AFTER you include a ThreatMetrix® widget on your signup page.  Learn how to  Pass a Profiling Tag  

 
How to call this method?

You should submit a PUT of XML data to the following URL
 
HTTP URL(s)
HTTP Verb PUT
HTTP Header Authorization
Example Request

Example Response

{
"PersonalData": {
"FirstName": "First",
"MiddleInitial": "X",
"LastName": "Last",
"DateOfBirth": "01-01-1981",
"SocialSecurityNumber": "123456789",
"SourceEmail": "ProPaytest@test.com",
"PhoneInformation": {
"DayPhone": "8888888888",
"EveningPhone": "8888888888"
},
"NotificationEmail": "Partner@partner.com"
},
"SignupAccountData": {
"CurrencyCode": "USD",
"Tier": "Test"
},
"BusinessData": {
"BusinessLegalName": "Merchantile Parent, Inc.",
"DoingBusinessAs": "Merchantile ABC",
"EIN": "121232343",
"MerchantCategoryCode": "5999",
"WebsiteURL": "http://www.Propay.com",
"BusinessDescription": "Accounting Services",
"MonthlyBankCardVolume": 10000,
"AverageTicket": 100,
"HighestTicket": 250
},

"Address": {
"ApartmentNumber": "1",
"Address1": "3400 N Ashton Blvd",
"Address2": "Suite 200",
"City": "Lehi",
"State": "UT",
"Country": "USA",
"Zip": "84043"
},
"BusinessAddress": {
"Address1": "3400 N Aston Blvd",
"Address2": "Suite 200",
"City": "Lehi",
"State": "UT",
"Country": "USA",
"Zip": "84045"
},
"BankAccount": {
"AccountCountryCode": "USA",
"BankAccountNumber": "123456789",
"RoutingNumber": "011306829",
"AccountOwnershipType": "Business",
"BankName": "MERCHANTILE BANK UT",
"AccountType": "Checking",
"AccountName": null,
"Description": null
},
"BeneficialOwnerData": {
"OwnerCount": "1",
"Owners": [{
        "FirstName": "First1",
        "LastName": "Last1",
        "SSN": "123456789",
        "DateOfBirth": "01-01-1981",
        "Email": "test1@qamail.com",
        "Address": "Address",
        "City": "Lehi",
        "State": "UT",
        "Zip": "84010",
        "Country": "USA",
        "Title": "CEO",
        "Percentage": "100"
    }]
}
}

{
    "AccountNumber": 718071685,
    "BeneficialOwnerDataResult": [
        {
            "FirstName": "First1",
            "LastName": "Last1",
            "Status": "Validated"
        }
    ],
    "Password": "TQeJzQ$23f",
    "SourceEmail": "ProPaytest@test.com",
    "Status": "00",
    "Tier": "test"
}

Implementation Details
Request Submission

namespace ProPayApi_MerchantSignup
{
using System;
using System.Text;

using RestSharp;

/*
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 MerchantSignupProgram
{
public static void Main(string[] args)
{
var merchantSignupResponse = MerchantSignUpForProPay();
}

/// <summary>
/// Signs up a Merchant for ProPay.
/// </summary>
/// <returns>The response data from the signup call.</returns>
private static SignupResponse MerchantSignUpForProPay()
{
var baseUrl = "https://xmltest.propay.com/propayapi/signup";
var request = BuildMerchantTestData();
var restRequest = CreateRestRequest("/Signup", Method.PUT);
restRequest.AddBody(request);
return Execute<SignupResponse>(restRequest, baseUrl);
}

/// <summary>
/// Builds the merchant request data.
/// </summary>
/// <returns>The request data.</returns>
private static SignupRequest BuildMerchantTestData()
{
var userid = "userId";
var email = userid + "@test.com";

var signupRequest = new SignupRequest
{
SignupAccountData = new SignupAccountData
{
ExternalId = "12345",
Tier = "Premium",
CurrencyCode = "USD",
PhonePIN = "1111",
UserId = userid
},
Address =
new Address
{
Address1 = "123 Main St.",
Address2 = "Suite 5000",
ApartmentNumber = "1",
City = "Lehi",
State = "UT",
Country = "USA",
Zip = "84013"
},
BusinessAddress =
new Address
{
Address1 = "Business Address",
Address2 = "NW",
ApartmentNumber = "333",
City = "Lehi",
State = "UT",
Country = "USA",
Zip = "84013"
},
MailAddress = new Address { Address1 = "101 Box St", City = "Lehi", State = "UT", Country = "USA", Zip = "84013" },
BankAccount =
new BankAccount
{
AccountCountryCode = "USA",
AccountType = "Checking",
AccountOwnershipType = "Business",
BankAccountNumber = "123456789",
BankName = "CITIZENS BANK NA",
RoutingNumber = "011306829"
},
SecondaryBankAccount =
new BankAccount
{
AccountCountryCode = "USA",
AccountType = "Checking",
AccountOwnershipType = "Business",
BankAccountNumber = "987654321",
BankName = "CITIZENS BANK NA",
RoutingNumber = "011306829"
},
BusinessData =
new BusinessData
{
BusinessLegalName = "Propay Merchant",
DoingBusinessAs = "Merchant Business",
EIN = "121232343",
},
CreditCardData = new CreditCardData
{
CreditCardNumber = "4111111111111111", // test card number
ExpirationDate = DateTime.Now.AddYears(1).ToString("MMyy")
},
PersonalData =
new PersonalData
{
DateOfBirth = DateTime.Now.AddYears(-30).ToString("MM-dd-yyyy"),
SourceEmail = email,
SocialSecurityNumber = "333224445",
FirstName = "First",
LastName = "Last",
MiddleInitial = "M",
PhoneInformation =
new PhoneInformation { DayPhone = "8015551212", EveningPhone = "8015551212" }
}
};
return signupRequest;
}

/// <summary>
/// Request factory to ensure API key is always first parameter added.
/// </summary>
/// <param name="resource">The resource name.</param>
/// <param name="method">The HTTP method.</param>
/// <returns>Returns a new <see cref="RestRequest"/>.</returns>
private static RestRequest CreateRestRequest(string resource, Method method)
{

var credentials = GetCredentials();

var restRequest = new RestRequest { Resource = resource, Method = method, RequestFormat = DataFormat.Json, };
restRequest.AddHeader("accept", "application/json");
restRequest.AddHeader("Authorization", credentials);
return restRequest;
}

private static string GetCredentials()
{
var termId = "AffTermId01"; // put affiliate term id here, if you have it
var certString = "TestAffiliateMerchCertString01"; // put affiliate cert string here
var encodedCredentials = Convert.ToBase64String(termId == null ? Encoding.Default.GetBytes(certString) : Encoding.Default.GetBytes(certString + ":" + termId));

var credentials = string.Format("Basic {0}", encodedCredentials);
return credentials;
}

/// <summary>
/// Executes a particular http request to a resource.
/// </summary>
/// <typeparam name="T">The response type.</typeparam>
/// <param name="request">The REST request.</param>
/// <param name="baseUrl">The base URL.</param>
/// <returns>Returns a response of the type parameter.</returns>
private static T Execute<T>(IRestRequest request, string baseUrl) where T : class, new()
{
var client = new RestClient(baseUrl);
var response = client.Execute<T>(request);

if (response.ErrorException != null)
{
Console.WriteLine(
"Error: Exception: {0}, Headers: {1}, Content: {2}, Status Code: {3}",
response.ErrorException,
response.Headers,
response.Content,
response.StatusCode);
}

return response.Data;
}

/// <summary>
/// Defines request body of a signup request.
/// </summary>
public class SignupRequest
{
/// <summary>
/// Gets or sets the Personal Data.
/// </summary>
public PersonalData PersonalData { get; set; }

/// <summary>
/// Gets or sets the Account Data.
/// </summary>
public SignupAccountData SignupAccountData { get; set; }

/// <summary>
/// Gets or sets the Business Data.
/// </summary>
public BusinessData BusinessData { get; set; }

/// <summary>
/// Gets or sets the Credit Card Information.
/// </summary>
public CreditCardData CreditCardData { get; set; }

/// <summary>
/// Gets or sets the Address.
/// </summary>
public Address Address { get; set; }

/// <summary>
/// Gets or sets the MailAddress.
/// </summary>
public Address MailAddress { get; set; }

/// <summary>
/// Gets or sets the BusinessAddress.
/// </summary>
public Address BusinessAddress { get; set; }

/// <summary>
/// Gets or sets the BankAccount.
/// </summary>
public BankAccount BankAccount { get; set; }

/// <summary>
/// Gets or sets the SecondaryBankAccount.
/// </summary>
public BankAccount SecondaryBankAccount { get; set; }

/// <summary>
/// Gets or sets the Gross Billing Information.
/// </summary>
public GrossBillingInformation GrossBillingInformation { get; set; }

/// <summary>
/// Gets or sets Fraud detection data.
/// </summary>
public FraudDetectionData FraudDetectionData { get; set; }

/// <summary>
/// Gets or sets the PaymentMethodId.
/// </summary>
public string PaymentMethodId { get; set; }
}

/// <summary>
/// Class for personal data like name, DOB.
/// </summary>
public class PersonalData
{
/// <summary>
/// Gets or sets the SourceEmail.
/// </summary>
public string SourceEmail { get; set; }

/// <summary>
/// Gets or sets the FirstName.
/// </summary>
public string FirstName { get; set; }

/// <summary>
/// Gets or sets the MiddleInitial.
/// </summary>
public string MiddleInitial { get; set; }

/// <summary>
/// Gets or sets the LastName.
/// </summary>
public string LastName { get; set; }

/// <summary>
/// Gets or sets the Date of Birth (MM-DD-YYYY).
/// </summary>
public string DateOfBirth { get; set; }

/// <summary>
/// Gets or sets the SocialSecurityNumber.
/// </summary>
public string SocialSecurityNumber { get; set; }

/// <summary>
/// Gets or sets the Phone Information.
/// </summary>
public PhoneInformation PhoneInformation { get; set; }

/// <summary>
/// Gets or sets the International Sign up data.
/// </summary>
public InternationalSignup InternationalSignUpData { get; set; }
}

/// <summary>
/// Class to collect the Phone Data.
/// </summary>
public class PhoneInformation
{
/// <summary>
/// Gets or sets the DayPhone.
/// </summary>
public string DayPhone { get; set; }

/// <summary>
/// Gets or sets the EveningPhone.
/// </summary>
public string EveningPhone { get; set; }
}

/// <summary>
/// Class to collect the Data for International Sign ups.
/// </summary>
public class InternationalSignup
{
/// <summary>
/// Gets or sets International Document Number.
/// </summary>
public string InternationalId { get; set; }

/// <summary>
/// Gets or sets Driver License Version.
/// </summary>
public string DriversLicenseVersion { get; set; }

/// <summary>
/// Gets or sets Document Type (deeper validation).
/// Allowed Values - DriversLicense, Passport or AustralianMedCard.
/// </summary>
public string DocumentType { get; set; }

/// <summary>
/// Gets or sets Document Expiration date.
/// </summary>
public DateTime DocumentExpDate { get; set; }

/// <summary>
/// Gets or sets Document Issuing state.
/// </summary>
public string DocumentIssuingState { get; set; }

/// <summary>
/// Gets or sets Medicate Reference Number.
/// </summary>
public string MedicareReferenceNumber { get; set; }

/// <summary>
/// Gets or sets Medicate Card Color.
/// </summary>
public string MedicareCardColor { get; set; }
}

/// <summary>
/// Attributes for the Account.
/// </summary>
public class SignupAccountData
{
/// <summary>
/// Gets or sets the CurrencyCode.
/// </summary>
public string CurrencyCode { get; set; }

/// <summary>
/// Gets or sets the UserId.
/// </summary>
public string UserId { get; set; }

/// <summary>
/// Gets or sets the PhonePIN.
/// </summary>
public string PhonePIN { get; set; }

/// <summary>
/// Gets or sets the ExternalId.
/// </summary>
public string ExternalId { get; set; }

/// <summary>
/// Gets or sets the Tier.
/// </summary>
public string Tier { get; set; }
}

/// <summary>
/// Class to represent the Business Data.
/// </summary>
public class BusinessData
{
/// <summary>
/// Gets or sets the BusinessLegalName.
/// </summary>
public string BusinessLegalName { get; set; }

/// <summary>
/// Gets or sets the DoingBusinessAs.
/// </summary>
public string DoingBusinessAs { get; set; }

/// <summary>
/// Gets or sets the EIN.
/// </summary>
public string EIN { get; set; }

/// <summary>
/// Gets or sets the Merchant Category Code.
/// </summary>
public string MerchantCategoryCode { get; set; }

/// <summary>
/// Gets or sets the website url.
/// </summary>
public string WebsiteURL { get; set; }

/// <summary>
/// Gets or sets the Business Description.
/// </summary>
public string BusinessDescription { get; set; }

/// <summary>
/// Gets or sets the Monthly Card Volume.
/// </summary>
public long MonthlyBankCardVolume { get; set; }

/// <summary>
/// Gets or sets the Average Ticket size.
/// </summary>
public int AverageTicket { get; set; }

/// <summary>
/// Gets or sets the Highest Ticket Size.
/// </summary>
public int HighestTicket { get; set; }
}

/// <summary>
/// Class for Credit Card Data.
/// </summary>
public class CreditCardData
{
/// <summary>
/// Gets or sets the Name on the credit card.
/// </summary>
public string NameOnCard { get; set; }

/// <summary>
/// Gets or sets the CreditCardNumber.
/// </summary>
public string CreditCardNumber { get; set; }

/// <summary>
/// Gets or sets the ExpirationDate.
/// </summary>
public string ExpirationDate { get; set; }
}

/// <summary>
/// Address contract.
/// </summary>
public class Address
{
/// <summary>
/// Gets or sets the ApartmentNumber.
/// </summary>
public string ApartmentNumber { get; set; }

/// <summary>
/// Gets or sets the Address1.
/// </summary>
public string Address1 { get; set; }

/// <summary>
/// Gets or sets the Address2.
/// </summary>
public string Address2 { get; set; }

/// <summary>
/// Gets or sets the City.
/// </summary>
public string City { get; set; }

/// <summary>
/// Gets or sets the State.
/// </summary>
public string State { get; set; }

/// <summary>
/// Gets or sets the Country.
/// </summary>
public string Country { get; set; }

/// <summary>
/// Gets or sets the Zip.
/// </summary>
public string Zip { get; set; }
}

/// <summary>
/// Bank account contact.
/// </summary>
public class BankAccount
{
/// <summary>
/// Gets or sets the AccountCountryCode.
/// </summary>
public string AccountCountryCode { get; set; }

/// <summary>
/// Gets or sets the BankAccountNumber.
/// </summary>
public string BankAccountNumber { get; set; }

/// <summary>
/// Gets or sets the RoutingNumber.
/// </summary>
public string RoutingNumber { get; set; }

/// <summary>
/// Gets or sets the AccountOwnershipType.
/// </summary>
public string AccountOwnershipType { get; set; }

/// <summary>
/// Gets or sets the BankName.
/// </summary>
public string BankName { get; set; }

/// <summary>
/// Gets or sets the AccountType.
/// </summary>
public string AccountType { get; set; }

/// <summary>
/// Gets or sets the Account Name.
/// </summary>
public string AccountName { get; set; }

/// <summary>
/// Gets or sets the Description.
/// </summary>
public string Description { get; set; }
}

/// <summary>
/// Class for the Gross Settlement Data.
/// </summary>
public class GrossBillingInformation
{
/// <summary>
/// Gets or sets the Bank Account information for the Gross Settlement.
/// </summary>
public BankAccount GrossSettleBankAccount { get; set; }

/// <summary>
/// Gets or sets the Gross Settle Address.
/// </summary>
public Address GrossSettleAddress { get; set; }

/// <summary>
/// Gets or sets the Credit Card Data for Gross Settle.
/// </summary>
public CreditCardData GrossSettleCardData { get; set; }
}

/// <summary>
/// Class for Collecting Fraud Prevention Data.
/// </summary>
public class FraudDetectionData
{
/// <summary>
/// Gets or sets the Merchant IP Address.
/// </summary>
public string MerchantSourceIp { get; set; }

/// <summary>
/// Gets or sets the Threat Metrix Policy.
/// </summary>
public string ThreatMetrixPolicy { get; set; }

/// <summary>
/// Gets or sets the Threat Metrix Session Id.
/// </summary>
public string ThreatMetrixSessionId { get; set; }
}

/// <summary>
/// Defines response body of a signup request.
/// </summary>
public class SignupResponse
{
/// <summary>
/// Gets or sets the ProPay account number.
/// </summary>
public long AccountNumber { get; set; }

/// <summary>
/// Gets or sets the email address.
/// </summary>
public string SourceEmail { get; set; }

/// <summary>
/// Gets or sets the account password.
/// </summary>
public string Password { get; set; }

/// <summary>
/// Gets or sets the tier name.
/// </summary>
public string Tier { get; set; }

/// <summary>
/// Gets or sets the response status.
/// </summary>
public string Status { get; set; }
}
}
}

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

private $_certStr;
private $_termId;

/* for signups */
private $_signupData;
private $_signupInfo;

/**
* @param string $certStr
* @return $this
*/
public function setCertStr($certStr) {
$this->_certStr = $certStr;
return $this;
}

/**
* @param array $signupData
* @return $this
*/
public function setSignupData($signupData) {
$this->_signupData = $signupData;
return $this;
}

/**
* @param string $termId
* @return $this
*/
public function setTermId($termId) {
$this->_termId = $termId;
return $this;
}

/**
* @return string
*/
private function _getAuth() {
return $this->_certStr . ':' . $this->_termId;
}

/**
* Processes the signup process through the rest api
* @return $this
*/
public function processSignup() {
$data_string = json_encode($this->_signupData);

$ch = curl_init($this->_apiBaseUrl . '/ProPayAPI/signup');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "PUT");
curl_setopt($ch, CURLOPT_POSTFIELDS, $data_string);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_USERPWD, $this->_getAuth());
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
'Content-Type: application/json',
'Content-Length: ' . strlen($data_string)
));

$this->_signupInfo = curl_exec($ch);
return $this;
}

/**
* Gets a json string of the signupInfo of the tier that was just signed up. A signed up response
* looks like
* {"AccountNumber":32299999,"Password":"$#GD!ADXv2","SourceEmail":"someuser@somedomain.com","Status":"00","Tier":"Platinum"}
* @return mixed
*/
public function getSignupInfo() {
return $this->_signupInfo;
}

}

$data = [
"SourceEmail" => "someemail@somedomain.com",
"FirstName" => "John",
"MiddleInitial" => "Q",
"LastName" => "Test",
"BusinessLegalName" => "ProPay Partner",
"DoingBusinessAs" => "PPA",
"DateOfBirth" => "1/19/1997",
"DayPhone" => "8601233421",
"EveningPhone" => "8601233421",
"SocialSecurityNumber" => "111111111",
"ExternalId" => "3212157",
"Tier" => "Merchant",
"PhonePIN" => "1234",
"Address" => [
"ApartmentNumber" => null,
"Address1" => "100 Main Street",
"Address2" => null,
"City" => "Rocky Hill",
"State" => "CT",
"Country" => "USA",
"Zip" => "06067"
],
"BankAccount" => [
"AccountCountryCode" => "USA",
"AccountOwnershipType" => "Personal",
"AccountType" => "C",
"BankAccountNumber" => "123456789",
"BankName" => "Wells Fargo",
"RoutingNumber" => "102000076"
],
"BusinessAddress" => [
"Address1" => "101 Main Street",
"Address2" => "Ste. 200",
"City" => "Rocky Hill",
"State" => "CT",
"Country" => "USA",
"Zip" => "06067"
]
];


/**
 * The cert string and setTermId would normally be in a config or in your database
 * This call normally yields return json data for the account created like so
 * {"AccountNumber" => 32299999,"Password" => "$#GD!ADXv2","SourceEmail" => "someuser@somedomain.com","Status":"00","Tier":"Platinum"}
 */

$proPayAPI = new ProPayApi();
$result = $proPayAPI->setCertStr('thecertstringgoesin here')
->setTermId('termid goes here')
->setSignupData($data)
->processSignup()
->getSignupInfo();

The online Windows XP simulator runs in a web browser and its operation imitates the operating system. You can use it to prank someone.

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

import java.io.IOException;
import java.text.DateFormat;
import java.text.SimpleDateFormat;
import java.util.Calendar;
import java.util.Date;

import com.fasterxml.jackson.core.JsonProcessingException;
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.ObjectMapper;
import com.mashape.unirest.http.Unirest;
import com.mashape.unirest.http.exceptions.UnirestException;
import com.mashape.unirest.request.HttpRequest;
import com.mashape.unirest.request.HttpRequestWithBody;

public class MerchantSignupSample {
 /**
* This URL would normally come from some configuration file or database.
*/
 final static String ApiUrl = "https://xmltestapi.propay.com/propayapi/";

 public static void main(String[] args) {
configureObjectMapper();

MerchantSignupSample program = new MerchantSignupSample();
SignupResponse response = program.signup();

System.out.println("Signup Status:" + response.Status);
System.out.println("Source email: " + response.SourceEmail);
System.out.println("Tier id: " + response.Tier);
System.out.println("Account number: " + response.AccountNumber);
System.out.println("Generated password: " + response.Password);
 }

 /**
* Execute a signup.
*
* @return The signup response.
*/
 public SignupResponse signup() {
String resourceUrl = ApiUrl + "Signup";

SignupRequest signupRequest = new SignupRequest();
SignupAccountData accountData = this.getSignupAccountData();
Address physicalAddress = this.getPhysicalAddress();
Address mailingAddress = this.getMailingAddress();
Address businessAddress = this.getBusinessAddress();
BankAccount primaryBankAccount = this.getPrimaryBankAccount();
BankAccount secondaryBankAccount = this.getSecondaryBankAccount();
BusinessData businessData = this.getMerchantBusinessData();
PersonalData personalData = this.getPersonalData();

signupRequest.SignupAccountData = accountData;
signupRequest.Address = physicalAddress;
signupRequest.MailAddress = mailingAddress;
signupRequest.BusinessAddress = businessAddress;
signupRequest.BankAccount = primaryBankAccount;
signupRequest.SecondaryBankAccount = secondaryBankAccount;
signupRequest.BusinessData = businessData;
signupRequest.PersonalData = personalData;

CreditCardData creditCard = new CreditCardData();
creditCard.NameOnCard = "Chris Cornell";
creditCard.CreditCardNumber = "4111111111111111";
creditCard.ExpirationDate = this.generateExpirationDate();

signupRequest.CreditCardData = creditCard;

HttpRequestWithBody request = this.createRequest(resourceUrl);

request.body(signupRequest);

return this.executeRequest(request, SignupResponse.class);
 }

 /**
* The affiliate certificate string.
*
* Normally this would be in a database or configuration file.
*/
 private String getCertString() {
return "P1r305Pc4fy6S942m0p0la3c";
 }


 /**
* Populate the user's basic account data.
*/
 private SignupAccountData getSignupAccountData() {
String tierName = "Premium";

SignupAccountData accountData = new SignupAccountData();
accountData.ExternalId = "246820";
accountData.Tier = tierName;
accountData.CurrencyCode = "USD";
accountData.PhonePIN = "1111";

return accountData;
 }

 /**
* Populate the user's mailing address.
*/
 private Address getMailingAddress() {
Address address = new Address();
address.Address1 = "101 Box St";
address.City = "Lehi";
address.State = "UT";
address.Country = "USA";
address.Zip = "84043";

return address;
 }

 /**
* Populate the user's physical address.
*/
 private Address getPhysicalAddress() {
Address address = new Address();
address.Address1 = "123 Main St";
address.Address2 = "Suite 5000";
address.ApartmentNumber = "1";
address.City = "Lehi";
address.State = "UT";
address.Country = "USA";
address.Zip = "84043";

return address;
 }

 /**
* Populate the user's business address.
*/
 private Address getBusinessAddress() {
Address address = new Address();
address.Address1 = "Business Address";
address.Address2 = "NW";
address.ApartmentNumber = "333";
address.City = "Lehi";
address.State = "UT";
address.Country = "USA";
address.Zip = "84043";

return address;
 }

 /**
* Populate the merchant's primary bank account.
*/
 private BankAccount getPrimaryBankAccount() {
BankAccount bankAccount = new BankAccount();
bankAccount.AccountCountryCode = "USA";
bankAccount.AccountType = "Checking";
bankAccount.AccountOwnershipType = "Business";
bankAccount.BankAccountNumber = "123456789";
bankAccount.BankName = "CITIZENS BANK NA";
bankAccount.RoutingNumber = "011306829";

return bankAccount;
 }

 /**
* Populate the merchant's secondary bank account.
*/
 private BankAccount getSecondaryBankAccount() {
BankAccount bankAccount = new BankAccount();
bankAccount.AccountCountryCode = "USA";
bankAccount.AccountType = "Checking";
bankAccount.AccountOwnershipType = "Business";
bankAccount.BankAccountNumber = "987654321";
bankAccount.BankName = "CITIZENS BANK NA";
bankAccount.RoutingNumber = "011306829";

return bankAccount;
 }

 /**
* Populate the merchant's business information.
*/
 private BusinessData getMerchantBusinessData() {
BusinessData businessData = new BusinessData();
businessData.BusinessLegalName = "ProPay Merchant";
businessData.DoingBusinessAs = "Merchant Business";

return businessData;
 }

 /**
* Get the merchant's personal information
*/
 private PersonalData getPersonalData() {
String birthdate = generateBirthDate();

PersonalData personalData = new PersonalData();
personalData.DateOfBirth = birthdate;
personalData.SourceEmail = "merchant90@test.com";
personalData.SocialSecurityNumber = "987654321";
personalData.FirstName = "First";
personalData.MiddleInitial = "M";
personalData.LastName = "Last";

PhoneInformation phoneInfo = new PhoneInformation();
phoneInfo.DayPhone = "8015551212";
phoneInfo.EveningPhone = "8015551212";

personalData.PhoneInformation = phoneInfo;

return personalData;
 }

 /**
* Create the request instance. This ensures that the authentication header
* is attached to each request.
*
* @param resourceUrl
* The URL of the REST resource.
* @return The GetRequest instance.
*/
 private HttpRequestWithBody createRequest(String resourceUrl) {
String certString = this.getCertString();


HttpRequestWithBody restRequest = Unirest.put(resourceUrl).basicAuth(certString, null)
.header("accept", "application/json").header("Content-Type", "application/json");

return restRequest;
 }

 /**
* Execute a REST request.
*
* @param request
* The request to perform.
* @param responseClass
* The type instance of the return type.
* @return An instance of type T or null if there was an error.
*/
 private <T> T executeRequest(HttpRequest request, Class<T> responseClass) {
try {
HttpResponse<T> response = request.asObject(responseClass);
if (response.getStatus() != 200) { // HTTP OK response code
System.out.println(response.getStatusText());
return null;
}

return response.getBody();
} catch (UnirestException e) {
e.printStackTrace();
}

return null;
 }

 /**
* Generate an expiration date that is always valid.
*/
 private String generateExpirationDate() {
Date currentDate = new Date();
Calendar c = Calendar.getInstance();
c.setTime(currentDate);

c.add(Calendar.YEAR, 1);
Date expirationDate = c.getTime();

DateFormat format = new SimpleDateFormat("MMyy");
return format.format(expirationDate);
 }

 /**
* Generate a birth date for a 30 year old man.
*/
 private String generateBirthDate() {
Date currentDate = new Date();
Calendar c = Calendar.getInstance();
c.setTime(currentDate);

c.add(Calendar.YEAR, -30);
Date birthDate = c.getTime();

DateFormat format = new SimpleDateFormat("MM-dd-yyyy");
String birthdate = format.format(birthDate);
return birthdate;
 }

 /**
* Configures the mapping between JSON and Classes.
*
* This is boilerplate Unirest & Jackson configuration. It should only need
* to be done once in a full solution.
*/
 private static void configureObjectMapper() {
Unirest.setObjectMapper(new ObjectMapper() {
private com.fasterxml.jackson.databind.ObjectMapper jacksonObjectMapper = new com.fasterxml.jackson.databind.ObjectMapper();

public <T> T readValue(String value, Class<T> valueType) {
try {
return jacksonObjectMapper.readValue(value, valueType);
} catch (IOException e) {
throw new RuntimeException(e);
}
}

public String writeValue(Object value) {
try {
return jacksonObjectMapper.writeValueAsString(value);
} catch (JsonProcessingException e) {
throw new RuntimeException(e);
}
}
});
 }
}


// -------------------------------------------------------------------------------------------- //
// Object files

// Address.java

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

/**
 * Address contract.
 */
public class Address {
 /**
* Gets or sets the ApartmentNumber.
*/
 public String ApartmentNumber;

 /**
* Gets or sets the Address1.
*/
 public String Address1;

 /**
* Gets or sets the Address2.
*/
 public String Address2;

 /**
* Gets or sets the City.
*/
 public String City;

 /**
* Gets or sets the State.
*/
 public String State;

 /**
* Gets or sets the Country.
*/
 public String Country;

 /**
* Gets or sets the Zip.
*/
 public String Zip;
}

// -------------------------------------------------------------------------------------------- //
// BankAccount.java

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

/**
 * Bank account contact.
 */
public class BankAccount {
 /**
* Gets or sets the AccountCountryCode.
*/
 public String AccountCountryCode;

 /**
* Gets or sets the BankAccountNumber.
*/
 public String BankAccountNumber;

 /**
* Gets or sets the RoutingNumber.
*/
 public String RoutingNumber;

 /**
* Gets or sets the AccountOwnershipType.
*/
 public String AccountOwnershipType;

 /**
* Gets or sets the BankName.
*/
 public String BankName;

 /**
* Gets or sets the AccountType.
*/
 public String AccountType;

 /**
* Gets or sets the Account Name.
*/
 public String AccountName;

 /**
* Gets or sets the Description.
*/
 public String Description;
}

// -------------------------------------------------------------------------------------------- //
// BusinessData.java

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

/**
 * Class to represent the Business Data.
 */
public class BusinessData {
 /**
* Gets or sets the BusinessLegalName.
*/
 public String BusinessLegalName;

 /**
* Gets or sets the DoingBusinessAs.
*/
 public String DoingBusinessAs;

 /**
* Gets or sets the EIN.
*/
 public String EIN;

 /**
* Gets or sets the Merchant Category Code.
*/
 public String MerchantCategoryCode;

 /**
* Gets or sets the website url.
*/
 public String WebsiteURL;

 /**
* Gets or sets the Business Description.
*/
 public String BusinessDescription;

 /**
* Gets or sets the Monthly Card Volume.
*/
 public long MonthlyBankCardVolume;

 /**
* Gets or sets the Average Ticket size.
*/
 public int AverageTicket;

 /**
* Gets or sets the Highest Ticket Size.
*/
 public int HighestTicket;
}

// -------------------------------------------------------------------------------------------- //
// CreditCardData.java

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

/**
 * Class for Credit Card Data.
 */
public class CreditCardData {
 /**
* Gets or sets the Name on the credit card.
*/
 public String NameOnCard;

 /**
* Gets or sets the CreditCardNumber.
*/
 public String CreditCardNumber;

 /**
* Gets or sets the ExpirationDate.
*/
 public String ExpirationDate;
}

// -------------------------------------------------------------------------------------------- //
// PersonalData.java

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

/**
 * Class for personal data like name, DOB.
 */
public class PersonalData {
 /**
* Gets or sets the SourceEmail.
*/
 public String SourceEmail;

 /**
* Gets or sets the FirstName.
*/
 public String FirstName;

 /**
* Gets or sets the MiddleInitial.
*/
 public String MiddleInitial;

 /**
* Gets or sets the LastName.
*/
 public String LastName;

 /**
* Gets or sets the Date of Birth (MM-DD-YYYY).
*/
 public String DateOfBirth;

 /**
* Gets or sets the SocialSecurityNumber.
*/
 public String SocialSecurityNumber;

 /**
* Gets or sets the Phone Information.
*/
 public PhoneInformation PhoneInformation;
}

// -------------------------------------------------------------------------------------------- //
// PhoneInformation.java

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

/**
 * Class to collect the Phone Data.
 */
public class PhoneInformation {
 /**
* Gets or sets the DayPhone.
*/
 public String DayPhone;

 /**
* Gets or sets the EveningPhone.
*/
 public String EveningPhone;
}

// -------------------------------------------------------------------------------------------- //
// SignupAccountData.java

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

/**
 * Attributes for the Account.
 */
public class SignupAccountData {
 /**
* Gets or sets the CurrencyCode.
*/
 public String CurrencyCode;

 /**
* Gets or sets the UserId.
*/
 public String UserId;

 /**
* Gets or sets the PhonePIN.
*/
 public String PhonePIN;

 /**
* Gets or sets the ExternalId.
*/
 public String ExternalId;

 /**
* Gets or sets the Tier.
*/
 public String Tier;
}

// -------------------------------------------------------------------------------------------- //
// SignupRequest.java


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

/**
 * Defines request body of a signup request.
 */
public class SignupRequest {
 /**
* The Personal Data.
*/
 public PersonalData PersonalData;

 /**
* Gets or sets the Account Data.
*/
 public SignupAccountData SignupAccountData;

 /**
* Gets or sets the Business Data.
*/
 public BusinessData BusinessData;

 /**
* Gets or sets the Credit Card Information.
*/
 public CreditCardData CreditCardData;

 /**
* Gets or sets the Address.
*/
 public Address Address;

 /**
* Gets or sets the MailAddress.
*/
 public Address MailAddress;

 /**
* Gets or sets the BusinessAddress.
*/
 public Address BusinessAddress;

 /**
* Gets or sets the BankAccount.
*/
 public BankAccount BankAccount;

 /**
* Gets or sets the SecondaryBankAccount.
*/
 public BankAccount SecondaryBankAccount;

 /**
* Gets or sets the PaymentMethodId.
*/
 public String PaymentMethodId;
}

// -------------------------------------------------------------------------------------------- //
// SignupResponse.java

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

/**
 * Defines response body of a signup request.
 */
public class SignupResponse {
 /**
* Gets or sets the ProPay account number.
*/
 public long AccountNumber;

 /**
* Gets or sets the email address.
*/
 public String SourceEmail;

 /**
* Gets or sets the account password.
*/
 public String Password;

 /**
* Gets or sets the tier name.
*/
 public String Tier;

 /**
* Gets or sets the response status.
*/
 public String Status;
}

Response Handling

The following sample uses the Unirest and Jackson libraries.

You can add them to your project using:

Apache Maven
<dependency>
<groupId>com.mashape.unirest</groupId>
<artifactId>unirest-java</artifactId>
<version>1.4.9</version>
</dependency>
<dependency>
<groupId>com.fasterxml.jackson.core</groupId>
<artifactId>jackson-databind</artifactId>
<version>2.8.8.1</version>
</dependency>


Gradle/Grails
compile 'com.mashape.unirest:unirest-java:1.4.9'
compile 'com.fasterxml.jackson.core:jackson-databind:2.8.8.1'

Request Submission

Response Handling

Request Values

Element

Type

Max

Required

Notes

PersonalData{

FirstName

String

20

Required

Merchant/Individual first names.

PersonalData{

MiddleInitial

String

2

Optional

Merchant/Individual middle initial.

PersonalData{

LastName

String

25

Required

Merchant/Individual last name.

PersonalData{

DateOfBirth

String

 

Required

Merchant/Individual Date of birth. Must be in ‘mm-dd-yyyy’ format. *Individual must be 18+ to obtain an account. The value 01-01-1981 will give a successful response. All others will return a Status 66 (Failed KYC).

PersonalData{

SocialSecurityNumber

String

9

Optional*

Merchant/Individual social security number. Must be 9 characters without dashes. *Required for USA when using personal validation. If business validated, do not pass!

PersonalData{

SourceEmail

String

55

Required

Merchant/Individual email address. Must be unique in ProPay system. *ProPay’s system will send automated emails to the email address on file unless NotificationEmail is provided. *Truncated, if value provided is greater than max value.

PersonalData{

PhoneInformation{

DayPhone

String

 

Required

Merchant/Individual day phone number. *For USA, CAN, NZL and AUS value must be 10 characters with no dashes

PeronsalData{

PhoneInformation{

EveningPhone

String

 

Required

Merchant/Individual evening phone number. *For USA, CAN, NZL and AUS value must be 10 characters with no dashes

PersonalData{

NotificationEmail

String

55

Optional

Communication Email Address. *ProPay’s system will send automated emails to the email address on file rather than the Source Email. 

SignupAccountData{

CurrencyCode

String

3

Optional*

Required to specify the currency in which funds should be held, if other than USD. An affiliation must be granted permission to create accounts in currencies other than USD. ISO 4217 standard 3 character currency code.

SignupAccountData{

Tier

String

 

Optional*

One of the previously assigned merchant tiers. *If not provided, will default to cheapest available tier.

SignupAccountData{

ExternalId

String

20

Optional

This is a partner’s own unique identifier. Typically used as the distributor or consultant ID.

SignupAccountData{

PhonePin

String

4

Optional

Numeric value which will give a user access to ProPay’s IVR system. Can also be used to reset password.

SignupAccountData{

UserId

String

55

Optional

ProPay account username. Must be unique in ProPay system. *Username defaults to <sourceEmail> if userId is not provided.

 

Personal Address - Required

Element

Type

Max

Required

Notes

Address{

Address1

 

String

100

Required

Merchant/Individual physical street Address. PO Boxes are not allowed.

Address{

Address2

String

100

Optional

Merchant/Individual physical Address. Use for 2nd Address Line

Address{

City

String

30

Required

Merchant/Individual physical Address city.

Address{

State

String

3

Required

Merchant/Individual physical Address state. *Standard 2 character abbreviation for state, province, prefecture, etc.

Address{

Zip

 

String

 

Required

Merchant/Individual physical Address zip/postal code. For USA: 5 or 9 characters without dash. For CAN: 6 characters postal code with a space "XXX XXX" For AUS and NZ 4 character code.

Address{

Country

 

String

3

Optional

ISO 3166 standard 3 character country codes. Required if creating an account in a country other than USA. *Country must be an approved country to create a ProPay account.

 

Business Data – Required for business validated accounts. May also be required for personal validated accounts by ProPay Risk Team

Element

Type

Max

Required

Notes

BusinessData{

BusinessLegalName

String

255

Required

The legal name of the business as registered.

BusinessData{

DoingBusinessAs

String

255

Required

This field can be used to provide DBA information on an account. ProPay accounts can be configured to display DBA on cc statements.

BusinessData{

EIN

String

 

Required

Employer Identification Number can be added to a ProPay account.

BusinessData{

MerchantCategoryCode

String

4

Optional

Merchant Category Code

BusinessData{

WebsiteURL

String

255

Required

The Business’ website URL

BusinessData{

BusinessDesc

String

255

Optional

The Business’ description

BusinessData{

MonthlyBankCardVolume

Int(64)

 

Required

The monthly volume of bank card transactions; Value representing the number of pennies in USD, or the number of [currency] without decimals. Defaults to $1000.00 if not sent

BusinessData{

AverageTicket

Int(64)

 

Required

The average amount of an individual transaction; Value representing the number of pennies in USD, or the number of [currency] without decimals. Defaults to $300.00 if not sent.

BusinessData{

HighestTicket

Int(64)

 

Required

The highest transaction amount; Value representing the number of pennies in USD, or the number of [currency] without decimals. Defaults to $300.00 if not sent. 

BusinessAddress{

Address1

String

100

Required

Business Physical Address

BusinessAddress{
Address2

String

100

Optional

Business Physical Address

BusinessAddress{

City

String

30

Required

Business Physical Address City

BusinessAddress{

Country

String

 

Required

Must be ISO standard 3 character country code.

BusinessAddress{

State

String

3

Required

If domestic signup this value MUST be one of the standard 2 character abbreviations. Rule also applies for Canadian signups. (Must be standard province abbreviation.)

BusinessAddress{

Zip

String

 

Required

For USA: 5 or 9 characters without dash. For CAN: 6 characters postal code with a space "XXX XXX". For AUS and NZ 4 character code.

 

International Signup Data – Frequently Required for partners who sign up international merchants

Element

Type

Max

Required

Notes

PersonalData{

InternationalData{

DocumentType

String

1

Optional*

Values 1( Driver’s license), 2(Passport), 3( Australia Medicare)

PersonalData{

InternationalData{

InternationalId

String

 

Optional*

Corresponds to the document number provided by DocumentType.

PersonalData{

InternationalData{

DocumentExpDate

String

 

Optional*

Corresponds to the Expiry date of the document provided by DocumentType. Should be a valid date. mm-dd-yyyy

PersonalData{

InternationalData{

DocumentIssuingState

String

3

Optional*

Required if the DocumentType is 1 (Driver’s license). The driver’s license issuing state.

PersonalData{

InternationalData{

DriversLicenseVersion

String

 

Optional*

Required if the DocumentType is 1 (Driver’s license) and Country is NZL. This is driver’s license version number.

PersonalData{

InternationalData{

MedicareReferenceNumber

String

1

Optional*

Required if the DocumentType is 3 (Australia Medicare) and Country is AUS. The data should be parsed to Number.

PersonalData{

InternationalData{

MedicareCardColor

String

 

Optional*

Required if the DocumentType is 3 (Australia Medicare) and Country is AUS.

Valid values are: Yellow, Green, Blue

 

Account Payment (Credit Card) Information – A payment method is required if account fee not paid for by partner

Element

Type

Max

Required

Notes

CreditCardData{

NameOnCard

String

 

Required

Card holder’s name as it appears on card.

CreditCardData{

CreditCardNumber

String

16

Required

Must pass Luhn check. Used to pay for an account if ProPay has not set account type up as free to users.

CreditCardData{

ExpDate

String

4

Required

Used to pay for an account if ProPay has not set account type up as free to users. Submitted as mmyy.

 

Account Payment (ACH) Information – A payment method is required if account fee not paid for by partner

Element

Type

Max

Required

Notes

PaymentBank{

AccountNumber

String

 

Required

Used to pay for an account via ACH and monthly renewal. Financial institution account number.

PaymentBank{

RoutingNumber

String

 

Required

Used to pay for an account via ACH and monthly renewal. Financial institution routing number. Must be a valid ACH routing number.

PaymentBank{

AccountType

String

 

Required

Used to pay for an account via ACH and monthly renewal. Valid values are: Checking, Savings, and GeneralLedger

 

Account Payment (ProtectPay) Information – A payment method is required if account fee not paid for by partner

Element

Type

Max

Required

Notes

PaymentMethodId

String

 

Required

Used to pay for an account via a ProtectPay Payment Method ID. Valid value is a GUID.

 

Mailing Address – Optional. Used if mailed correspondence from Propay should be sent to separate address

Element

Type

Max

Required

Notes

MailAddress{

Address1

String

100

Optional

Merchant/Individual mailing address if different than physical address.

MailAddress{

Address2

String

 

Optional

Merchant/Individual mailing address if different than physical address.

MailAddress{

City

String

30

Optional

Merchant/Individual mailing city if different than physical address.

MailAddress{

State

String

3

Optional

Merchant/Individual mailing state if different than physical address. *Standard 2 character abbreviation for state, province, prefecture, etc.

MailAddress{

Country

String

3

Optional

ISO 3166 standard 3 character country codes. Required if creating an account in a country other than USA.

MailAddress{

Zip

String

 

Optional

Merchant/Individual mailing zip/postal code if different than physical address. For USA: 5 or 9 characters without dash. For CAN: 6 characters postal code with a space "XXX XXX" For AUS and NZ 4 character code.

 

Primary Bank Account Information – Optional. Used to add a bank account to which funds can be settled

Element

Type

Max

Required

Notes

BankAccount{

AccountCountryCode

String

3

Required

ISO 3166 standard 3-character country code.

BankAccount{

AccountName

String

32

Required

Merchant/Individual Name.

BankAccount{

BankAccountNumber

String

25

Required

Financial institution account number.

BankAccount{

AccountOwnershipType

String

15

Required

Valid values are: Personal and Business

BankAccount{

AccountType

String

1

Required

Valid values are:

C – Checking, S – Savings , G – General Ledger

BankAccount{

BankName

String

50

Required

Name of financial institution.

BankAccount{

RoutingNumber

String

9

Required

Financial institution routing number. Must be a valid ACH routing number.

 

Secondary Bank Account Information – Optional. Used to add an account from which fees are pulled. Only works when Primary bank added

Element

Type

Max

Required

Notes

SecondaryBankAccount{

AccountCountryCode

String

3

Required

Required if adding secondary bank account. Must be ISO standard 3 character code. This will become the account to which proceeds of transactions are sent in split sweep functionality.

SecondaryBankAccount{

AccountName

String

32

Required

Required if adding secondary bank account info as part of the signup. This will become the account to which proceeds of transactions are sent in split sweep functionality.

SecondaryBankAccount{

BankAccountNumber

String

25

Required

Required if adding secondary bank account info as part of the signup. This will become the account to which proceeds of transactions are sent in split sweep functionality.

SecondaryBankAccount{

AccountOwnershipType

String

15

Required

Required if adding secondary account as part of the signup. Valid values are ‘Personal’ or ‘Business’ If accountType is G, then this value is always overwritten as ‘Business’ This will become the account to which proceeds of transactions are sent in split sweep functionality.

SecondaryBankAccount{

AccountType

String

1

Required

Required if adding secondary bank account info as part of the signup. Valid values are:

C – Checking, S – Savings , G – General Ledger

SecondaryBankAccount{

BankName

String

50

Required

Required if adding secondary bank account info as part of the signup. This will become the account to which proceeds of transactions are sent in split sweep functionality.

SecondaryBankAccount{

RoutingNumber

String

9

Required

Required if adding secondary bank account info as part of the signup, must be a valid Fedwire ACH participant routing number. This will become the account to which proceeds of transactions are sent in split sweep functionality.

 

Bank Account Ownership Details – Optional. Needed for Canadian merchants, to comply with banking rule. If missing in Canada, transfers fail.

XML Element

Type

Max

Required

Notes

BankAccountOwnerData{

PrimaryBankAccountOwner{

FirstName

String

25

Required

Required if adding ownership info.

BankAccountOwnerData{

PrimaryBankAccountOwner{

LastName

String

25

Required

Required if adding ownership info.

BankAccountOwnerData{

PrimaryBankAccountOwner{

Address1

String

50

Required

Required if adding ownership info.

BankAccountOwnerData{

PrimaryBankAccountOwner{

City

String

50

Required

Required if adding ownership info.

BankAccountOwnerData{

PrimaryBankAccountOwner{

StateProvince

String

3

Required

Required if adding ownership info. 2-3 character abbreviation.

BankAccountOwnerData{

PrimaryBankAccountOwner{

PostalCode

String

10

Required

Required if adding ownership info.

BankAccountOwnerData{

PrimaryBankAccountOwner{

Country

String

3

Required

Required if adding ownership info. 3 character ISO standard country abbreviation.

BankAccountOwnerData{

PrimaryBankAccountOwner{

Phone

String

25

Required

Required if adding ownership info.

 

Gross Billing Information – Optional. Used with prior approval to automatically bill fees to separate account

Element

Type

Max

Required

Notes

GrossBillingInformation{

GrossSettleAddress{

Address1

String

25

Optional

Gross Settle credit card billing address.

GrossBillingInformation{

GrossSettleAddress{

City

String

25

Optional

Gross Settle credit card billing address.

GrossBillingInformation{

GrossSettleAddress{

Country

String

3

Optional

Gross Settle credit card billing address. Must be 3 character ISO standard country code.

GrossBillingInformation{

GrossSettleAddress{

State

String

2

Optional

Gross Settle credit card billing address. Must be 2 character standard US State or Canadian province code.

GrossBillingInformation{

GrossSettleAddress{

Zip

String

9

Optional*

Gross Settle credit card billing address. For USA: 5 or 9 characters without dash. For CAN: 6 characters postal code with a space "XXX XXX" Do not use if not USA or CAN. *Required if payment method is a credit card.

GrossBillingInformation{

GrossSettleAddress{

CountryCode

String

3

Optional*

ISO standard 3 character country code. *Required if payment method is a bank account.

GrossBillingInformation{

GrossSettleBankAccount{

AccountName

String

 

Optional*

Bank account-holder’s name. *Required if payment method is a bank account.

GrossBillingInformation{

GrossSettleBankAccount{

AccountType

String

10

Optional*

*Required if Gross Settle billing info is bank account. Valid values are:

C – Checking, S – Savings

GrossBillingInformation{

GrossSettleBankAccount{

BankAccountNumber

String

25

Optional*

Bank account number. *Required if payment method is a bank account.

GrossBillingInformation{

GrossSettleBankAccount{

RoutingNumber

String

9

Optional*

Routing number of valid Fedwire ACH participant. *Required if payment method is a bank account.

GrossBillingInformation{

GrossSettleCardData{

CreditCardNumber

String

16

Optional*

Valid credit card number. *Required if payment method is a credit card.

GrossBillingInformation{

GrossSettleCardData{

ExpirationDate

String

4

Optional*

Credit card expiration date. *Required if payment method is a credit card.

GrossBillingInformation{

GrossSettleCardData{

NameOnCard

String

25

Optional*

Name on credit card. *Required if payment method is a credit card.

 

Merchant Beneficiary Owner Information – Required for all merchants validating KYC based off of personal data. Only certain types of merchants are exempt from this requirement.

 

Element

Type

Max

Required

Notes

BeneficialOwnerData{

OwnerCount

String

1

Required

Number of Beneficiary Owners, should be maximum 5.

BeneficialOwnerData{

Owners{

Owner{

Title

String

55

Optional

This field contains the Title.

BeneficialOwnerData{

Owners{

Owner{

FirstName

String

20

Required

Owner First Name.

BeneficialOwnerData{

Owners{

Owner{

LastName

String

25

Required

Owner Last Name.

BeneficialOwnerData{

Owners{

Owner{

Email

String

55

Required

Owner Email ID.

BeneficialOwnerData{

Owners{

Owner{

DateOfBirth

String

10

Required

Date of Birth of the Owner. Must be in ‘mm-dd-yyyy’ format.

BeneficialOwnerData{

Owners{

Owner{

Percentage

String

3

Required

Percentage for Owner. Percentage should be in between 0 and 100.

BeneficialOwnerData{

Owners{

Owner{

Address

String

100

Required

Street address where Owner resides. *Required if passing Merchant Beneficiary Owner Information.

BeneficialOwnerData{

Owners{

Owner{

SSN

String

9

Required

Social Security Number of the Owner. Should be 9 digits.

BeneficialOwnerData{

Owners{

Owner{

City

String

55

Required

The name of the city where the Owner resides.

BeneficialOwnerData{

Owners{

Owner{

Zip

String

10

Required

The postal code where the Owner resides.

BeneficialOwnerData{

Owners{

Owner{

State

String

3

Required

The region code that corresponds to the state where the Owner resides.

BeneficialOwnerData{

Owners{

Owner{

Country

String

3

Required

The three-character, alpha country code for where the Owner resides.

 

 

Significant Owner Information – May be required for some partners based on ProPay Risk decision

Element

Type

Max

Required

Notes

AuthorizedSigner{

FirstName

String

20

Required

Seller’s Authorized Signer First Name. By default Merchant’s First name is saved*.

AuthorizedSigner{

LastName

String

25

Required

Seller’s Authorized Signer Last Name. By default Merchant’s Last name is saved*.

AuthorizedSigner{

Title

String

20

 

Optional

This field contains the Seller’s Authorized Signer Title*. Commonly used Authorized Signer Titles include:

SignificantOwner{

FirstName

String

20

Required

For US: Seller’s Significant Owner First Name.

For CAN: Seller’s Significant Owner or Authorized Signer First Name.

SignificantOwner{

LastName

String

20

Required

For US: Seller’s Significant Owner Last Name.

For CAN: Seller’s Significant Owner or Authorized Signer Last Name.

SignificantOwner{

SSN

String

9

Required

Social Security Number of the Seller’s Significant Owner. Should be 9 digits.

SignificantOwner{

DateOfBirth

Date

 

Required

Date of Birth of the Seller’s Significant Owner. Must be in ‘mm-dd-yyyy’ format.

SignificantOwner{

Address1

String

40

Required

Street address where Seller’s Significant Owner resides.

SignificantOwner{

City

String

40

Required

The name of the city where the Seller’s Significant Owner resides.

SignificantOwner{

RegionCode

String

6

Required

The region code that corresponds to the state where the Seller’s Significant Owner resides.

SignificantOwner{

Zip

String

9

Required

The postal code for where the Seller's Significant Owner resides.

SignificantOwner{

CountryCode

String

2

Required

The two-character, alpha country code for where the Seller's Significant Owner resides.

SignificantOwner{

Title

String

50

Required

This field contains the Seller’s Significant Signer Title.

SignificantOwner{

Percentage

Byte

 

Required

Percentage for Significant Owner. Percentage should be in between 0 and 100.

 

Threat Risk Assessment Information – May be required based on ProPay Risk Decision

Element

Type

Max

Required

Notes

FraudDetectionData{

MerchantSourceIp

String

64

Required

SourceIp of Merchant, see ProPay Fraud Detection Solutions Manual.

FraudDetectionData{

ThreatMetrixPolicy

String

32

Required

Threat Metrix Policy, see ProPay Fraud Detection Solutions Manual.

FraudDetectionData{

ThreatMetrixSessionId

String

128

Required

SessionId for Threat Metrix, see ProPay Fraud Detection Solutions Manual.

Response Values

Element

Type

Notes

Status

String

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

Password

String

Temporary password

AccountNumber

Integer

Primary identifier for new ProPay account

Tier

String

Type of account created

How to call this method?

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

Example Response

 <XMLRequest>
 <username/>
 <sourceip/>
 <certStr>4d8c657a7bc64e31bce4fc37741abb</certStr>
 <termid>8a399ce744</termid>
 <class>partner</class>
 <XMLTrans>
  <transType>01</transType>
  <country>GBR</country>
  <sourceEmail>7b9885d2-1399-49f8-8614-67e346b6a7e2@qamail.com</sourceEmail>
  <firstName>Bill</firstName>
  <mInitial/>
  <lastName>Smith</lastName>
  <addr>Hong Alert Test Street 1</addr>
  <aptNum>111</aptNum>
  <city>Hong Alert City 1</city>
  <state/>
  <zip>84043</zip>
  <addressId/>
  <bldgNumber>501A</bldgNumber>
  <district>CA</district>
  <postTown>Lindon</postTown>
  <county>CA</county>
  <timeAtAddress>20</timeAtAddress>
  <prevBldgNumber>505A</prevBldgNumber>
  <prevAddr>PrevAddr</prevAddr>
  <prevAptNum>PrevAptNum</prevAptNum>
  <prevAddr3>PrevAddr3</prevAddr3>
  <prevCity>PrevCity</prevCity>
  <prevCounty>PrevCounty</prevCounty>
  <prevDistrict/>
  <prevPostTown>PrevPostTown</prevPostTown>
  <prevState>CA</prevState>
  <prevZip>1234 567</prevZip>
  <prevCountry>GBR</prevCountry>
  <dayPhone>8015551112</dayPhone>
  <evenPhone>8015551112</evenPhone>
  <ssn>333224445</ssn>
  <externalId/>
  <dob>01-01-1981</dob>
  <phonePin/>
  <ccName>Sylvester Stallone</ccName>
  <ccNum>4111111111111111</ccNum>
  <expDate>0624</expDate>
  <CVV2>999</CVV2>
  <password/>
  <acceptedTermsAndConditions>False</acceptedTermsAndConditions>
  <CurrencyCode>GBP</CurrencyCode>
  <paymentMethodId/>
  <userId/>
  <BankName>The Big Bank</BankName>
  <accountName>Test Merchant</accountName>
  <AccountNumber>111111111</AccountNumber>
  <RoutingNumber>111111</RoutingNumber>
  <accountType>C</accountType>
  <AccountOwnershipType>Personal</AccountOwnershipType>
  <SecondaryAccountName/>
  <SecondaryAccountType/>
  <SecondaryRoutingNumber/>
  <SecondaryAccountNumber/>
  <SecondaryBankName/>
  <SecondaryAccountOwnershipType/>
  <SecondaryAccountCountryCode/>
  <GrossSettleAddress/>
  <GrossSettleCity/>
  <GrossSettleState/>
  <GrossSettleZipCode/>
  <GrossSettleCountry/>
  <GrossSettleNameOnCard/>
  <GrossSettleCreditCardNumber/>
  <GrossSettleCreditCardExpDate/>
  <GrossSettleAccountType>Unknown</GrossSettleAccountType>
  <GrossSettleAccountCountryCode/>
  <GrossSettleRoutingNumber/>
  <GrossSettleAccountNumber/>
  <GrossSettleAccountHolderName/>
  <tier>6269fbaf-16f9-4ba0-8</tier>
  <EIN>584384656</EIN>
  <BusinessLegalName>Hong Alert Test Store 1</BusinessLegalName>
  <DoingBusinessAs>nomatch</DoingBusinessAs>
  <BusinessAddress>Test Street 1</BusinessAddress>
  <BusinessCity>Hong Alert City 1</BusinessCity>
  <BusinessState>UT</BusinessState>
  <BusinessZip>128901</BusinessZip>
  <BusinessCountry>GBR</BusinessCountry>
  <BusinessAddress2/>
  <BusinessRegistrationNumber>55555555</BusinessRegistrationNumber>
  <BusinessPhoneNumber>88888888888</BusinessPhoneNumber>
  <BusinessAddress3/>
  <BusinessDistrict/>
  <BusinessPostTown>Lindon</BusinessPostTown>
  <BusinessCounty>GBR</BusinessCounty>
  <TimeAtBusinessAddress>18</TimeAtBusinessAddress>
  <BusinessPreviousAddress>BusinessPreviousAddress</BusinessPreviousAddress>
  <BusinessPreviousAddress2>BusinessPreviousAddress2</BusinessPreviousAddress2>
  <BusinessPreviousAddress3>BusinessPreviousAddress3</BusinessPreviousAddress3>
  <BusinessPreviousCity>BusinessPreviousCity</BusinessPreviousCity>
  <BusinessPreviousCounty>BusinessPreviousCounty</BusinessPreviousCounty>
  <BusinessPreviousDistrict>BusinessPreviousDistrict</BusinessPreviousDistrict>
  <BusinessPreviousPostTown>BusinessPreviousPostTown</BusinessPreviousPostTown>
  <BusinessPreviousState>CA</BusinessPreviousState>
  <BusinessPreviousZip>1234567</BusinessPreviousZip>
  <BusinessPreviousCountry>GBR</BusinessPreviousCountry>
  <WebsiteURL/>
  <MerchantLegalName>Hong Alert Test Store 1</MerchantLegalName>
  <BusinessDesc/>
  <MonthlyBankCardVolume>0</MonthlyBankCardVolume>
  <AverageTicket>0</AverageTicket>
  <HighestTicket>0</HighestTicket>
  <mailApt/>
  <mailAddr/>
  <mailCity/>
  <mailState/>
  <mailZip/>
  <mailCountry/>
  <mailPostTown>Lindon</mailPostTown>
  <mailCounty>CA</mailCounty>
  <mailDistrict/>
  <MerchantSourceip>127.0.0.1</MerchantSourceip>
  <ThreatMetrixPolicy/>
  <ThreatMetrixSessionid/>
  <intlID/>
  <driversLicenseVersion/>
  <documentType/>
  <documentExpDate/>
  <documentIssuingState/>
  <medicareReferenceNumber/>
  <medicareCardColor/>
  <AuthorizedSignerFirstName/>
  <AuthorizedSignerLastName/>
  <AuthorizedSignerTitle/>
  <SignificantOwnerFirstName>Bill</SignificantOwnerFirstName>
  <SignificantOwnerLastName>Smitch</SignificantOwnerLastName>
  <SignificantOwnerSSN>759687533</SignificantOwnerSSN>
  <SignificantOwnerDateOfBirth>1981-01-01</SignificantOwnerDateOfBirth>
  <SignificantOwnerStreetAddress>Hong Alert Test Street 1</SignificantOwnerStreetAddress>
  <SignificantOwnerCityName>Hong Alert City 1</SignificantOwnerCityName>
  <SignificantOwnerRegionCode>UT</SignificantOwnerRegionCode>
  <SignificantOwnerPostalCode>84042</SignificantOwnerPostalCode>
  <SignificantOwnerCountryCode>US</SignificantOwnerCountryCode>
  <SignificantOwnerTitle>Owner</SignificantOwnerTitle>
  <SignificantOwnerPercentage>100</SignificantOwnerPercentage>
  <PaymentBankAccountNumber/>
  <PaymentBankRoutingNumber/>
  <PaymentBankAccountType/>
  <GrossSettlePropayAccountNumber/>
  <FulfillmentNotes/>
  <BusinessType>D</BusinessType>
  <Nationality>GBR</Nationality>
   <intlIDs>
    <intlID>
    <Type>2</Type>
    <ID>52657</ID>
    </intlID>
   <intlID>
    <Type>14</Type>
    <ID>89765242</ID>
    </intlID>
  </intlIDs>
  <BeneficialOwnerData>
   <OwnerCount>1</OwnerCount>
   <Owners>
    <Owner>
    <FirstName>Bill1</FirstName>
    < LastName>Smith1</LastName>
    <Title>Owner</Title>
    <Address>Hong Alert Test Street 1</Address>
    <Address2/>
    <Percentage>100</Percentage>
    <SSN>759687533</SSN>
    <Country>USA</Country>
    <State>UT</State> 
    <City>Hong Alert City 1</City>
    <Zip>84042</Zip>
    <Email>cdd830e7-2527-4846-bafe-21799a80fc86@qamail.com</Email>
    <DateOfBirth>1981-01-01</DateOfBirth>
    <BldgNumber>503A</BldgNumber>
    <District/>
    <PostTown>Lindon</PostTown>
    <County>CA</County>
    <Nationality>GBR</Nationality>
    </Owner>
   </Owners>
  </BeneficialOwnerData>
 </XMLTrans>
</XMLRequest>

<XMLResponse>
  <XMLTrans>
    <transType>01</transType>
    <status>00</status>
    <sourceEmail>John@Smith.com</sourceEmail>
    <password>!WTYSefRW3</password>
    <accntNum>123456</accntNum>
    <tier>Merchant</tier>
    <beneficialOwnerDataResult>
      <Owner>
        <FirstName>First1</FirstName>
        <LastName>Last1</LastName>
        <status>Validated</status>
        </Owner>
      </beneficialOwnerDataResult>
  </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 ProcessTransactionTransType01
 {
 public static void ProcessTransaction()
 {
 var processRequest = new XmlTransactionRequest { CertificationString = "YourCertStringGoesHere", TerminalID = "YourTermId", };
 var xmlTransaction = new XmlProcessTransaction
 {
 TransType = "01",
 firstName = "Tester",
 lastname = "Guy",
 dob = "04-12-1971",
 ssn = "000000000",
 sourceEmail = "testerguy@tester.com",
 dayPhone = "8013415300",
 evenPhone = "8013415300",
 addr = "3400 Ashton Blvd",
 city = "Lehi",
 state = "UT",
 zip = "84043",
 };
 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;
 var password = load.Descendants().First(p => p.Name.LocalName == "password").Value;
 var accntNum = load.Descendants().First(p => p.Name.LocalName == "accntNum").Value;
 var tier = load.Descendants().First(p => p.Name.LocalName == "tier").Value;
 }
 }

public class XmlProcessTransaction : XmlTransaction
 {
 [XmlElement("firstName")]
 public string firstName = string.Empty;
 [XmlElement("mInitial")]
 public string mInitial = string.Empty;
 [XmlElement("lastName")]
 public string lastName = string.Empty;
 [XmlElement("dob")]
 public string dob = string.Empty;
 [XmlElement("ssn")]
 public string ssn = string.Empty;
 [XmlElement("sourceEmail")]
 public string sourceEmail = string.Empty;
 [XmlElement("dayPhone")]
 public string dayPhone = string.Empty;
 [XmlElement("evenPhone")]
 public string evenPhone = string.Empty;
 [XmlElement("NotificationEmail")]
 public string NotificationEmail = string.Empty;
 [XmlElement("currencyCode")]
 public string currencyCode = string.Empty;
 [XmlElement("tier")]
 public string tier = string.Empty;
 [XmlElement("externalId")]
 public string externalId = string.Empty;
 [XmlElement("phonePin")]
 public string phonePin = string.Empty;
 [XmlElement("userId")]
 public string userId = string.Empty;
 [XmlElement("addr")]
 public string addr = string.Empty;
 [XmlElement("aptNum")]
 public string aptNum = string.Empty;
 [XmlElement("addr3")]
 public string addr3 = string.Empty;
 [XmlElement("city")]
 public string city = string.Empty;
 [XmlElement("state")]
 public string state = string.Empty;
 [XmlElement("zip")]
 public string zip = string.Empty;
 [XmlElement("country")]
 public string country = string.Empty;
 [XmlElement("BusinessLegalName")]
 public string BusinessLegalName = string.Empty;
 [XmlElement("DoingBusinessAs")]
 public string DoingBusinessAs = string.Empty;
 [XmlElement("EIN")]
 public string EIN = string.Empty;
 [XmlElement("MCCCode")]
 public string MCCCode = string.Empty;
 [XmlElement("WebsiteURL")]
 public string WebsiteURL = string.Empty;
 [XmlElement("BusinessDescription")]
 public string BusinessDescription = string.Empty;
 [XmlElement("MonthlyBankCardVolume")]
 public string MonthlyBankCardVolume = string.Empty;
 [XmlElement("AverageTicket")]
 public string AverageTicket = string.Empty;
 [XmlElement("HighestTicket")]
 public string HighestTicket = string.Empty;
 [XmlElement("BusinessAddress")]
 public string BusinessAddress = string.Empty;
 [XmlElement("BusinessAddress2")]
 public string BusinessAddress2 = string.Empty;
 [XmlElement("BusinessCity")]
 public string BusinessCity = string.Empty;
 [XmlElement("BusinessCountry")]
 public string BusinessCountry = string.Empty;
 [XmlElement("BusinessState")]
 public string BusinessZip = string.Empty;
 [XmlElement("BusinessZip")]
 public string BusinessZip = string.Empty;
 [XmlElement("NameOnCard")]
 public string NameOnCard = string.Empty;
 [XmlElement("ccNum")]
 public string ccNum = string.Empty;
 [XmlElement("expDate")]
 public string expDate = string.Empty;
 [XmlElement("mailAddr")]
 public string mailAddr = string.Empty;
 [XmlElement("mailApt")]
 public string mailApt = string.Empty;
 [XmlElement("mailAddr3")]
 public string mailAddr3 = string.Empty;
 [XmlElement("mailCity")]
 public string mailCity = string.Empty;
 [XmlElement("mailState")]
 public string mailState = string.Empty;
 [XmlElement("mailCountry")]
 public string mailCountry = string.Empty;
 [XmlElement("mailZip")]
 public string mailZip = string.Empty;
 [XmlElement("AccountCountryCode")]
 public string AccountCountryCode = string.Empty;
 [XmlElement("accountName")]
 public string accountName = string.Empty;
 [XmlElement("AccountNumber")]
 public string AccountNumber = string.Empty;
 [XmlElement("AccountOwnershipType")]
 public string AccountOwnershipType = string.Empty;
 [XmlElement("accountType")]
 public string accountType = string.Empty;
 [XmlElement("BankName")]
 public string BankName = string.Empty;
 [XmlElement("RoutingNumber")]
 public string RoutingNumber = string.Empty;
 [XmlElement("MerchantSourceIp")]
 public string MerchantSourceIp = string.Empty;
 [XmlElement("ThreatMetrixPolicy")]
 public string ThreatMetrixPolicy = string.Empty;
 [XmlElement("ThreatMetrixSessionId")]
 public string ThreatMetrixSessionId = 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', 01);
$simpleXML->XMLTrans->addChild('firstName', 'Test');
$simpleXML->XMLTrans->addChild('lastName', 'Guy');
$simpleXML->XMLTrans->addChild('dob', '04-12-1971');
$simpleXML->XMLTrans->addChild('ssn', '000000000');
$simpleXML->XMLTrans->addChild('sourceEmail', 'someone@somewhere.com');
$simpleXML->XMLTrans->addChild('dayPhone', '8013415300');
$simpleXML->XMLTrans->addChild('evenPhone', '8013415300');
$simpleXML->XMLTrans->addChild('addr', 'right here');
$simpleXML->XMLTrans->addChild('city', 'Lehi');
$simpleXML->XMLTrans->addChild('state', 'UT');
$simpleXML->XMLTrans->addChild('zip', '84043');

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

XML Element

Type

Max

Required

Notes

firstName

String

20

Required

Merchant/Individual first names.

mInitial

String

2

Optional

Merchant/Individual middle initial.

lastName

String

25

Required

Merchant/Individual last name.

dob

String

 

Required

Merchant/Individual Date of birth. Must be in ‘mm-dd-yyyy’ format. *Individual must be 18+ to obtain an account. The value 01-01-1981 will give a successful response. All others will return a Status 66 (Failed KYC).

ssn

String

9

Optional*

Merchant/Individual social security number. Must be 9 characters without dashes. *Required for USA when using personal validation. If business validated, do not pass!

sourceEmail

String

55

Required

Merchant/Individual email address. Must be unique in ProPay system. *ProPay’s system will send automated emails to the email address on file unless NotificationEmail is provided.

*Truncated, if value provided is greater than max value.

dayPhone

String

 

Required

Merchant/Individual day phone number. *For USA, CAN, NZL and AUS value must be 10 characters with no dashes

evenPhone

String

 

Required

Merchant/Individual evening phone number. *For USA, CAN, NZL and AUS value must be 10 characters with no dashes

NotificationEmail

String

55

Optional

Communication Email Address. *ProPay’s system will send automated emails to the email address on file rather than the Source Email. 

currencyCode

String

3

Optional*

Required to specify the currency in which funds should be held, if other than USD. An affiliation must be granted permission to create accounts in currencies other than USD. ISO 4217 standard 3 character currency code.

tier

String

 

Optional*

One of the previously assigned merchant tiers. *If not provided, will default to cheapest available tier.

externalId

String

20

Optional

This is a partner’s own unique identifier. Typically used as the distributor or consultant ID.

phonePin

String

4

Optional

Numeric value which will give a user access to ProPay’s IVR system. Can also be used to reset password.

userId

String

55

Optional

ProPay account username. Must be unique in ProPay system. *Username defaults to <sourceEmail> if userId is not provided.

IpSignup String 16 Optional Signup IP Address
USCitizen Boolean True / False Optional When marked true, the submerchant is attesting that they are a US citizen. (Value passed should be either true, false, or null) 
BOAttestation Boolean True / False Optional When marked true. the submerchant is attesting that there are no other individuals that have 20% ownership or a controlling interest in the entity that have not already been disclosed elsewhere in the application process. The partner is also attesting that a pop up or other message has been displayed to the submerchant to explain these requriements. (Value passed should be either true, false or null) 
TermsAcceptanceIP String 15 Optional The IP address of the device that was used to agree to ProPay's Terms and Conditions. (Maximum value should be accepted to 15 characters) 
TermsAcceptanceTimeStamp DateTime Date.Time.Now Optional The timestamp associated with the agreement to ProPay's Terms and Conditions
TermsVersion Numeric 1 Optional This refers to the version of our terms and conditions that was provided to the submerchant review and to which they are agreeing. (Valid Numeric values are 1-5
1 - Merchant US
2 - Payment US
3 - Merchant CA
4 - Merchant  UK
5 - Merchant AU ) 
nationality String 3 Optional This represents the country in which the merchant was born. ISO 3166 3 Digit alpha code applies. For example: GBR, USA, etc. *Mandatory for UK merchants
CultureCode String 11 Optional The culture code is used by the system to send notifications in a particular language.  The culture code is required for Canada accounts. Acceptable codes include: 
•    en-AU  -  English - Australia
•    en-CA  -  English - Canada
•    en-NZ  -  English - New Zealand
•    en-US  -  English - United States
•    es-MX  -  Spanish - Mexico
•    es-US  -  Spanish - United States
•    fr-CA  -  French - Canada
•    fr-FR  -  French - France
•    ja-JP  -  Japanese - Japan
•    ko-KR  -  Korean - Korea
•    pt-PT  -  Portuguese - Portugal
•    ru-RU  -  Russian - Russia
•    zh-CHS  -  Chinese (Simplified)
•    zh-Hans  -  Chinese

 

 

Personal Address - Required

XML Element

Type

Max

Required

Notes

addr

 

String

100

Required

Merchant/Individual physical street Address. PO Boxes are not allowed. *Mandatory for UK merchants

aptNum

String

100

Optional

Merchant/Individual physical Address. Use for 2nd Address Line

addr3

String

100

Optional

Merchant/Individual physical Address. * For UK Merchants, use to provide the building / home name. For example: Primrose Cottage

city

String

30

Required

Merchant/Individual physical Address city. * Mandatory for UK merchants

state

String

3

Required

Merchant/Individual physical Address state. *Standard 2 character abbreviation for state, province, prefecture, etc. *Does not apply to UK merchants

zip

 

String

 

Required

Merchant/Individual physical Address zip/postal code. For USA: 5 or 9 characters without dash. For CAN: 6 characters postal code with a space "XXX XXX" For AUS and NZ 4 character code. For the UK: 6-8 alphanumeric character postal code with a space. The first part is 2-4 digits. The second half is 3 digits. "yyyy-yyy". *Mandatory for UK merchants. 

country

 

String

3

Optional

ISO 3166 standard 3 character country codes. Required if creating an account in a country other than USA. *Country must be an approved country to create a ProPay account. USA territories should use 'USA'

addressId String 20 Optional This is a unique address identification number assigned to each address returned by Equifax. *The value for this tag is provided in the Address Lookup API response
bldgNumber String 50 Optional 3This is the building / home number fo rhte street address. For example: 501a Halfway Street. Value for this tag would be "501a". *Mandatory for UK merchants
district String 50 Optional The District associated with the merchant's address  * For use by UK merchants
postTown String 100 Optional The post town that is associated with the merchant's address.  *Mandatory for UK merchants
county String 50 Optional The county associated with the Merchant's address  *Mandatory for UK merchants
timeAtAddress String 3 Optional 3 The length of time the merchant has live din their current address, represented in whole months (ie. 5, 10, etc.).  *Mandatory for UK merchants

 

 

Personal Previous Address - Optional

XML Element

Type

Max

Required

Notes

prevBldNumber

 

String

50

Optional

This is the building / home nmber for the previous street address. For example 501a Halfway Street. Value for this tag would be 501a. *Mandatory for UK merchants if time in current address is less than 24 months.

prevAddr String 100 Optional  Merchant / Individual physical prevous strett address without the building / house number. For example: 501a Halfway street. Value for this tag would be Hlafway Street. PO Boxes are not allowed. Alphanumeric.  *Mandatory for UK merchants if time in current address is less than 24 months.
prevAptNum String 100 Optional Merchant / Individual pervious physical address. user for the 2nd address line.  *Mandatory for UK merchants if time in current address is less than 24 months.
prevAddr3 String 100 Optional Merchant / individual previous physical Address city.   *Mandatory for UK merchants if time in current address is less than 24 months.
prevCity String 30 Optional Merchant / Individual previous physical address city.  *Mandatory for UK merchants if time in current address is less than 24 months.
prevCounty String 50 Optional The county associated with the merchant's previous address  *Mandatory for UK merchants if time in current address is less than 24 months.
prevDistrict String 50 Optional   The District associated with the merchants previous address.  *For use by UK merchants
prevPostTown String 100 Optional The post town that is associated with the Merchant's previous address.  *Required for UK merchants if time in current address is less than 24 months.
prevState String 3 Optional merchant / Individual previou sphysical address state. Standard 2 character abbreviation for state, province, prefecture, etc.  *Does not apply to UK merchnts.
prevZip String 9 Optional merchant / individual previou sphysical sddress zip / postal code. For the USA: 5 or 9 characters withouta dash. For CAN: 6 character postal code wth a space "xxx xxx" For AUS and NZ: 4 character code. For the UK: 6-8 alphanumeric character postal code with a space. The first part is 2-4 digits. The second half is 3 digits "yyyy yyy".   *Required for UK merchants if time in current address less than 24 months. 
prevCountry String 3 Optional ISO 3166 standard 3 character country codes. Required if creating an account in a country other than the USA. *Country must be an approved country to create a ProPay account. US Territories should use 'USA'.  *Required for UK merchants if time in current address is less than 24 months. 

 

 

Business Data – Required for business validated accounts. May also be required for personal validated accounts by ProPay Risk Team

XML Element

Type

Max

Required

Notes

BusinessLegalName

String

255

Required

The legal name of the business as registered.

DoingBusinessAs

String

255

Required

This field can be used to provide DBA information on an account. ProPay accounts can be configured to display DBA on cc statements.

EIN

String

 

Required

Employer Identification Number can be added to a ProPay account.

MCCCode

String

4

Optional

Merchant Category Code

WebsiteURL

String

255

Required

The Business’ website URL

BusinessDesc

String

255

Optional

The Business’ description

MonthlyBankCardVolume

Int(64)

 

Required

The monthly volume of bank card transactions; Value representing the number of pennies in USD, or the number of [currency] without decimals. Defaults to $1000.00 if not sent

AverageTicket

Int(64)

 

Required

The average amount of an individual transaction; Value representing the number of pennies in USD, or the number of [currency] without decimals. Defaults to $300.00 if not sent.

HighestTicket

Int(64)

 

Required

The highest transaction amount; Value representing the number of pennies in USD, or the number of [currency] without decimals. Defaults to $300.00 if not sent. 

BusinessAddress

String

100

Required

Business Physical Address

BusinessAddress2

String

100

Optional

Business Physical Address

BusinessCity

String

30

Required

Business Physical Address City

BusinessCountry

String

 

Required

Must be ISO standard 3 character country code.

BusinessState

String

3

Required

If domestic signup this value MUST be one of the standard 2 character abbreviations. Rule also applies for Canadian signups. (Must be standard province abbreviation.)

BusinessZip

String

 

Required

For USA: 5 or 9 characters without dash. For CAN: 6 characters postal code with a space "XXX XXX". For AUS and NZ 4 character code.

BusinessType String 1 Optional Valid values are: 
Business Type Valid Value
C-Corp (Non-Publically Traded) D
C-Corp (Publically Traded) E
501c3 Non-Profit Organization F
Municipality or Govt. Org G
LLC (Non-publically traded) M
LLC (Publically traded) N
General Partnership Q
Publically Traded Partnership R
Sole Proprietorship S
American Express Reserved Indicator X
Limited Partnership P
BusinessRegistrationNumber String 50 Optional Company registration number *Mandatory for merchants outside the United States whose Business Type is a Limited Company
BusinessPhoneNumber String 15 Optional Business day phone number. *For USA, CAN, NZ, and AUS values must be 10 characters. For the UK, the value must be 11 characters. *Mandatory for UK merchants
BusinessAddress3 String 100 Optional Business Physical Address. *For UK merchants, use to provide the Building Name
BusinessDistrict String 50 Optional The District associated with the busines address *For use by UK merchants
BusinessPostTown String 100 Optional The post town that is associated with the business address. *Mandatory for UK merchants
BusinessCounty String 50 Optional The county associated with the business address. * Mandatory for UK merchants
timeAtBusinessAddress String 3 Optional The lengh of time the business has been at the current address represented in whole months (ie. 5, 10, etc.). *Required for UK merchants if business has been at current address less than 24 months
LegalAddress String 100 Optional Legal Address is the registered office Address wihch can differ from where the business is actually run. PO Boxes are not allowed, Alphanumeric. **Required for the UK**
LegalAddress2 String 100 Optional Legal physical address. PO Boxes are not allowed. Alphanumeric. **For the UK. Use to provide the FLat or Suite #. Ex. Flat B | Suite 103**
LegalAddress3 String 100 Optional Legal physical Address. PO Boxes are not allowed. Alphanumeric. **For the UK. Use to provide the Building Name**
LegalAddressCity String 30 Optional Legal Physical Address: City. **Required for the UK**
LegalAddressCounty String 50 Optional Legal Physical Address: County. **Required for the UK**
LegalAddressDistrict String 50 Optional Legal Physical Address: District. **For use in the UK**
LegalAddressPostTown String 100 Optional Legal Physical Address: Post Town.  **Required for the UK**
LegalAddressState String 3 Optional Legal Physical Address: State.  **Does not apply to the UK**
LegalAddressZip String 9 Optional Legal Physical Address: Zip Code. For USA: 5 or 9 characters without dash. For CAN: 6 Character postal code with a space "XXX XXX"  For AUS and NZ 4 character code. For the UK: Zip Code is 6 - 8 characters in length with the first character being Alphabetic: A9 9AA (6 character), A99 9AA (7 character), AA9A 9AA (8 character). **Required for UK merchants if the Merchant has been at the current busines address less than 24 months**
LegalAddressCountry String 3 Optional Must be ISO standard 3 character country code. **Required for the UK**

 

 

Business Previous Address

XML Element

Type

Max

Required

Notes

business Previous Address String 100 Optional Business physical Address. PO Boxes are not allowed. Alphanumeric *Required for UK merchants if the merchant has been at current business address less than 24 months
businessPreviousAddress2 String 100 Optional Business Physical Address. PO Boxes are not allowed. Alphanumeric
businessPreviousAddress3 String 100 Optional Business Physical Address. PO Boxes are not allowed. Alphanumeric *For UK Merchants, use to provide the Buliding Name
businessPreviousCity String 30 Optional Business Physical Address: City. *Required for UK Merchants if Merchant has been at the current business address less than 24 months. 
businessPreviousCounty String 50 Optional business PrevoiusCounty. *Required for UK Merchants if Merchant has been at the current business address less than 24 months. 
businessPreviousDistrict String 50 Optional The District associated with the busnies previous address. *For use by UK merchants
businessPreviousPostTown String 100 Optional The post town that is associated with the business previou saddress. *Required for UK Merchants if Merchant has been at the current business address less than 24 months. 
businessPreviousState String 3 Optional business Physical Address: State. Standard 2 character abbreviation for state, province, prefecture, etc. *Does not apply to UK merchants
businessPreviousZip String 9 Optional Business physical address zip/postal code. For the USA: 5 or 9 characters without a dash. For CAN: 6 character postal code with a space "XXX XXX". For AUS and NZ: 4 character code. For the UK: 6-8 alphanumeric character postal code with a space. The first part is 2-4 digits. The second half is 3 digits "YYYY YYY" *Required for UK merchants if merchant has been at current business address less than 24 months
businessPreviousCounty String 3 Optional Must be ISO standard 3 character country code. *Required for UK Merchants if Merchant has been at the current business address less than 24 months. 

 

International Signup Data – Frequently Required for partners who sign up international merchants

XML Element

Type

Max

Required

Notes

documentType

String

1

Optional*

Values 1( Driver’s license), 2(Passport), 3( Australia Medicare)

intlID

String

 

Optional*

Corresponds to the document number provided by DocumentType.

documentExpDate

String

 

Optional*

Corresponds to the Expiry date of the document provided by DocumentType. Should be a valid date.

documentIssuingState

String

 

Optional*

Required if the DocumentType is 1 (Driver’s license). The driver’s license issuing state.

driversLicenseVersion

String

 

Optional*

Required if the DocumentType is 1 (Driver’s license) and Country is NZL. This is driver’s license version number.

medicareReferenceNumber

String

 

Optional*

Required if the DocumentType is 3 (Australia Medicare) and Country is AUS. The data should be parsed to Number.

medicareCardColor

String

 

Optional*

Required if the DocumentType is 3 (Australia Medicare) and Country is AUS.

 

 

Account Payment (Credit Card) Information – A payment method is required if account fee not paid for by partner

XML Element

Type

Max

Required

Notes

NameOnCard

String

 

Required

Card holder’s name as it appears on card.

ccNum

String

16

Required

Must pass Luhn check. Used to pay for an account if ProPay has not set account type up as free to users.

expDate

String

4

Required

Used to pay for an account if ProPay has not set account type up as free to users. Submitted as mmyy.

 

 

Account Payment (ACH) Information – A payment method is required if account fee not paid for by partner

XML Element

Type

Max

Required

Notes

PaymentBankAccountNumber

String

 

Required

Used to pay for an account via ACH and monthly renewal. Financial institution account number.

PaymentBankRoutingNumber

String

 

Required

Used to pay for an account via ACH and monthly renewal. Financial institution routing number. Must be a valid ACH routing number.

PaymentBankAccountType

String

 

Required

Used to pay for an account via ACH and monthly renewal. Valid values are: Checking, Savings, and GeneralLedger

 

 

Account Payment (ProtectPay) Information – A payment method is required if account fee not paid for by partner

XML Element

Type

Max

Required

Notes

paymentMethodId

String

 

Required

Used to pay for an account via a ProtectPay Payment Method ID. Valid value is a GUID.

 

 

Mailing Address – Optional. Used if mailed correspondence from Propay should be sent to separate address

XML Element

Type

Max

Required

Notes

mailAddr

String

100

Optional

Merchant/Individual mailing address if different than physical address.

mailApt

String

 

Optional

Merchant/Individual mailing address if different than physical address.

mailAddr3

String

100

Optional

Merchant/Individual mailing address if different than physical address. *For UK merchants, use to provide the Building / Home Name. For example: Primrose Cottage

mailCity

String

30

Optional

Merchant/Individual mailing city if different than physical address.

mailState

String

3

Optional

Merchant/Individual mailing state if different than physical address. *Standard 2 character abbreviation for state, province, prefecture, etc.

mailCountry

String

3

Optional

ISO 3166 standard 3 character country codes. Required if creating an account in a country other than USA.

mailZip

String

 

Optional

Merchant/Individual mailing zip/postal code if different than physical address. For USA: 5 or 9 characters without dash. For CAN: 6 characters postal code with a space "XXX XXX" For AUS and NZ 4 character code.

mailDistrict String 50 Optional The District associated with the mailing address. *For use by UK merchants
mailPostTown String 100 Optional The Post Town associated with the mailing address. *For use by UK merchants
mailCounty String 50 Optional The county associated with the mailing address. *For use by UK merchants 

 

 

Primary Bank Account Information – Optional. Used to add a bank account to which funds can be settled

XML Element

Type

Max

Required

Notes

AccountCountryCode

String

3

Required

ISO 3166 standard 3-character country code.

accountName

String

32

Required

Merchant/Individual Name.

AccountNumber

String

25

Required

Financial institution account number.

AccountOwnershipType

String

15

Required

Valid values are: Personal and Business

accountType

String

1

Required

Valid values are:

C – Checking, S – Savings , G – General Ledger

BankName

String

50

Required

Name of financial institution.

RoutingNumber

String

9

Required

Financial institution routing number. Must be a valid ACH routing number. *For UK merchants, use the 6 diget bank sort code (xx-xx-xx or xxxxxx)

 

 

Secondary Bank Account Information – Optional. Used to add an account from which fees are pulled. Only works when Primary bank added

XML Element

Type

Max

Required

Notes

SecondaryAccountCountryCode

String

3

Required

Required if adding secondary bank account. Must be ISO standard 3 character code. This will become the account to which proceeds of transactions are sent in split sweep functionality.

SecondaryAccountName

String

32

Required

Required if adding secondary bank account info as part of the signup. This will become the account to which proceeds of transactions are sent in split sweep functionality.

SecondaryAccountNumber

String

25

Required

Required if adding secondary bank account info as part of the signup. This will become the account to which proceeds of transactions are sent in split sweep functionality.

SecondaryAccountOwnershipType

String

15

Required

Required if adding secondary account as part of the signup. Valid values are ‘Personal’ or ‘Business’ If accountType is G, then this value is always overwritten as ‘Business’ This will become the account to which proceeds of transactions are sent in split sweep functionality.

SecondaryAccountType

String

1

Required

Required if adding secondary bank account info as part of the signup. Valid values are:

C – Checking, S – Savings , G – General Ledger

SecondaryBankName

String

50

Required

Required if adding secondary bank account info as part of the signup. This will become the account to which proceeds of transactions are sent in split sweep functionality.

SecondaryRoutingNumber

String

9

Required

Required if adding secondary bank account info as part of the signup, must be a valid Fedwire ACH participant routing number. This will become the account to which proceeds of transactions are sent in split sweep functionality.

 

 

Bank Account Ownership Information – Optional. Transfers out of ProPay account won’t work without this information when bank outside US.

XML Element

Type

Max

Required

Notes

BankaccountOwnerData

.PrimaryBankAccountOwnerData

.FirstName

String

25

Required

Bank account owner’s first name

BankaccountOwnerData

.PrimaryBankAccountOwnerData

.LastName

String

25

Required

Bank account owner’s last name

BankaccountOwnerData

.PrimaryBankAccountOwnerData

.Address1

String

25

Required

Bank account owner’s address

BankaccountOwnerData

.PrimaryBankAccountOwnerData

.Address2

String

25

Required

Bank account owner’s address

BankaccountOwnerData

.PrimaryBankAccountOwnerData

.City

String

25

Required

Bank account owner’s address

BankaccountOwnerData

.PrimaryBankAccountOwnerData

.StateProvince

String

25

Required

Bank account owner’s address

BankaccountOwnerData

.PrimaryBankAccountOwnerData

.PostalCode

String

25

Required

Bank account owner’s address

 

 

Gross Billing Information – Optional. Used with prior approval to automatically bill fees to separate account

XML Element

Type

Max

Required

Notes

GrossSettleAddress

String

25

Optional

Gross Settle credit card billing address.

GrossSettleCity

String

25

Optional

Gross Settle credit card billing address.

GrossSettleCountry

String

3

Optional

Gross Settle credit card billing address. Must be 3 character ISO standard country code.

GrossSettleState

String

2

Optional

Gross Settle credit card billing address. Must be 2 character standard US State or Canadian province code.

GrossSettleZipCode

String

9

Optional*

Gross Settle credit card billing address. For USA: 5 or 9 characters without dash. For CAN: 6 characters postal code with a space "XXX XXX" Do not use if not USA or CAN. *Required if payment method is a credit card.

GrossSettleAccountCountryCode

String

3

Optional*

ISO standard 3 character country code. *Required if payment method is a bank account.

GrossSettleAccountHolderName

String

 

Optional*

Bank account-holder’s name. *Required if payment method is a bank account.

GrossSettleAccountType

String

10

Optional*

*Required if Gross Settle billing info is bank account. Valid values are:

C – Checking, S – Savings

GrossSettleAccountNumber

String

25

Optional*

Bank account number. *Required if payment method is a bank account.

GrossSettleRoutingNumber

String

9

Optional*

Routing number of valid Fedwire ACH participant. *Required if payment method is a bank account.

GrossSettleCreditCardNumber

String

16

Optional*

Valid credit card number. *Required if payment method is a credit card.

GrossSettleCreditCardExpDate

String

4

Optional*

Credit card expiration date. *Required if payment method is a credit card.

GrossSettleNameOnCard

String

25

Optional*

Name on credit card. *Required if payment method is a credit card.

 

 

Devices - Optional. Used for Portico device ordering.

XML Element

Type

Max

Required

Notes

Name String 20 Required Unique name of the device being ordered.
Quantity String 2 Required Number of devices ordered. Defaults to 0.
Attributes     Optional Parent tag for specifying special attributes for an individual device
Attributes.Item     Optional Specify an attribure Item
Attributes.Item["Name"] String 20 Required Name of the attribute item. E.g. "Heartland.AMD.OfficeKey" which is specific to boarding Portico devices for AMD through Heartland, or "Canada.CP.Language" which is specific to Canadian submerchants and passed to EzPOS for device ordering. 
Attributes.Item["Value"] String 20 Required

Value of the attribte item. In the above example, the value of "Heartland.AMD.OfficeKey" or the value of "Canada.CP.language" being either "en" or "fr". 
E.g.

<Attributes>
<ItemName="Canada.CP.Language" Value="en"/>
</Attributes>

 

 

Time Zone - Required for partners ordering Heartland Portico and Canada Portico devices. 

XML Element

Type

Max

Required

Notes

TimeZone

String

5

Optional

Must be one of the following TimeZone abbreviations. **Only canadian time zones are valid for Canada devices.** 

  • UTC   Universal Time Coordinated
  • PT      Pacific Time (US)  (UTC08/7DST) **CA time zone
  • MST    Arizona (Mountain Standard Time [US]) (UTC-7) **CA time zone
  • MT      Mountain Time (US) (UTC-7/6DST) **CA time zone
  • CT      Central Time (US) (UTC-6/5DST) **CA time zone
  • ET       Eastern Time  (US) (UTC-5/4DST) **CA time zone
  • HST     Hawaii Standard TIme (UTC-10)
  • AT       Atlantic Time (UTC-4/4DST)  **CA time zone
  • AST     Puerto Rico (Atlantic Standard Time) (UTC-4) 
  • AKST   Alaska  (Alaskan Standard Time) (UTC -9) 
  • ECT    European Central Time (UTC-1)
  • EET     Eastern European Time  (UTC-2) 
  • EAT    Eastern African Time (UTC-3)
  • MET    Middle East Time (UTC-3.30)
  • NET     Near East Time (UTC-4) 
  • PLT      Pakistan Lahore Time (UTC-5)
  • IST       Indian Standard Time (UTC-5.30)
  • BST      Bangaldesh Standard Time (UTC-6)
  • VST     Vietnam Standard Time  (UTC-7) 
  • CTT     China Taiwan Time (UTC-8) 
  • JST      Japan Standard Time (UTC-9)
  • ACT     Australia Central Time (UTC-9.30)
  • AET     Australia Eastern Time (UTC-10)
  • SST      Solomon Standard TIme (UTC-11) 
  • NST      New Zealand Standard Time (UTC-12) 
  • MIT      Midway Islands Time (UTC-11) 
  • CNT     Canadian Newfoundland Time (UTC-3.30) **CA time zone
  • AGT     Argentina standard Time (UTC-3) 
  • CAT     Central African Time (UTC-1) 


 

Merchant Beneficiary Owner Information – May be required for some partners based on ProPay Risk decision

XML Element

Type

Max

Required

Notes

OwnerCount

String

1

Required

Number of Beneficiary Owners, should be maximum 5.

Title

String

55

Optional

This field contains the Title.

FirstName

String

20

Required

Owner First Name.

LastName

String

25

Required

Owner Last Name.

Email

String

55

Required

Owner Email ID.

DateOfBirth

String

10

Required

Date of Birth of the Owner. Must be in ‘mm-dd-yyyy’ format.

Percentage

String

3

Required

Percentage for Owner. Percentage should be in between 0 and 100.

Address

String

100

Required

Street address where Owner resides. *Required if passing Merchant Beneficiary Owner Information.

Address2 String 100 Optional Street address where owner resides. *For UK merchants, use this for the Apt or flat number. For example APT 102 | Flat A

SSN

String

9

Required

Social Security Number of the Owner. Should be 9 digits. * Does not apply to UK merchants

City

String

55

Required

The name of the city where the Owner resides.

Zip

String

10

Required

The postal code where the Owner resides. For the UK:6-8 alphanumeric character postal code with a space. The first part is 2-4 digits. The second half is 3 digits. "YYYY YYY"

State

String

3

Required

The region code that corresponds to the state where the Owner resides.

Country

String

3

Required

The three-character, alpha country code for where the Owner resides.

bldgNumber String 50 Optional This is the building / home number for the street address. For example: 501a Halfway Street. Value for this tag would be 501a
*Mandatory for UK merchants
district String 50 Optional The District associated with the address *For use by UK merchants
postTown String 100 Optional The Post town associated with the address  *Mandatory for UK merchants
county String 50 Optional The county associated with the address  *Mandatory for UK merchants
nationality String 3 Optional This represents the country in which the merchant was born. ISO 3166 3 Digit Alpha code applies. For example: GBR, USA, etc.  *Mandatory for UK merchants

 

 

Significant Owner Information – May be required for some partners based on ProPay Risk decision

XML Element

Type

Max

Required

Notes

AuthorizedSignerFirstName

String

20

Required

Seller’s Authorized Signer First Name. By default Merchant’s First name is saved*.

AuthorizedSignerLastName

String

25

Required

Seller’s Authorized Signer Last Name. By default Merchant’s Last name is saved*.

AuthorizedSignerTitle

String

20

 

Optional

This field contains the Seller’s Authorized Signer Title*. Commonly used Authorized Signer Titles include:

SignificantOwnerFirstName

String

20

Required

For US: Seller’s Significant Owner First Name.

For CAN: Seller’s Significant Owner or Authorized Signer First Name.

SignificantOwnerLastName

String

20

Required

For US: Seller’s Significant Owner Last Name.

For CAN: Seller’s Significant Owner or Authorized Signer Last Name.

SignificantOwnerSSN

String

9

Required

Social Security Number of the Seller’s Significant Owner. Should be 9 digits.

SignificantOwnerDateOfBirth

Date

 

Required

Date of Birth of the Seller’s Significant Owner. Must be in ‘mm-dd-yyyy’ format.

SignificantOwnerStreetAddress

String

40

Required

Street address where Seller’s Significant Owner resides.

SignificantOwnerCityName

String

40

Required

The name of the city where the Seller’s Significant Owner resides.

SignificantOwnerCityName

String

40

Required

The name of the city where the Seller’s Significant Owner resides.

SignificantOwnerRegionCode

String

6

Required

The region code that corresponds to the state where the Seller’s Significant Owner resides.

SignificantOwnerPostalCode

String

9

Required

The postal code for where the Seller's Significant Owner resides.

SignificantOwnerCountryCode

String

2

Required

The two-character, alpha country code for where the Seller's Significant Owner resides.

SignificantOwnerTitle

String

50

Required

This field contains the Seller’s Significant Signer Title.

SignificantOwnerPercentage

Byte

 

Required

Percentage for Significant Owner. Percentage should be in between 0 and 100.

 

 

Threat Risk Assessment Information – May be required based on ProPay Risk Decision

XML Element

Type

Max

Required

Notes

MerchantSourceIp

String

64

Required

SourceIp of Merchant, see ProPay Fraud Detection Solutions Manual.

ThreatMetrixPolicy

String

32

Required

Threat Metrix Policy, see ProPay Fraud Detection Solutions Manual.

ThreatMetrixSessionId

String

128

Required

SessionId for Threat Metrix, see ProPay Fraud Detection Solutions Manual.

 

 

SoundPayment - Required for Transit Devices

XML Element

Type

Max

Required

Notes

SoundPaymentsSettingsPwd String   Required Used for sound payment password settings
SoundPaymentsUsername String   Required Used for sound payment user name
SoundPaymentsPwd String   Required Used for sound payment password
SoundPaymentsTerminalId String   Required Used for sound payment terminal
SoundPaymentsPosId String   Required Used for sound paymentposid

SoundPaymentsPosId

String

 

Required

Used for sound payment token

 

 

Required for Transit, Canada Portico, and UK Portico Devices

XML Element

Type

Max

Required

Notes

PostbackUrl

String

 

Required

This is used to pass back the Card Not Present Credentials

PostbackUrl2     Optoinal Thisis used to pass back the Card Present credentials
FulfilmentNotes     Required This field is added in to the business info element

 

Response Values

Element

Type

Conditional

Notes

transType

String

No

Will always return as 01.

status

String

No

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

password

String

No

Temporary password

accntNum

Integer

No

Primary identifier for new ProPay account

tier

String

No

Type of account created

transit XML Element Portico / transit Tier When the transaciton is a success the property inside will be filled with data from GP API, when the transaction is a failure, the properties will be empty and the status will be different. Check code responses for code result
transNum String Portico / transit Tier This is the transactionInfoId of the charged transaction.
Name String Portico / transit Tier The name of hte device that was ordered.
Price String Portico / transit Tier This is the unit price for the device that was ordered
Quantity String Portico / transit Tier This is the quantity of devices that were ordered, this should match the requested quantity.
TotalAmount String Portico / transit Tier This is the total amount that was charged to the credit card.
CurrencyCode String Portico / transit Tier This is the currency that the Price and TotalAmount are represented.
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