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

Contact Info

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.
* 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
mcc integer 1234 Merchant category code (4 digits)
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
mcc integer 1234 Merchant category code (4 digits)
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
mcc integer 1234 Merchant category code (4 digits)
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
mcc integer 1234 Merchant category code (4 digits)
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
mcc integer 1234 Merchant category code (4 digits)
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.