Payment API

Commissions

Payment Facilitator

Merchant Account Signups

DOWNLOAD

Unique Email Constraint

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:

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 Boarding Fraud Monitoring: ProPay may require additional fraud monitoring while boarding new merchants. ProPay's merchant boarding API supports ThreatMetrix® application monitoring. This works by including the "Merchant Threat Risk Assessment Information" elements in the API method to board a merchant as well as passing a Profiling Tag on your boarding UI. Learn how to Pass a Profiling Tag.

NOTESpecial Signup Information for Partners who use 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.

How to call this method:

You should submit a post of XML data to the following URL

HTTP URL(s)
HTTP Verb PUT
HTTP Header Authorization
Example Request
Example Response

How to call this method:

You should submit a post of XML data to the following URL

HTTP URL(s)
HTTP Verb POST
Authentication
Example Request
Example Response
Method Implementation
Method Implementation
Method Implementation
Dependencies
Method Implementation Header
Method Implementation
Request Submission
Method Implementation
Request Submission
Method Implementation
Request Submission
Method Implementation
Request Submission
Method Implementation
Request Submission
Basic Account Information
NOTE Required, unless noted, for all transactions of this type.
Element Type Max Required Notes
tier String 55 Required* One of the previously assigned merchant tiers.
*If not provided, will default to cheapest available tier.
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.
externalId String 20 Optional This is a client'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. Also used to reset password.
userId String 55 Optional ProPay account username. Must be unique in ProPay system.
*Username defaults to Merchant/Individual email if userId is not provided.
addr String 100 Required Merchant/Individual physical street Address. PO Boxes are not allowed.
city String 30 Required Merchant/Individual physical Address city.
dayPhone String Required Merchant/Individual day phone number.
*For USA and CAN, value must be 10 characters with no dashes
dob String Required Merchant/Individual Date of birth. Must be in 'mm-dd-yyyy' format.
*Individual must be 18+ to obtain an account.
evenPhone String Required Merchant/Individual evening phone number.
*For USA and CAN, value must be 10 characters with no dashes
firstName String 20 Required Merchant/Individual first names.
lastName String 25 Required Merchant/Individual last name.
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 Notification Email is specified.
*Truncated, if value provided is greater than max value.
ssn String Required Merchant/Individual social security number. Must be 9 characters without dashes.
*Required for USA.
state String 3 Required Merchant/Individual physical Address state.
*Standard 2 character abbreviation for state, province, prefecture, etc.
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"
addr3 String 100 Optional Merchant/Individual physical Address.
aptNum String 100 Optional Merchant/Individual physical Address. Use for 2nd Address Line
country String 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.
mailAddr String 100 Optional Merchant/Individual mailing address if different than physical address.
mailAddr3 String 100 Optional Merchant/Individual mailing address if different than physical address.
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.
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"
mInitial String 2 Optional Merchant/Individual middle initial.
NotificationEmail String 55 Optional Merchant/Individual email address.
*ProPay's system will send automated emails to the email address on file.
Data from ProPay, Inc PCI documentation.
Merchant Threat Risk Assessment Information
NOTE Required for usage of Threat Assessment.
Element Type Max Required Notes
MerchantSourceIp String 64 Required Source of Merchant, see ProPay Fraud Detection Solutions Manual.
ThreatMetrixPolicy String 32 Required Threat Metrix Policy, see ProPay Fraud Detection Solutions Manual.
*Threat Metrix Only
ThreatMetrixSessionId String 128 Required SessionId for Threat Metrix, see ProPay Fraud Detection Solutions Manual.
*Threat Metrix Only
Data from ProPay, Inc PCI documentation.
Primary Bank Account Information
NOTE Required, unless noted, if adding Personal Bank Account information.
Element Type Max Required Notes
AccountCountryCode String 3 Required ISO standard 3 character country code for a foreign currency transaction.
accountName String 32 Required Merchant/Individual Name
AccountNumber String 25 Required Financial institution account number
AccountOwnershipType String 15 Required Valid values are:
  • Personal
  • Business

