Overview
This endpoint provides an interface for working with merchant applications. Please note that applications are not active merchant accounts. Once an application is created, it will be reviewed and activated by gateway staff. Once activated, a merchant ID will be assigned and all supported merchant related methods may be used.
For partners that are certified for self boarding, merchant applications are not required. Merchants may be added directly (see the POST reseller/merchants endpoint).
Create Merchant Application
POST /api/v2/reseller/merchant_applications
This method adds a new merchant application to the system. If successful, the application ID will be returned. The application ID can be used to check on the status of the merchant application.
Request
curl -X POST https://sandbox.usaepay.com/api/v2/reseller/merchant_applications \
-H "Content-Type: application/json" \
-H "Authorization: Basic X1Y4N1F0YjUxM0NkM3ZhYk03UkMwVGJ0SldlU284cDc6czIvYWJjZGVmZ2hpamtsbW5vcC9iNzRjMmZhOTFmYjBhMDk3NTVlMzc3ZWU4ZTIwYWE4NmQyYjkyYzNkMmYyNzcyODBkYjU5NWY2MzZiYjE5MGU2" \
-d '{
"merchant_name": "Acme Bagel Co",
"reseller_email": "acme@example.com",
"contact_info": {
"contact": "James Dean",
"street": "1234 Main",
"street2": "Suite 1010",
"city": "New York",
"state": "NY",
"postal_code": "12312",
"country": "US",
"email": "merchant@example.com",
"phone": "222-333-4444",
"alt_email": "alt@example.com",
"mobile": "333-222-1212",
"fax": "232-343-3333"
},
"billing": {
"bank_name": "Wells Fargo",
"routing": "123456789",
"account": "123123123",
"gateway_package": "Silver Package"
},
"creditcard": {
"platform": "FDMS",
"industry": "eCommerce",
"merchant_id": "123214234",
"terminal_id": "234523452345",
"merchant_num": "23423412352345"
}
}'
This cURL request is an example of retrieving a merchant application.
Response
{
"type": "merchant_application",
"key": "bn52dkpayqkf0rkkx",
"status": "Pending"
}
This is the sample response object sent back from the server.
Request Parameters
This is a complete overview of the request parameters that are sent.
| Parameter |
Type |
Description |
| reseller_email |
string |
Email address for reseller. |
| merchant_name |
string |
Company name of merchant, used to identify merchant |
| contact_info |
ContactInfo |
Address and contact information for merchant |
| billing |
BillingInfo |
Billing information and gateway package |
| user |
UserInfo |
Login settings |
| apikey |
ApiKey |
Provision an api key during boarding |
| batch |
Batch |
Batch closure settings |
| settings |
Settings |
Miscellaneous merchant settings |
| creditcard |
CreditCardProcessing |
Credit card processing configuration. |
| ach |
ACHProcessing |
Electronic check processing configuration. |
| notes |
string |
Notes or instructions for gateway staff activating merchant account, ie “Hold application until 3/4/10” |
Response Variables
| Parameter |
Type |
Description |
| type |
string |
This denotes the fact that this response object is a token. |
Retrieve Merchant Application
GET /api/v2/reseller/merchant_applications/:app_key:
Retrieve a merchant application by its :app_key:. Once the application is approved, merch_key will be available in the response. This key can be used to retrieve information on the active merchant.
Request
curl https://sandbox.usaepay.com/api/v2/reseller/merchant_applications/bn52dkpayqkf0rkkx \
-H "Authorization: Basic X1Y4N1F0YjUxM0NkM3ZhYk03UkMwVGJ0SldlU284cDc6czIvYWJjZGVmZ2hpamtsbW5vcC9iNzRjMmZhOTFmYjBhMDk3NTVlMzc3ZWU4ZTIwYWE4NmQyYjkyYzNkMmYyNzcyODBkYjU5NWY2MzZiYjE5MGU2"
Response
{
"type": "merchant_application",
"key": "en51d0t16zrfb0nrw",
"reseller_email": "acme@example.com",
"merchant_name": "Acme Bagel Co",
"contact_info": {
"contact": "James Dean",
"street": "1234 Main",
"street2": "Suite 1010",
"state": "NY",
"city": "New York",
"postal_code": "12312",
"country": "US",
"email": "merchant@example.com",
"phone": "222-333-4444",
"alt_email": "alt@example.com",
"mobile": "333-222-1212",
"fax": "232-343-3333"
},
"settings": {
"call_in_password": "",
"email_instruction_to": null
},
"billing": {
"bank_name": "Wells Fargo",
"routing": "xxxxx6789",
"account": "xxxxx3123",
"gateway_package": null
},
"apikey": {
"name": null,
"pin": null,
"type": null,
"deliver_to_email": null
},
"user": {
"username": null
},
"notes": null,
"status": "Pending"
}
Response Variables
| Parameter |
Type |
Description |
| reseller_email |
string |
Email address for reseller. |
| merchant_name |
string |
Company name of merchant, used to identify merchant |
| contact_info |
ContactInfo |
Address and contact information for merchant |
| billing |
BillingInfo |
Billing information and gateway package |
| user |
UserInfo |
Login settings |
| apikey |
ApiKey |
Provision an api key during boarding |
| batch |
Batch |
Batch closure settings |
| settings |
Settings |
Miscellaneous merchant settings |
| creditcard |
CreditCardProcessing |
Credit card processing configuration. |
| ach |
ACHProcessing |
Electronic check processing configuration. |
| notes |
string |
Notes or instructions for gateway staff activating merchant account, ie “Hold application until 3/4/10” |
| status |
string |
Status of the merchant application. Possible values: "Pending","Under Review","Waiting For Documents","Call Support","Declined","Approved","Canceled" |
| merch_key |
string |
The key identifying the active merchant account (once application is approved) |
Search Applications
GET /api/v2/reseller/merchant_applications
Retrieve list of merchant applications. You can also filter on most of the merchant_application fields by prefixing with "filter_". Quick fuzzy searching can be done using the filter parameter
Request
curl https://sandbox.usaepay.com/api/v2/reseller/merchant_applications?filter_merchant_name=Acme+Bagel+Co \
-H "Authorization: Basic X1Y4N1F0YjUxM0NkM3ZhYk03UkMwVGJ0SldlU284cDc6czIvYWJjZGVmZ2hpamtsbW5vcC9iNzRjMmZhOTFmYjBhMDk3NTVlMzc3ZWU4ZTIwYWE4NmQyYjkyYzNkMmYyNzcyODBkYjU5NWY2MzZiYjE5MGU2"
Response
{
"type": "list",
"limit": 20,
"offset": 0,
"data": [
{
"type": "merchant_application",
"key": "an51d0r750tq64a6r",
"reseller_email": "acme@example.com",
"merchant_name": "Acme Bagel Co",
"contact_info": {
"contact": "John Doe",
"street": "1234 Main",
"street2": "Suite 1010",
"state": "NY",
"city": "New York",
"postal_code": "12312",
"country": "US",
"email": "merchant@example.com",
"phone": "222-333-4444",
"alt_email": "alt@example.com",
"mobile": "333-222-1212",
"fax": "232-343-3333"
},
"settings": {
"call_in_password": "",
"email_instruction_to": null
},
"billing": {
"bank_name": "Wells Fargo",
"routing": "xxxxx6789",
"account": "xxxxx3123",
"gateway_package": null
},
"apikey": {
"name": null,
"pin": null,
"type": null,
"deliver_to_email": null
},
"user": {
"username": null
},
"notes": null,
"status": "Pending"
}
],
"total": 1
}
Data Reference
ACH Processing
| Parameter |
Type |
Description |
| platform |
string |
Name of the electronic check processor to set the merchant up on. Contact integration support for the latest list |
| * |
string |
Remaining fields depend on the platform selected, see below for platform specific fields |
ApiKey Setup
| Parameter |
Type |
Description |
| name |
string |
Name of SourceKey to create when merchant is activated. Leave blank if no source key is requested |
| pin |
string |
Pin to assign to new API Key |
| type |
string |
ID of vendor to deliver apikey to (optional) |
| deliver_to_email |
string |
Email address to send the new apikey to. The email will contain the apikey but not the pin. |
Batch Object
| Variable |
Type |
Description |
| auto_closure |
string |
The desired schedule for automatically closing the merchants open batch. If omitted, the setting from the selected Package will be used. Can either be every x hours: '6 hours', '12 hours', '24 hours', '36 hours', '48 hours', '72 hours' or it can be a specific time of day: '3:45pm'. Multiple closures can be specified in a comma separated list: '6:30am,7:39pm,11:55pm' |
| email |
string |
Email address to send batch closure reports to |
| errors_email |
string |
Email address to send batch closure failure notices to |
Billing Info Object
| Parameter |
Type |
Description |
| bank_name |
string |
Name of merchants bank |
| routing |
string |
Bank routing number (9 digits) |
| account |
string |
Bank account number (numeric) |
| gateway_package |
string |
Billing/feature package, standard package names: "Silver Package", "Gold Package (Fraud Center)", "Gold Package (Cust DB)" and "Platinum Package" Contact channel sales for list of non-standard package names |
| Parameter |
Type |
Description |
| contact |
string |
First and Last name of the merchants owner or primary contact |
| street |
string |
Merchant's street address |
| street2 |
string |
Merchant's street address, line 2 |
| city |
string |
Merchant's city |
| state |
string |
Merchant's state (two letter state code) |
| postal_code |
string |
Merchant's zip or postal code |
| country |
string |
Merchant's country (three letter country code) |
| email |
string |
Merchant's primary email address |
| phone |
string |
Merchant's phone number (###-###-#### format, country code optional) |
| mobile |
string |
Merchant's mobile phone number (optional) |
| alt_email |
string |
An alternative email address for merchant (optional) |
| fax |
string |
Merchant's fax number (optional) |
Credit Card Processing
| Parameter |
Type |
Description |
| platform |
string |
Name of the credit card processor to set the merchant up on. Possible values are: EPX, FDMS, FDMS North Global, Heartland, MeS, Paymentech, TSYS, Rapid Connect and Vantiv. Leave blank if no credit card processing is requested. |
| industry |
string |
Primary industry of merchant: : eCommerce, Mail Order, Retail (Swipe), Hotel, Restaurant, Utility/Bill Pay, or Utility/Bill Pay (Card Present) |
| refund_policy |
string |
This sets the level of restrictions placed on a merchants ability to issue credits (refunds) to a credit cards. Possible values (listed from least to most restrictive): No Restrictions, Minimal Restrictions, Require Prior Sale, Connected Refunds Only, Block All Credits |
| pin_debit_support |
boolean |
Set to true to enable pin debit processing. |
| mcc |
integer |
Merchant category code (4 digits) |
| * |
string |
Remaining fields depend on the platform selected, see below for platform specific fields |
Settings Object
| Variable |
Type |
Description |
| call_in_password |
string |
Optional call in password for merchant. If a merchant has a call in password, they must provide this password to customer support |
| email_instructions_to |
string |
Email address to send the merchant console instructions to. The email will include the merchants username and password |
| master_user |
string |
Access to an existing multi merchant master username |
| console_version |
string |
Set the version of the console to set the merchant under. Will default to the resellers preference |
User Object
| Variable |
Type |
Description |
| username |
string |
Username of merchant user that will be created when the application is activated. A password will be randomly assigned by the system. Merchant must change the password the first time they log in. |
| role |
string |
Normally the username will be configured with full access. This allows the newly created user to be placed in the specified “role”. |
| validate |
boolean |
Set to “true” to require that the exact username is available. Otherwise the system will try to find an available username by adding a number to the end of the requested username. |
Credit Card Processors
EPX
| Parameter |
Type |
Example |
Description |
| cust_num |
integer |
5001 |
Max length of 16 numeric digits - This will usually be 4 digits |
| merch_num |
integer |
3130030000000 |
Max length of 16 numeric digits |
| terminal_num |
integer |
1 |
Max length of 16 numeric digits |
| dba_num |
integer |
1 |
Max length of 16 numeric digits |
| mac |
integer |
1 |
Max length of 80 numeric digits (optional) |
FDMS
| Parameter |
Type |
Example |
| merchant_num |
integer |
4120949485344948 |
| merchant_id |
integer |
0000000 |
| terminal_id |
integer |
0000000 |
FDMS North
| Parameter |
Type |
Example |
Description |
| merchant_id |
string |
RCTST0000008056 |
|
| terminal_id |
integer |
1234567 |
|
| tax_id |
integer |
000000000 |
|
| level3 |
boolean |
Y |
Denotes if level 3 processing should be enabled. Y to enable and N to disable. Defaults to disabled. |
| default_commoditycode |
integer |
00 |
Only required of Level 3 processing is enabled. |
First Data Rapid Connect
| Parameter |
Type |
Example |
Description |
| merchant_num |
integer |
4120949485344948 |
|
| merchant_id |
string |
RCTST0000008056 |
|
| terminal_id |
integer |
1234567 |
|
| group_id |
integer |
10001 |
|
| tax_id |
integer |
0000 |
|
| settlement_id |
integer |
987654321012 |
Settlement terminal id |
| level3 |
boolean |
Y |
Denotes if level 3 processing should be enabled. Y to enable and N to disable. Defaults to disabled. |
| default_commoditycode |
integer |
00 |
Only required of Level 3 processing is enabled. |
Global
| Parameter |
Type |
Example |
| bank_id |
integer |
123456 |
| merchant_id |
integer |
4567890123456 |
Heartland
| Parameter |
Type |
Example |
Description |
| acquirer_bin |
integer |
123456 |
|
| merchant_num |
integer |
891234567890 |
|
| agent_bank |
integer |
000000 |
|
| agent_chain |
integer |
000000 |
|
| store_number |
integer |
0001 |
|
| terminal_number |
integer |
0001 |
|
| merchant_name |
string |
ACME BAGELS |
Merchant name as it will appear on cardholder statement |
| merchant_state |
string |
CA |
|
| merchant_zip |
integer |
90010 |
|
| service_phonen_umber |
integer |
3239312233 |
Customer Service number for merchant |
| amexlevel2 |
boolean |
Y |
Merchant is enrolled to process level 2 corporate purchasing cards (Y/N) |
| debit_networks |
string |
V,P,T |
Comma separated list of one character debit network codes |
MeS
| Parameter |
Type |
Example |
Description |
| acquirer_bin |
integer |
123456 |
|
| merchant_num |
integer |
891234567890 |
|
| agent_bank |
integer |
000000 |
|
| agent_chain |
integer |
000000 |
|
| store_number |
integer |
0001 |
|
| terminal_number |
integer |
0001 |
|
| merchant_name |
string |
ACME BAGELS |
Merchant name as it will appear on cardholder statement |
| merchant_state |
string |
CA |
|
| merchant_zip |
integer |
90010 |
|
| service_phonen_umber |
integer |
3239312233 |
Customer Service number for merchant |
| amexlevel2 |
boolean |
Y |
Merchant is enrolled to process level 2 corporate purchasing cards (Y/N) |
| debit_networks |
string |
V,P,T |
Comma separated list of one character debit network codes |
Paymentech
| Parameter |
Type |
Example |
| client_number |
integer |
1234 |
| merchant_id |
integer |
012345678901 |
| terminal_number |
integer |
001 |
Tsys
| Parameter |
Type |
Example |
Description |
| acquirer_bin |
integer |
123456 |
|
| merchant_num |
integer |
891234567890 |
|
| agent_bank |
integer |
000000 |
|
| agent_chain |
integer |
000000 |
|
| store_number |
integer |
0001 |
|
| terminal_number |
integer |
0001 |
|
| vnumber |
integer |
1234567 |
Only needed for Tsys |
| merchant_name |
string |
ACME BAGELS |
Merchant name as it will appear on cardholder statement |
| merchant_state |
string |
CA |
|
| merchant_zip |
integer |
90010 |
|
| service_phonen_umber |
integer |
3239312233 |
Customer Service number for merchant |
| amexlevel2 |
boolean |
Y |
Merchant is enrolled to process level 2 corporate purchasing cards (Y/N) |
| debit_networks |
string |
V,P,T |
Comma separated list of one character debit network codes |
| level3 |
boolean |
Y |
Denotes if level 3 processing should be enabled. Y to enable and N to disable. Defaults to disabled. |
| default_commoditycode |
integer |
00 |
Only required of Level 3 processing is enabled. |
Vantiv
| Parameter |
Type |
Description |
| bank_id |
integer |
123456 |
| merchant_id |
integer |
567890123456 |
| terminal_id |
integer |
001 |
| debit_terminal_id |
integer |
000 |
Errors
| Code |
Message |
Advice |
| 19000 |
Unable to save application. |
A temporary error occurred while saving the application. Try again or contact support |
| 19001 |
The field 'fieldname' is required. |
A required field was not populated. See the error message for the name of the missing field. |
| 19014 |
Email address 'fieldname' not valid |
The email address fields was not a valid email address. It did not pass the formatting check. Check formatting. |
| 19015 |
Email address 'fieldname' not valid |
One of the email addresses entered was invalid. It did not pass the DNS or mail server delivery checks. Double check the address. |
| 19016 |
Requested credit card platform not supported |
The CreditCardPlatform was not found in the list of supported platforms |
| 19017 |
Requested credit card industry not supported |
The CreditCardIndustry was not a supported industry. |
| 19019 |
Requested check platform not supported |
The eCheckPlatform was not found in the list of supported platforms. |
| 19020 |
Billing package not found. |
Specified billing package was not found. Double check the list of valid billing package names. |
Change Log
| Date |
Change |
| 2018-01-18 |
Added page |
| 2018-02-28 |
Added FDMS North platform. |
| 2018-10-09 |
Added pin_debit_support field to credit card processing object. |
Click here for the full REST API change log.
