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.

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. Click here to learn how this is done.

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
Versions: | |
Method Implementation
Versions: |
Method Implementation
Versions: | |
Method Implementation
Dependencies
Versions: | |
Method Implementation Header
Method Implementation
Request Submission
Versions: | |
Method Implementation
Request Submission
Versions: |
Method Implementation
Request Submission
Versions:
Method Implementation
Request Submission
Version:
Method Implementation
Request Submission
Account Information
NOTE Required, unless noted, for all transactions of this type.
Element Type Max Required Notes
tier String Required One of the previously assigned account types.
*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 grant permission to create accounts in currencies other than USD. If omitted, system will create accounts that hold money in 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.
intlID String Optional Omit unless specially instructed by ProPay.
phonePin String 4 Optional Numeric value which will five 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
Data from ProPay, Inc PCI documentation.
Account Identification Information
NOTE Required, unless noted, for all transactions of this type.
Element Type Max Required Notes
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 names.
sourceEmail String 55 Required Merchant/Individual email address. Must be unique in ProPay system.
*ProPay's system will send automated emails to the address on file.
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 to 9 characters without dash. For CAN: 6 characters postal code.
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.
*Country must have an approved country to create a ProPay account, see Appendix C
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.
mInitial String 2 Optional Merchant/Individual middle initial.
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 SourceIp of Merchant, see Appendix C for additional information.
*Legacy XML Only
ThreatMetrixPolicy String 32 Required Threat Metrix Policy, see Appendix C for additional information.
*Threat Metrix Only
*Legacy XML Only
ThreatMetrixSessionId String 128 Required SessionId for Threat Metrix, see Appendix C for additional information.
*Threat Metrix Only
*Legacy XML 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 50 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
BusinessAddress String 100 Required Business Physical Address
BusinessAddress2 String 100 Optional Business Physical Address
BusinessLegalName String 255 Optional The legal name of the business as registered.
NOTE * May be required by ProPay Risk team.
BusinessCountry String Required See Appendix B for possible country codes.
BusinessState String 3 Required If domestic signup this value MUST be one of the standard w character abbreviations. Rule also applies for Canadian signups. (Must be standard province abbreviation.)
BusinessZip String Required If domestic signup this value MUST be either 5 or 9 characters with no dash. For Canada this value MUST be 6 characters.
DoingBusinessAs String 255 Optional This field can be used to provide DBA information on an account. ProPay accounts can be configured to display DBA on cc statements.
NOTE * May be required by ProPay Risk team.
EIN String Optional Employer Identification Number can be added to a ProPay account.
MCCCode String 4 Optional Merchant Category Code
Data from ProPay, Inc PCI documentation.
Merchant Gross Billing Information
NOTE Required for Gross Billing feature, with prior approval.
Element Type Max Required Notes
GrossSettleAccountCountryCode String 3 Required Required if Gross Settle billing info is bank account. Must be ISO standard 3 character country code.
GrossSettleAccountHolderName Required Required if Gross Settle billing info is bank account. The Gross Settle billing bank account holder name.
GrossSettleAccountNumber String 10 Required Required if Gross Settle billing info is bank account. The Gross Settle billing bank account number.
GrossSettleAccountType String 25 Required Required if Gross Settle billing info is bank account.
  • C - Checking
  • S - Savings
  • G - General Ledger
GrossSettleAddress String Required Gross Settle Billing information address.
GrossSettleCity String 25 Required Gross Settle Billing information address.
GrossSettleCountry String 3 Required Gross Settle billing information address. Must be 3 character ISO standard country code.
GrossSettleCreditCardExpDate String 4 Required The Gross Settle billing information credit card expiration date expressed as mmyy.
GrossSettleCreditCardNumber String 16 Required The Gross Settle billing information credit card number. Standard cc numbers which must pass Luhn check.
GrossSettleNameOnCard String 25 Required The Gross Settle billing information on credit card.
GrossSettleRoutingNumber String 9 Required Required if Gross Settle billing info is bank account.
The Gross Settle billing bank account routing number. Must be a valid Fedwire ACH participant.
GrossSettleState String 2 Required Gross Settle billing information address. Must be 2 characters standard State or province code. Do no use if not USA or CAN
GrossSettleZipCode String 9 Required Gross Settle billing information address.
Must be standard US or Canadian zip code. Do not use if not USA or CAN
Data from ProPay, Inc PCI documentation.
ProPay Account Signup Response Elements
NOTE Required for Gross Billing features, with prior approval.
Element Type Notes
status String Result of the transaction request.
See Appendix A for result code definitions.
accntNum Integer Assigned to each account by ProPay.
password String Temporary password. Will need to be changed on first login.
sourceEmail String Email address used for signup.
Data from ProPay, Inc PCI documentation.

When Boarding and underwriting merchants using a Business Tax ID:

NOTE Do not pass an SSN, only the Business Tax ID