* If accountType is G, then this value is always overwritten as '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
Description String 50 Optional Merchant/Individual description of account
Data from ProPay, Inc PCI documentation.
Merchant Business Information
NOTE Required, unless noted, for Merchant Accounts.
Element Type Max Required Notes
AuthorizedSignerFirstName String 20 Best Practice Seller's Authorized Signer First Name. By default Merchant's First name is saved*.
AuthorizedSignerLastName String 25 Best Practice 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:
Owner President
Vice President
Treasurer
Controller or Comptroller
CEO or CFO
Chairman
General
Manager
Partner
Co-owner
Director
Office Manager
AverageTicket Int(64) Signed Int(64) Best Practice 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.
BusinessAddress String 100 Best Practice Business Physical Address
BusinessAddress2 String 100 Optional Business Physical Address
BusinessLegalName String 255 Best Practice The legal name of the business as registered.
BusinessCity String 30 Best Practice Business Physical Address City
BusinessCountry String Best Practice Must be ISO standard 3 character country code.
BusinessDescription String 255 Best Practice The Business' description
BusinessState String 3 Best Practice 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 Best Practice For USA: 5 or 9 characters without dash. For CAN: 6 characters postal code with a space "XXX XXX"
DoingBusinessAs String 255 Best Practice 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 Best Practice Employer Identification Number can be added to a ProPay account.
HighestTicket Int(64) Signed Int(64) Best Practice 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.
MCCCode String 4 Optional Merchant Category Code
MonthlyBankCardVolume Int(64) Signed Int(64) Best Practice 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
SignificantOwnerFirstName String 20 Optional For US: Seller's Significant Owner First Name.
For CAN: Seller's Significant Owner or Authorized Signer First Name.
SignificantOwnerLastName String 20 Optional For US: Seller's Significant Owner Last Name.
For CAN: Seller's Significant Owner or Authorized Signer Last Name.
SignificantOwnerSSN String 9 Optional Social Security Number of the Seller's Significant Owner. Should be 9 digits.
SignificantOwnerDateOfBirth Date Optional Date of Birth of the Seller's Significant Owner. Must be in ‘mm-dd-yyyy' format.
SignificantOwnerStreetAddress String 40 Optional Street address where Seller's Significant Owner resides.
SignificantOwnerCityName String 40 Optional The name of the city where the Seller's Significant Owner resides.
SignificantOwnerRegionCode String 6 Optional The region code that corresponds to the state where the Seller's Significant Owner resides.
SignificantOwnerPostalCode String 9 Optional The postal code for where the Seller's Significant Owner resides.
SignificantOwnerCountryCode String 2 Optional The two-character, alpha country code for where the Seller's Significant Owner resides.
SignificantOwnerTitl String 50 Optional This field contains the Seller's Significant Signer Title.
SignificantOwnerPercentage Byte Optional Percentage for Significant Owner. Percentage should be in between 0 and 100.
WebsiteURL String 255 Best Practice The Business' website URL
Data from ProPay, Inc PCI documentation.
Account Payment Information
NOTE Required, unless noted, for account payment.
Element Type Max Required Notes
ccNum String 16 Optional 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 Optional Used to pay for an account if ProPay has not set account type up as free to users. Submitted as mmyy
paymentMethodId String Optional Used to pay for an account via a ProtectPay Payment Method ID. Valid value is a GUID
PaymentBankAccountNumber String Optional Used to pay for an account via ACH and monthly renewal. Financial institution account number
PaymentBankRoutingNumber String Optional Used to pay for an account via ACH and monthly renewal. Financial institution routing number.
*Must be a valid ACH routing number.
PaymentBankAccountType String Optional Used to pay for an account via ACH and monthly renewal. Valid values are:
  • Checking
  • Savings
  • GeneralLedger
* If an account is set to be paid for by the individual user, either this information must be passed, or the account holder must log into the ProPay website to pay for the account before it will be fully functional.
Data from ProPay, Inc PCI documentation.
Response Values
NOTE Required for Gross Billing features, with prior approval.
Element Type Notes
status String Result of the transaction request.
See ProPay API Appendix for result code definitions.
accntNum Integer Assigned to each account by ProPay.
password String Temporary password. Will need to be charged on first login.
sourceEmail String Email address used for signup.
tier String Type of ProPay account provided to user.
Data from ProPay, Inc PCI documentation.