Business Account Information
NOTE Required, unless noted.
Element Type Max Required Notes
dayPhone String Required Business day phone number.
For USA and CAN value must be 10 characters with no dashes.
DoingBusinessAs String 40 Required This field is used to provide DBA information on an account.
ProPay accounts can be configured to display DBA on Credit Card Statements.
NOTE * May be required by ProPay Risk team.
EIN String 9 Required Employer Identification Number, required for business risk analysis.
firstName String 20 Optional Merchant/Individual first name.
lastName String 25 Optional Merchant/Individual last name.
MCCCode String 4 Required Merchant Category code
sourceEmail String 55 Required Business email address. Must be unique in ProPay system.
tier String 40 Required One of the previously assigned business tier types.
WebsiteURL String 255 Optional The Business' website URL.
NOTE * May be required by ProPay Risk team.
BusinessDescription String 255 Optional The Business' description
NOTE * May be required by ProPay Risk team.
MonthlyBankCardVolume Int(64) Signed Int(64) Optional 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.
NOTE * May be required by ProPay Risk team.
AverageTicket Int(64) Signed Int(64) Optional The monthly volume 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.
NOTE * May be required by ProPay Risk team.
HighTicket Int(64) Signed Int(64) Optional The highest transaction amount; Values representing the number of pennies in USD, or the number of [currency] without decimals. Defaults to $300.00 if not sent.
NOTE * May be required by ProPay Risk team.
Data from ProPay, Inc PCI documentation.
Business Address Information
NOTE Required, unless noted.
Element Type Max Required Notes
BusinessAddress String 100 Required Business Physical Address 1
BusinessCity String Required Business Physical Address
BusinessCountry String Required Business Physical Address 1
ISO 3166 standard 3 character country codes
BusinessLegalName String 255 Required The Legal name of the business as registered.
BusinessState String 3 Required Business Physical Address.
Standard 2-3 character abbreviation for state, province, prefecture, etc.
BusinessZip String 9 Required Business Physical Address
*For USA: 5 or 9 characters without dash. For CAN: 6 character postal code without space.
BusinessAddress2 String 100 Optional Business Physical Address line 2
Data from ProPay, Inc PCI documentation.
Merchant Threat Risk Assessment Information
NOTE Required, unless noted.
Element Type Max Required Notes
MerchantSourceIp String 64 Required SourceIp of Mechant, see Appendix C for additional information.
*Legacy XML Only.
ThreatMetrixPolicy String 32 Required Threat Metrix Policy, see Appendix C for additional information.
*Threat Metrix Only.
*Legacy XML Only.
ThreatMetrixSessionId String 128 Required SessionId for Threat Metrix, see Appendix C for additional information.
*Threat Metrix Only.
*Legacy XML Only.
Data from ProPay, Inc PCI documentation.
Business Primary Bank Account Information
NOTE Required, unless noted, if adding 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 Required Merchant/Individual description of account.
Data from ProPay, Inc PCI documentation.
Business Gross Billing Information
NOTE Required, unless noted.
Element Type Max Required Notes
GrossSettleAccountCountryCode String 3 Required Required if Gross Settle billing info is bank account. Must be ISO standard 3 character country code.
*Legacy XML Only.
GrossSettleAccountHolderName Required Required if Gross Settle billing info is bank account. The Gross Settle billing bank account holder name.
*Legacy XML Only.
GrossSettleAccountNumber String 25 Required Required if Gross Settle billing info is bank account. The Gross Settle billing bank account number.
*Legacy XML Only.
GrossSettleAccountType String 10 Required Required if Gross Settle billing info is bank account.
  • C - Checking
  • S - Savings
  • G - General Ledger
GrossSettleAddress String 25 Required Gross Settle Billing information address.
*Legacy XML Only.
GrossSettleCity String 25 Required Gross Settle Billing information address.
*Legacy XML Only.
GrossSettleCountry String 3 Required Gross Settle billing information address. Must be 3 character ISO standard country code.
*Legacy XML Only.
GrossSettleCreditCardExpDate String 4 Required The Gross Settle billing information credit card expiration date expressed as mmyy.
*Legacy XML Only.
GrossSettleCreditCardNumber String 16 Required The Gross Settle billing information credit card number. Standard cc numbers which must pass Luhn check.
*Legacy XML Only.
GrossSettleNameOnCard String 25 Required The Gross Settle billing information name on credit card.
*Legacy XML Only.
GrossSettleRoutingNumber String 9 Required Required if Gross Settle billing info is bank account.
The Gross Settle billing bank account routing number. Must be a valid Fedwire ACH participant.
GrossSettleState String 2 Required Gross Settle billing information address. Must be 2 characters standard State or province code. Do no use if not USA or CAN
*Legacy XML Only.
GrossSettleZipCode String 9 Required Gross Settle billing information address.
Must be standard US or Canadian zip code. Do not use if not USA or CAN
*Legacy XML Only.
Data from ProPay, Inc PCI documentation.

Response Values

Element Type Notes
status String Result of the transaction request.
See Appendix A 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.