Marketplace APIs
GET Categories
# Don't forget to add your HMAC Authorization Headers
endpoint = "/marketplace/v1/categories"
r = requests.get(url + endpoint, headers=headers)
print(r)
# Don't forget to add your HMAC Authorization Headers
ENDPOINT="$URL/marketplace/v1/categories"
curl -X GET -H "date: $DATE" -H "Authorization: $HMAC_AUTH" $ENDPOINT
// Don't forget to add your HMAC Authorization Headers
var options = {
method: 'GET',
url: url + '/marketplace/v1/categories',
headers: getAuthenticationHeaders()
};
request(options, function (error, response, body) {
if (error) throw new Error(error);
console.log(response);
});
// Don't forget to add your HMAC Authorization Headers
HttpResponse response = null;
try {
response = doGet("/marketplace/v1/categories");
int statusCode = response.getStatusLine().getStatusCode();
String response_string = EntityUtils.toString(response.getEntity());
System.out.println("json:" + response_string);
} catch (Exception e) {
e.printStackTrace();
}
<?php
# Don't forget to add your HMAC Authorization Headers
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url . "/marketplace/v1/categories");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
$res = curl_exec($ch);
echo($res);
?>
The above command returns JSON structured like this (partial response):
[{
"id": 100,
"name": "RETAIL",
"description": "Retail",
"rank": 1,
"imageURL": "https://s3-us-west-2.amazonaws.com/fdmarketplace/res/img/categories/retail-physical-presence.png"
}, {
"id": 101,
"name": "RESTAURANT",
"description": "Restaurant",
"rank": 2,
"imageURL": "https://s3-us-west-2.amazonaws.com/fdmarketplace/res/img/categories/restaurant-pay-at-the-counter.png"
}, {
"id": 102,
"name": "MOTO",
"description": "Moto (Mail Order Telephone Order)",
"rank": 3,
"imageURL": "https://s3-us-west-2.amazonaws.com/fdmarketplace/res/img/categories/mailorder-telephoneorder.png"
}]
This endpoint retrieves a list of business categories (such as Retail, MOTO and Restaurant) for your Marketplace.
Request
GET /marketplace/v1/categories
| Parameter | Required | Data Type | Default | Description |
|---|---|---|---|---|
| no input |
Response
This endpoint returns an array of objects, each representing a business category. The following parameters are in each object returned.
| Parameter | Data Type | Description |
|---|---|---|
| id | integer | Numeric value that uniquely identifies a category (canonical identifier). |
| name | string | Unique name of the Category used in other API Endpoints as input when referencing this Category. |
| description | string | Name of the Category used in the user interface. |
| rank | integer | The index of the Category to define the display order in the user interface. |
| imageURL | string | Public URL of 1 image associated with the Category. |
GET Products
# Don't forget to add your HMAC Authorization Headers
endpoint = "/marketplace/v1/products"
r = requests.get(url + endpoint, headers=headers)
print(r)
# Don't forget to add your HMAC Authorization Headers
ENDPOINT="$URL/marketplace/v1/products"
curl -X GET -H "date: $DATE" -H "Authorization: $HMAC_AUTH" $ENDPOINT
// Don't forget to add your HMAC Authorization Headers
var options = {
method: 'GET',
url: url + '/marketplace/v1/products',
headers: getAuthenticationHeaders()
};
request(options, function (error, response, body) {
if (error) throw new Error(error);
console.log(response);
});
// Don't forget to add your HMAC Authorization Headers
HttpResponse response = null;
try {
response = doGet("/marketplace/v1/products");
int statusCode = response.getStatusLine().getStatusCode();
String response_string = EntityUtils.toString(response.getEntity());
System.out.println("json:" + response_string);
} catch (Exception e) {
e.printStackTrace();
}
<?php
# Don't forget to add your HMAC Authorization Headers
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url . "/marketplace/v1/products");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
$res = curl_exec($ch);
echo($res);
?>
The above command returns JSON structured like this (partial response):
[{
"id": 89393,
"productId": 231,
"supplierProductName": "Magtek Checkreader",
"supplierName": "MAMA",
"productType": "CHKRDR",
"productName": "Magtek Checkreader",
"productShortDescription": "This low cost check reader combines high accuracy with dependability. It reads MICR characters on checks, deposit, withdrawal slips and other documents, as well as the optional magnetic stripe reading capability.Execute reliable electronic ",
"productLongDescription": "This low cost check reader combines high accuracy with dependability. It reads MICR characters on checks, deposit, withdrawal slips and other documents, as well as the optional magnetic stripe reading capability.Execute reliable electronic check transactions with MagTek's Mini MICR Mini MICR reads real-world checks with the highest accuracy in the industry. Mini MICR's rugged and durable design will provide years of daily use. With over millions check readers installed worldwide, Mini MICR is in service today with major retailers and financial institutions reading billions of checks annually. Mini MICR offers a range of interface options for easy and flexible connectivity to POS terminals, PCs, cash registers, etc. Benefits The MICR data is automatically read from checks in a quick, single-pass. Transaction time and manual entry errors are significantly reduced. Mini MICR can easily format the MICR data to match any application input requirements. Mini MICR's horseshoe design creates the smallest footprint with no additional counter space required to allow for check movement. Applications At the POS, Mini MICR's reliability and functionality are ideal for check verification and check conversion applications. At the Teller Window, Mini MICR's speed and accuracy can significantly reduce transaction time when processing deposits with multiple checks. Ease of Use The easy drop-and-push movement to feed the check facilitates operator training. No complicated alignments required to feed the check.",
"showoncart": true,
"productWithOptions": false,
"pinPad": false,
"imageUrls": [
"https://s3-us-west-2.amazonaws.com/fdmarketplace/res/img/products/large/231/image_1.jpg",
"https://s3-us-west-2.amazonaws.com/fdmarketplace/res/img/products/thumb/231/image_1.jpg"
],
"categoryIds": [],
"tags": []
}, {
"id": 96376,
"productId": 74042,
"supplierProductName": "Clover Mini 3G/WiFi",
"supplierName": "MAMA",
"productType": "Terminal",
"productName": "Clover Mini 3G/WiFi",
"productShortDescription": "A Clover Mini for when WiFi is not always available. One of the most advanced payment terminals on the market. As powerful as it is sleek with a small footprint that won’t hog your counter space. ",
"productLongDescription": "A Clover Mini for when WiFi is not always available. One of the most advanced payment terminals on the market. As powerful as it is sleek with a small footprint that won’t hog your counter space. ",
"showoncart": true,
"productWithOptions": false,
"pinPad": false,
"imageUrls": [
"https://s3-us-west-2.amazonaws.com/fdmarketplace/res/img/products/large/74042/image_1.jpg",
"https://s3-us-west-2.amazonaws.com/fdmarketplace/res/img/products/large/74042/image_2.jpg",
"https://s3-us-west-2.amazonaws.com/fdmarketplace/res/img/products/large/74042/image_3.jpg",
"https://s3-us-west-2.amazonaws.com/fdmarketplace/res/img/products/large/74042/image_4.jpg",
"https://s3-us-west-2.amazonaws.com/fdmarketplace/res/img/products/large/74042/image_5.jpg",
"https://s3-us-west-2.amazonaws.com/fdmarketplace/res/img/products/thumb/74042/image_1.jpg",
"https://s3-us-west-2.amazonaws.com/fdmarketplace/res/img/products/thumb/74042/image_2.jpg",
"https://s3-us-west-2.amazonaws.com/fdmarketplace/res/img/products/thumb/74042/image_3.jpg",
"https://s3-us-west-2.amazonaws.com/fdmarketplace/res/img/products/thumb/74042/image_4.jpg",
"https://s3-us-west-2.amazonaws.com/fdmarketplace/res/img/products/thumb/74042/image_5.jpg"
],
"categoryIds": [
100,
101,
102,
107
],
"tags": [
"HOME"
]
}]
This endpoint retrieves a list of products for your Marketplace.
Request
GET /marketplace/v1/products
| Parameter | Required | Data Type | Default | Description |
|---|---|---|---|---|
| no input |
Response
This endpoint returns an array of objects, each representing a product. The following parameters are in each object returned.
| Parameter | Data Type | Description |
|---|---|---|
| id | long | Unique identifier for rows (First Data’s internal record). |
| productId | long | Numeric value that uniquely identifies a product (canonical identifier). |
| supplierProductName | string | Name of the product as given by the source (supplier). Use productName in user interface. |
| supplierName | string | Name of the supplier. |
| productType | string | Indicates the behavior of the product, or when the merchant is charged a fee in case of “Processing/Pricing” products. See list of possible values here. |
| productName | string | Name of product to be used in the user interface. |
| productShortDescription | string | A short description of the product which can be used to display brief information in the Product List interface. |
| productLongDescription | string | A longer, more detailed description of the product, which should be used in the interface showing detailed information about the product. |
| showoncart | boolean | Flag to provide guidance on which products should be visibly displayed in the Shopping Cart after being selected. |
| productWithOptions | boolean | This indicates if this product has “options” (child products) that the user can select/add to cart individually. |
| pinPad | boolean | Indicates if a debit PIN pad is included with the product. true: PIN pad is included. false: PIN pad is not included. |
| imageUrls | array | Array of public URLs (string type) of up to 5 pairs of images associated with the product. Images in /large/ directory are full size versions of smaller thumbnails with the same name in /thumb/ directory. |
| categoryIds | array | Array of Categories (represented by the id attribute - integer type - of the Category) that the product belongs to. |
| tags | array | A list of tags that can be used to search for or filter products. |
Possible values for productType
| Value | Meaning | Behavior/Requirements |
|---|---|---|
"ACCES" | Hardware or equipment accessory | |
"APP_FEE" | Application fee | |
"CABLES" | Cables for hardware | |
"CHKRDR" | Check reader equipment | A "CHKRDR" type product is required if a check acceptance product is selected. |
"GAS" | Hardware/Equipment for petroleum products | |
"IMP" | Imprinter equipment | |
"INET_HOST" | Hosted Gateway | |
"INET_MISC" | Misc. Gateway | |
"MO_FEE" | Fee that is charged on a monthly basis | |
"NET_FEE" | Fee that is charged on every card transaction or occurrence | |
"OTHER" | Other | |
"PINPAD" | Pin pad for terminals and registers | A "PINPAD" type product is required if “Debit” processing product option is selected. |
"PP_CABLES" | Cables for PINPAD products | |
"PRNTR" | Printer | |
"Power_Sup" | Power supply for hardware and equipment | |
"REG" | Register | |
"SATBUNDLE" | Products that use some sort of network - Datawire etc. | |
"SETUP_FEE" | Fees for setting up a merchant for acquiring | |
"SOFT" | Software | |
"STAND" | Stand and mounting products for hardware and equipment | |
"TERM" | Terminal | Minimum 1 "TERM" type product is required to onboard new merchants. |
GET Product/Details
# Don't forget to add your HMAC Authorization Headers
endpoint = "/marketplace/v1/products/74042/details"
r = requests.get(url + endpoint, headers=headers)
print(r)
# Don't forget to add your HMAC Authorization Headers
ENDPOINT="$URL/marketplace/v1/products/74042/details"
curl -X GET -H "date: $DATE" -H "Authorization: $HMAC_AUTH" $ENDPOINT
// Don't forget to add your HMAC Authorization Headers
var options = {
method: 'GET',
url: url + '/marketplace/v1/products/74042/details',
headers: getAuthenticationHeaders()
};
request(options, function (error, response, body) {
if (error) throw new Error(error);
console.log(response);
});
// Don't forget to add your HMAC Authorization Headers
HttpResponse response = null;
try {
response = doGet("/marketplace/v1/products/74042/details");
int statusCode = response.getStatusLine().getStatusCode();
String response_string = EntityUtils.toString(response.getEntity());
JSONObject json = new JSONObject(response_string);
System.out.println("json:" + json.toString());
} catch (Exception e) {
e.printStackTrace();
}
<?php
# Don't forget to add your HMAC Authorization Headers
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url . "/marketplace/v1/products/74042/details");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
$res = curl_exec($ch);
echo($res);
?>
The above command returns JSON structured like this:
{
"id": 96376,
"productId": 74042,
"supplierProductName": "Clover Mini 3G/WiFi",
"supplierName": "MAMA",
"productType": "Terminal",
"productName": "Clover Mini 3G/WiFi",
"productShortDescription": "A Clover Mini for when WiFi is not always available. One of the most advanced payment terminals on the market. As powerful as it is sleek with a small footprint that won’t hog your counter space.",
"productLongDescription": "A Clover Mini for when WiFi is not always available. One of the most advanced payment terminals on the market. As powerful as it is sleek with a small footprint that won’t hog your counter space.",
"showoncart": true,
"price": 649,
"productWithOptions": false,
"pinPad": true,
"imageUrls": [
"https://s3-us-west-2.amazonaws.com/fdmarketplace/res/img/products/large/74042/image_1.jpg",
"https://s3-us-west-2.amazonaws.com/fdmarketplace/res/img/products/large/74042/image_2.jpg",
"https://s3-us-west-2.amazonaws.com/fdmarketplace/res/img/products/large/74042/image_3.jpg",
"https://s3-us-west-2.amazonaws.com/fdmarketplace/res/img/products/large/74042/image_4.jpg",
"https://s3-us-west-2.amazonaws.com/fdmarketplace/res/img/products/large/74042/image_5.jpg",
"https://s3-us-west-2.amazonaws.com/fdmarketplace/res/img/products/thumb/74042/image_1.jpg",
"https://s3-us-west-2.amazonaws.com/fdmarketplace/res/img/products/thumb/74042/image_2.jpg",
"https://s3-us-west-2.amazonaws.com/fdmarketplace/res/img/products/thumb/74042/image_3.jpg",
"https://s3-us-west-2.amazonaws.com/fdmarketplace/res/img/products/thumb/74042/image_4.jpg",
"https://s3-us-west-2.amazonaws.com/fdmarketplace/res/img/products/thumb/74042/image_5.jpg"
],
"categoryIds": [ ],
"pricingModel": [
{
"id": 6881,
"fkProdId": 74042,
"fkCompanyId": 386,
"purchaseType": "IP3",
"defaultAmt": 219,
"status": "A",
"occurrence": "Recurring",
"purchaseTypeLabel": "3 Month Installment"
},
{
"id": 6879,
"fkProdId": 74042,
"fkCompanyId": 386,
"purchaseType": "LT36",
"defaultAmt": 30.93,
"status": "A",
"occurrence": "Recurring",
"purchaseTypeLabel": "36 Month Lease"
},
{
"id": 6878,
"fkProdId": 74042,
"fkCompanyId": 386,
"purchaseType": "P",
"defaultAmt": 649,
"status": "A",
"occurrence": "Onetime_Product",
"purchaseTypeLabel": "Purchased"
}
]
}
This endpoint retrieves the product details for any given product.
Request
GET /marketplace/v1/products/{productId}/details
In the URL, use the productId as it was returned in the response of the GET Products API.
| Parameter | Required | Data Type | Default | Description |
|---|---|---|---|---|
| no input |
Response
This endpoint returns an object containing information such as descriptions, price and other detailed attributes of the product. The following parameters are in each object returned.
| Parameter | Data Type | Description |
|---|---|---|
| id | long | Unique identifier for rows (First Data’s internal record). |
| productId | long | Numeric value that uniquely identifies a product (canonical identifier). |
| supplierProductName | string | Name of the product as given by the source (supplier). Use productName in user interface. |
| supplierName | string | Supplier name. |
| productType | string | Indicates the behavior of the product, or when the merchant is charged a fee in case of “Processing/Pricing” products. See list of possible values here. |
| productName | string | Name of product to be used in the user interface. |
| productShortDescription | string | A short description of the product which can be used to display brief information in the Product List interface. |
| productLongDescription | string | A longer, more detailed description of the product, which should be used in the interface showing detailed information about the product. |
| showoncart | boolean | Flag to provide guidance on which products should be visibly displayed in the Shopping Cart after being selected. |
| price | float | Product price in USD. |
| productWithOptions | boolean | This indicates if this product has “options” (child products) that the user can select/add to cart individually. |
| pinPad | boolean | Indicates if a debit PIN pad is included with the product. true: PIN pad is included. false: PIN pad is not included. |
| categoryIds | array | Array of Categories (represented by the id attribute - integer type - of the Category) that the product belongs to. |
| imageUrls | array | Array of public URLs (string type) of up to 5 pairs of images associated with the product. Images in /large/ directory are full size versions of smaller thumbnails with the same name in /thumb/ directory. |
| pricingModel | array | Array of pricing type objects contains the different kinds of purchasing options available for the product. Each object in the array represents a “pricing type product.” |
| id | long | Unique Identifier for every pricing product. |
| fkProdId | long | Same as productId. Numeric value that uniquely identifies a product that the pricing type product belongs to. |
| purchaseType | string | Abbreviated code for purchase types. See list of possible values here. |
| defaultAmt | float | Amount to be paid when selecting the particular purchase type in USD. |
| occurrence | string | Information about the occurrence of the charge. Possible values: "OneTime_Products" - the amount is paid once. "Recurring" - the amount is paid periodically. |
| purchaseTypeLabel | string | The description (“name”) of the purchase type to display in the user interface. Possible values: "Purchased", "Rental", "Lease", "Installment" |
Possible values for purchaseType
The purchaseType together with occurrence in the pricingModel array defines the frequency/means of defaultAmt is charged for a product.
| Value | associated purchaseTypeLabel | Meaning |
|---|---|---|
"IP3" | “3 Month Installment” | Pay the defaultAmt in installments every month for a period of 3 months. |
"IP6" | “6 Month Installment” | Pay the defaultAmt in installments every month for a period of 6 months. |
"IP9" | “9 Month Installment” | Pay the defaultAmt in installments every month for a period of 9 months. |
"IP12" | “12 Month Installment” | Pay the defaultAmt in installments every month for a period of 12 months. |
"LR" | “Lease Rental” | Pay the defaultAmt every month to lease the product. |
"LT12" | “12 Month Lease” | Pay the defaultAmt every month for a period of 12 months (lease term) to lease the product. |
"LT24" | “24 Month Lease” | Pay the defaultAmt every month for a period of 24 months (lease term) to lease the product. |
"LT27" | “27 Month Lease” | Pay the defaultAmt every month for a period of 27 months (lease term) to lease the product. |
"LT36" | “36 Month Lease” | Pay the defaultAmt every month for a period of 36 months (lease term) to lease the product. |
"LT48" | “48 Month Lease” | Pay the defaultAmt every month for a period of 47 months (lease term) to lease the product. |
"LT60" | “60 Month Lease” | Pay the defaultAmt every month for a period of 60 months (lease term) to lease the product. |
"O" | “Owned” | Currently owned (compatible) equipment to be added to the account during on-boarding. |
"P" | “Purchased” | Pay the defaultAmt to purchase the product. |
"R" | “Rent” | |
"RP" | “Re-program” | The currently owned (compatible) equipment is to be re-programmed to work with First Data and the defaultAmt is charged. |
"S" | “Swap” | |
"SR" | “Short Term Rental” | The defaultAmt is charged periodically for the time of rental. |
GET Product/Features
# Don't forget to add your HMAC Authorization Headers
endpoint = "/marketplace/v1/products/74042/features"
r = requests.get(url + endpoint, headers=headers)
print(r)
# Don't forget to add your HMAC Authorization Headers
ENDPOINT="$URL/marketplace/v1/products/74042/features"
curl -X GET -H "date: $DATE" -H "Authorization: $HMAC_AUTH" $ENDPOINT
// Don't forget to add your HMAC Authorization Headers
var options = {
method: 'GET',
url: url + '/marketplace/v1/products/74042/features',
headers: getAuthenticationHeaders()
};
request(options, function (error, response, body) {
if (error) throw new Error(error);
console.log(response);
});
// Don't forget to add your HMAC Authorization Headers
HttpResponse response = null;
try {
response = doGet("/marketplace/v1/products/74042/features");
int statusCode = response.getStatusLine().getStatusCode();
String response_string = EntityUtils.toString(response.getEntity());
System.out.println("json:" + response_string);
} catch (Exception e) {
e.printStackTrace();
}
<?php
# Don't forget to add your HMAC Authorization Headers
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url . "/marketplace/v1/products/74042/features");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
$res = curl_exec($ch);
echo($res);
?>
The above command returns JSON structured like this:
[
"Use as a powerful payment terminal or full featured point of sale with Clover Register Plan (Item level orders and inventory tracking).",
"3G connectivity option: Requires data plan (your own or a plan provided by Clover).",
"End-to-end encryption, data tokenization, and hardware designed exclusively for payments processing. ",
"Built in printer, on-screen signature capture, and front facing camera for barcode and QR code scanning,",
"Access to Clover App Market with apps designed to help you sell more and run your business better."
]
This endpoint retrieves a list of features for any given product.
Request
GET /marketplace/v1/products/{productId}/features
In the URL, use the productId as it was returned in the response of the GET Products API.
| Parameter | Required | Data Type | Default | Description |
|---|---|---|---|---|
| no input |
Response
This endpoint returns an array of strings, each representing a feature.
| Parameter | Data Type | Description |
|---|---|---|
| features | array | List of features. |
| feature | string | One feature line. |
GET Product/Includes
# Don't forget to add your HMAC Authorization Headers
endpoint = "/marketplace/v1/products/74042/includes"
r = requests.get(url + endpoint, headers=headers)
print(r)
# Don't forget to add your HMAC Authorization Headers
ENDPOINT="$URL/marketplace/v1/products/74042/includes"
curl -X GET -H "date: $DATE" -H "Authorization: $HMAC_AUTH" $ENDPOINT
// Don't forget to add your HMAC Authorization Headers
var options = {
method: 'GET',
url: url + '/marketplace/v1/products/74042/includes',
headers: getAuthenticationHeaders()
};
request(options, function (error, response, body) {
if (error) throw new Error(error);
console.log(response);
});
// Don't forget to add your HMAC Authorization Headers
HttpResponse response = null;
try {
response = doGet("/marketplace/v1/products/74042/includes");
int statusCode = response.getStatusLine().getStatusCode();
String response_string = EntityUtils.toString(response.getEntity());
System.out.println("json:" + response_string);
} catch (Exception e) {
e.printStackTrace();
}
<?php
# Don't forget to add your HMAC Authorization Headers
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url . "/marketplace/v1/products/74042/includes");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
$res = curl_exec($ch);
echo($res);
?>
The above command returns JSON structured like this (partial response):
[{
"id": 95667,
"productId": 65823,
"supplierProductName": "CLVSGL",
"supplierName": "MAMA",
"productType": "ACCES",
"productName": " Clover Register Software",
"productShortDescription": "The center of your Clover activities including taking orders and payments. Simple to use and ready to meet the demands of business.",
"productLongDescription": "The center of your Clover activities including taking orders and payments. Simple to use and ready to meet the demands of business.",
"showoncart": true,
"productWithOptions": false,
"pinPad": false,
"imageUrls": [
"https://s3-us-west-2.amazonaws.com/fdmarketplace/res/img/products/large/65823/image_1.jpg",
"https://s3-us-west-2.amazonaws.com/fdmarketplace/res/img/products/thumb/65823/image_1.jpg"
]
}, {
"id": 96368,
"productId": 73942,
"supplierProductName": "AA105K",
"supplierName": "MAMA",
"productType": "ITERM",
"productName": "Clover Mini 3G/WiFi",
"productShortDescription": "A Clover Mini for when WiFi is not always available. One of the most advanced payment terminals on the market. As powerful as it is sleek with a small footprint that won’t hog your counter space.",
"productLongDescription": "A Clover Mini for when WiFi is not always available. One of the most advanced payment terminals on the market. As powerful as it is sleek with a small footprint that won’t hog your counter space.",
"showoncart": true,
"productWithOptions": false,
"pinPad": false,
"imageUrls": [
"https://s3-us-west-2.amazonaws.com/fdmarketplace/res/img/products/large/73942/image_1.jpg",
"https://s3-us-west-2.amazonaws.com/fdmarketplace/res/img/products/large/73942/image_2.jpg",
"https://s3-us-west-2.amazonaws.com/fdmarketplace/res/img/products/large/73942/image_3.jpg",
"https://s3-us-west-2.amazonaws.com/fdmarketplace/res/img/products/large/73942/image_4.jpg",
"https://s3-us-west-2.amazonaws.com/fdmarketplace/res/img/products/large/73942/image_5.jpg",
"https://s3-us-west-2.amazonaws.com/fdmarketplace/res/img/products/thumb/73942/image_1.jpg",
"https://s3-us-west-2.amazonaws.com/fdmarketplace/res/img/products/thumb/73942/image_2.jpg",
"https://s3-us-west-2.amazonaws.com/fdmarketplace/res/img/products/thumb/73942/image_3.jpg",
"https://s3-us-west-2.amazonaws.com/fdmarketplace/res/img/products/thumb/73942/image_4.jpg",
"https://s3-us-west-2.amazonaws.com/fdmarketplace/res/img/products/thumb/73942/image_5.jpg"
]
}]
This endpoint retrieves a list of “included products” that come with any given product. This may include things such as built-in hardware and accessories and/or software that comes with it.
HTTP Request
GET /marketplace/v1/products/{productId}/includes
In the URL, use the productId as it was returned in the response of the GET Products API.
| Parameter | Required | Data Type | Default | Description |
|---|---|---|---|---|
| no input |
Response
The endpoint returns an array of objects, each representing an included product. The following parameters are in each object returned.
| Parameter | Data Type | Description |
|---|---|---|
| id | long | Unique identifier for rows (First Data’s internal record). |
| productId | long | Numeric value that uniquely identifies a product (canonical identifier). |
| supplierProductName | string | Name of the product as given by the source (supplier). Use productName in user interface. |
| supplierName | string | Supplier name. |
| productType | string | Indicates the behavior of the product, or when the merchant is charged a fee in case of “Processing/Pricing” products. See list of possible values here. |
| productName | string | Name of product to be used in the user interface. |
| productShortDescription | string | A short description of the product which can be used to display brief information in the Product List interface. |
| productLongDescription | string | A longer, more detailed description of the product, which should be used in the interface showing detailed information about the product. |
| showoncart | boolean | Flag to provide guidance on which products should be visibly displayed in the Shopping Cart after being selected. |
| price | float | Product price in USD. |
| productWithOptions | boolean | This indicates if this product has “options” (child products) that the user can select/add to cart individually. |
| pinPad | boolean | Indicates if a debit PIN pad is included with the product. true: PIN pad is included. false: PIN pad is not included. |
| imageUrls | array | Array of public URLs (string type) of up to 5 pairs images associated with the product. Images in /large/ directory are full size versions of smaller thumbnails with the same name in /thumb/ directory. |
GET Product/Specs
# Don't forget to add your HMAC Authorization Headers
endpoint = "/marketplace/v1/products/74042/specs"
r = requests.get(url + endpoint, headers=headers)
print(r)
# Don't forget to add your HMAC Authorization Headers
ENDPOINT="$URL/marketplace/v1/products/74042/specs"
curl -X GET -H "date: $DATE" -H "Authorization: $HMAC_AUTH" $ENDPOINT
// Don't forget to add your HMAC Authorization Headers
var options = {
method: 'GET',
url: url + '/marketplace/v1/products/74042/specs',
headers: getAuthenticationHeaders()
};
request(options, function (error, response, body) {
if (error) throw new Error(error);
console.log(response);
});
// Don't forget to add your HMAC Authorization Headers
HttpResponse response = null;
try {
response = doGet("/marketplace/v1/products/74042/specs");
int statusCode = response.getStatusLine().getStatusCode();
String response_string = EntityUtils.toString(response.getEntity());
JSONObject json = new JSONObject(response_string);
System.out.println("json:" + json.toString());
} catch (Exception e) {
e.printStackTrace();
}
<?php
# Don't forget to add your HMAC Authorization Headers
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url . "/marketplace/v1/products/74042/specs");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
$res = curl_exec($ch);
echo($res);
?>
The above command returns JSON structured like this:
{
"Materials": [
"Display: Antimicrobial Corning Gorilla Glass"
],
"Weight": [
"device: 2.3 lbs",
"device + hub: 2.6 lbs"
],
"Internet Connectivity": [
"3G (Pentaband HSPA+): requires data plan — bring your own or use the one provided by Clover.",
"Wi-Fi (802.11a/b/g/n wireless)",
"Ethernet"
],
"Screen Size": [
"7\", 1280 px x 800 px"
],
"Power Source": [
"External power adapter with DC input"
],
"Overall Dimensions": [
"D: 3.73\"",
"W: 8.0\"",
"H: 6.47\""
],
"Payments": [
"EMV chip card reader",
"NFC reader (EMV compliant)",
"3-Track Magstripe reader"
]
}
This endpoint retrieves a list of technical specifications for any given product. This may include information such as height and weight as well as the materials the product is made of in the case of a hardware type product.
Request
GET /marketplace/v1/products/{productId}/specs
In the URL, use the productId as it was returned in the response of the GET Products API.
| Parameter | Required | Data Type | Default | Description |
|---|---|---|---|---|
| no input |
Response
The endpoint returns an object with arrays, each representing a “line” in the specification. Each “line” array may contain multiple lines of specifications as strings.
| Parameter | Data Type | Description |
|---|---|---|
| specifications | array | The specifications are returned as an array of objects. Each specification object contains a keyword and array pairs of product specifications such as “weight” etc. |
GET Product/Recommended
# Don't forget to add your HMAC Authorization Headers
endpoint = "/marketplace/v1/products/74042/recommended"
r = requests.get(url + endpoint, headers=headers)
print(r)
# Don't forget to add your HMAC Authorization Headers
ENDPOINT="$URL/marketplace/v1/products/74042/recommended"
curl -X GET -H "date: $DATE" -H "Authorization: $HMAC_AUTH" $ENDPOINT
// Don't forget to add your HMAC Authorization Headers
var options = {
method: 'GET',
url: url + '/marketplace/v1/products/74042/recommended',
headers: getAuthenticationHeaders()
};
request(options, function (error, response, body) {
if (error) throw new Error(error);
console.log(response);
});
// Don't forget to add your HMAC Authorization Headers
HttpResponse response = null;
try {
response = doGet("/marketplace/v1/products/74042/recommended");
int statusCode = response.getStatusLine().getStatusCode();
String response_string = EntityUtils.toString(response.getEntity());
System.out.println("json:" + response_string);
} catch (Exception e) {
e.printStackTrace();
}
<?php
# Don't forget to add your HMAC Authorization Headers
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url . "/marketplace/v1/products/74042/recommended");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
$res = curl_exec($ch);
echo($res);
?>
The above command returns JSON structured like this (partial response):
[{
"id": 95870,
"productId": 67664,
"supplierProductName": "CLVCDR",
"supplierName": "MAMA",
"productType": "ACCES",
"productName": "Cash Drawer",
"productShortDescription": "Each Clover Station comes with a matching cash drawer. But with all the money you'll be making, you may need an extra drawer in which to stash your cash.",
"productLongDescription": "Each Clover Station comes with a matching cash drawer. But with all the money you'll be making, you may need an extra drawer in which to stash your cash.",
"showoncart": true,
"price": 50,
"productWithOptions": false,
"pinPad": false,
"imageUrls": [
"https://s3-us-west-2.amazonaws.com/fdmarketplace/res/img/products/large/67664/image_1.jpg",
"https://s3-us-west-2.amazonaws.com/fdmarketplace/res/img/products/thumb/67664/image_1.jpg"
]
}, {
"id": 96507,
"productId": 76002,
"supplierProductName": "AA110B",
"supplierName": "MAMA",
"productType": "ACCES",
"productName": "Clover Merchant Keypad",
"productShortDescription": "Engage your customers while they pay on Clover Mini, as you control the process from Clover Merchant Keypad. Quickly switch between taking payments, issuing card refunds, and authorizing cards for later payments while presenting customers w",
"productLongDescription": "Engage your customers while they pay on Clover Mini, as you control the process from Clover Merchant Keypad. Quickly switch between taking payments, issuing card refunds, and authorizing cards for later payments while presenting customers with Clover Mini as a friendly and modern payment display.",
"showoncart": true,
"price": 79,
"productWithOptions": false,
"pinPad": false,
"imageUrls": [
"https://s3-us-west-2.amazonaws.com/fdmarketplace/res/img/products/large/76002/image_1.jpg",
"https://s3-us-west-2.amazonaws.com/fdmarketplace/res/img/products/large/76002/image_2.jpg",
"https://s3-us-west-2.amazonaws.com/fdmarketplace/res/img/products/thumb/76002/image_1.jpg",
"https://s3-us-west-2.amazonaws.com/fdmarketplace/res/img/products/thumb/76002/image_2.jpg"
]
}]
This endpoint retrieves all Recommended Products for any given product. For example, a terminal system may have items like a weight scale and kitchen printer as its Recommended Products.
Request
GET /marketplace/v1/products/{productId}/recommended
In the URL, use the productId as it was returned in the response of the GET Products API.
| Parameter | Required | Data Type | Default | Description |
|---|---|---|---|---|
| no input |
Response
The endpoint returns an array of objects, each representing a Recommended Product. The following parameters are in each object returned.
| Parameter | Data Type | Description |
|---|---|---|
| id | long | Unique identifier for rows (First Data’s internal record). |
| productId | long | Numeric value that uniquely identifies a product (canonical identifier). |
| supplierProductName | string | Name of the product as given by the source (supplier). Use productName in user interface. |
| supplierName | string | Supplier name. |
| productType | string | Indicates the behavior of the product, or when the merchant is charged a fee in case of “Processing/Pricing” products. See list of possible values here. |
| productName | string | Name of product to be used in the user interface. |
| productShortDescription | string | A short description of the product which can be used to display brief information in the Product List interface. |
| productLongDescription | string | A longer, more detailed description of the product, which should be used in the interface showing detailed information about the product. |
| showoncart | boolean | Flag to provide guidance on which products should be visibly displayed in the Shopping Cart after being selected. |
| price | float | Product price in USD. |
| productWithOptions | boolean | Indicates if this product has “options” (child products) that the user can select/add to cart individually. |
| pinPad | boolean | Indicates if a debit PIN pad is included with the product. true: PIN pad is included. false: PIN pad is not included. |
| imageUrls | array | Array of public URLs (string type) of up to 5 pairs images associated with the product. Images in /large/ directory are full size versions of smaller thumbnails with the same name in /thumb/ directory. |
GET Product/FAQ
# Don't forget to add your HMAC Authorization Headers
endpoint = "/marketplace/v1/products/74042/faq"
r = requests.get(url + endpoint, headers=headers)
print(r)
# Don't forget to add your HMAC Authorization Headers
ENDPOINT="$URL/marketplace/v1/products/74042/faq"
curl -X GET -H "date: $DATE" -H "Authorization: $HMAC_AUTH" $ENDPOINT
// Don't forget to add your HMAC Authorization Headers
var options = {
method: 'GET',
url: url + '/marketplace/v1/products/74042/faq',
headers: getAuthenticationHeaders()
};
request(options, function (error, response, body) {
if (error) throw new Error(error);
console.log(response);
});
// Don't forget to add your HMAC Authorization Headers
HttpResponse response = null;
try {
response = doGet("/marketplace/v1/products/74042/faq");
int statusCode = response.getStatusLine().getStatusCode();
String response_string = EntityUtils.toString(response.getEntity());
System.out.println("json:" + response_string);
} catch (Exception e) {
e.printStackTrace();
}
<?php
# Don't forget to add your HMAC Authorization Headers
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url . "/marketplace/v1/products/74042/faq");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
$res = curl_exec($ch);
echo($res);
?>
The above command returns JSON structured like this:
[{
"header": "Printer Paper Sizes?",
"shortAnswer": "The Clover Station Printer takes 3 1/8” X 230’ thermal paper rolls.",
"url": "https://gyftteam.atlassian.net/wiki/pages/viewpage.action?pageId=57933826",
"sortId": 1
}, {
"header": "Which weight scales are supported by Clover?",
"shortAnswer": "Clover supports the CAS SW-20 Weight Scale. In order to connect the scale to your Clover Station or Clover Mini, you will need a custom cable that comes bundled with the scale when purchased from your Clover provider.",
"url": "https://gyftteam.atlassian.net/wiki/pages/viewpage.action?pageId=55378004",
"sortId": 2
}, {
"header": "Does Clover support layaway?",
"shortAnswer": "Clover does not currently support layaway directly on Register app register-app-icon. Third party apps may support layaway in the future.",
"url": "https://gyftteam.atlassian.net/wiki/pages/viewpage.action?pageId=57212991",
"sortId": 3
}, {
"header": "Does Clover integrate with E-commerce?",
"shortAnswer": "Our third party apps E-commerce solutions for you...",
"url": "https://gyftteam.atlassian.net/wiki/pages/viewpage.action?pageId=57212992",
"sortId": 4
}]
This endpoint retrieves a list of frequently asked questions for any given product.
Request
GET /marketplace/v1/products/{productId}/faq
In the URL, use the productId as it was returned in the response of the GET Products API.
| Parameter | Required | Data Type | Default | Description |
|---|---|---|---|---|
| no input |
Response
The endpoint returns an array of objects, each representing a FAQ entry. The following parameters are in each object returned.
| Parameter | Data Type | Description |
|---|---|---|
| header | string | Question. |
| shortAnswer | string | Brief answer to the question that can be displayed in the user interface as a “snippet” of the whole answer. |
| url | string | Public URL of the detailed knowledge base article, explaining the answer to this question. |
| sortId | integer | The index of the FAQ entry to define the display order in the user interface. |
POST Cart/Validate v1
# Don't forget to add your HMAC Authorization Headers
data = {
"merchant": "",
"cartdetails": [
{ "productId": 67702 },
{ "productId": 10013 },
{ "productId": 10017 },
{ "productId": 10021 },
{ "productId": 10023 }
],
"transactionInfo": {
"mccTypes": "",
"mcc": "null",
"annualVolume": "null",
"averageTicket": "null",
"amexVolume": "null",
"amexMemberId": "null",
"highestTicket": "null",
"category": "null"
}
}
endpoint = "/marketplace/v1/cart/validate"
r = requests.post(url + endpoint, json=data, headers=headers)
print(r)
# Don't forget to add your HMAC Authorization Headers
ENDPOINT="$URL/marketplace/v1/cart/validate"
curl -X POST -H "date: $DATE" -H "Authorization: $HMAC_AUTH" -H "Content-Type:application/json" --data '{
"merchant":"",
"cartdetails":[
{"productId":67702},
{"productId":10013},
{"productId":10017},
{"productId":10021},
{"productId":10023}
],
"transactionInfo":{
"mccTypes":"",
"mcc":null,
"annualVolume":null,
"averageTicket":null,
"amexVolume":null,
"highestTicket":null,
"category":null
}
}' $ENDPOINT
// Don't forget to add your HMAC Authorization Headers
var options = {
method: 'POST',
url: url + '/marketplace/v1/cart/validate',
headers: getAuthenticationHeaders(),
body: {
merchant: "",
cartdetails: [
{ productId: 67702 },
{ productId: 10013 },
{ productId: 10017 },
{ productId: 10021 },
{ productId: 10023 }
],
transactionInfo: {
mccTypes: "",
mcc: null,
annualVolume: null,
averageTicket: null,
amexVolume: null,
amexMemberId: null,
highestTicket: null,
category: null
}
},
json: true
};
request(options, function (error, response, body) {
if (error) throw new Error(error);
console.log(response);
});
// Don't forget to add your HMAC Authorization Headers
try {
String jsonString = "{\n" +
" \"merchant\": \"\",\n" +
" \"cartdetails\": [{\n" +
" \"productId\": 67702\n" +
" }, {\n" +
" \"productId\": 10013\n" +
" }, {\n" +
" \"productId\": 10017\n" +
" }, {\n" +
" \"productId\": 10021\n" +
" }, {\n" +
" \"productId\": 10023\n" +
" }],\n" +
" \"transactionInfo\": {\n" +
" \"mccTypes\": \"\",\n" +
" \"mcc\": null,\n" +
" \"annualVolume\": null,\n" +
" \"averageTicket\": null,\n" +
" \"amexVolume\": null,\n" +
" \"amexMemberId\": null,\n" +
" \"highestTicket\": null,\n" +
" \"category\": null\n" +
" }\n" +
"}";
StringEntity payload = new StringEntity(jsonString);
HttpResponse response = doPost("/marketplace/v1/cart/validate", payload);
int statusCode = response.getStatusLine().getStatusCode();
String response_string = EntityUtils.toString(response.getEntity());
JSONObject json = new JSONObject(response_string);
System.out.println("json:" + json.toString());
} catch (Exception e) {
e.printStackTrace();
}
<?php
# Don't forget to add your HMAC Authorization Headers
$data = array (
'merchant' => '',
'cartdetails' =>
array (
0 =>
array (
'productId' => 74862,
),
1 =>
array (
'productId' => 10014,
),
2 =>
array (
'productId' => 10018,
),
),
'transactionInfo' =>
array (
'mccTypes' => 'Restaurant Beverage and Food',
'mcc' => '5812',
'annualVolume' => 1000,
'averageTicket' => 1,
'amexVolume' => NULL,
'highestTicket' => 2,
'category' => 'RESTAURANT',
),
);
$data_json = json_encode($data);
$headers = array(
'date: ' . $date,
'Authorization: ' . $hmacAuth,
'Content-Type: application/json',
'Content-Length: ' . strlen($data_json)
);
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url . "/marketplace/v1/cart/validate");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data_json);
$res = curl_exec($ch);
echo($res);
?>
Example payload:
cartValidate.json
{
"merchant": "",
"cartdetails": [
{ "productId": 67702 },
{ "productId": 10013 },
{ "productId": 10017 },
{ "productId": 10021 },
{ "productId": 10023 }
],
"transactionInfo": {
"mccTypes": "",
"mcc": null,
"annualVolume": null,
"averageTicket": null,
"amexVolume": null,
"amexMemberId": null,
"highestTicket": null,
"category": null
}
}
The above command returns JSON structured like this:
Success response
{
"iscartvalid":true
}
Error response
{
"iscartvalid": false,
"carterrors": [{
"errormessage": "Payment Processing",
"errortype": "ACQUIRING"
}]
}
This endpoint can be used for validation of the items in the Shopping Cart, such as products or product types required to be bought together, etc.
Request
POST /marketplace/v1/cart/validate
The endpoint takes a JSON object as input. Refer to the example request for the JSON structure of the request payload.
| Parameter | Required | Data Type | Description |
|---|---|---|---|
| cartdetails | ✔ | array | Collection of productId representing each product in the the Shopping Cart. |
| productId | ✔ | long | productId: Numeric value that uniquely identifies each product (canonical identifier), as returned in the GET Products endpoint. |
| transactionInfo | object | Transactions information used to determine pricing. Contains mccTypes, mcc, annualVolume, averageTicket, highestTicket and category. | |
| mccTypes | string | “Merchant Category Code” MCC description (refer to: GET MCC/Category). | |
| mcc | string | MCC Code (refer to: GET MCC/Category). | |
| annualVolume | double | Actual or estimated annual credit card transaction volume in USD. | |
| averageTicket | double | Actual or estimated average ticket price in USD. | |
| highestTicket | double | Actual or estimated highest ticket price in USD. | |
| category | string | Category name eg: "RETAIL/MOTO" (refer to: GET Categories). |
Response
The endpoint returns an object representing the validation result. The following parameters may be in each object returned.
| Parameter | Type | Description |
|---|---|---|
| iscartvalid | boolean | Validation result: true Cart is valid, false Cart is invalid. |
| carterrors | array | If iscartvalid is false, the carterrors is returned as an array of objects where each object represents an error and contains an errortype and errormessage. See list of possible values below. |
| errortype | string | String used to filter the cart error products. |
| errormessage | string | Error Message you can display in the user interface to notify the user of the error. |
Possible values for carterrors
The errortype together with errormessage in the carterrors array provides filtering and guidance on what needs to be modified in the Shopping Cart.
| errortype | errormessage | Suggested Behavior |
|---|---|---|
"ACQUIRING" | “Payment Processing” | Provide notification to user that a “Payment Processing” product is required. |
"PIN PAD" | “Pinpad” | Provide notification to user that a “PIN Pad” product is required. |
"TERM" | “POS or Gateway” | Provide notification to user that a “POS or Gateway” is required. |
"Discover" | “Discover is required for PayPal” | Provide notification to user that a “Discover is required for PayPal” payment processing option. |
"Debit" | “Debit cannot be on boarded with selected equipment” | Provide notification to user that a “Debit cannot be on boarded with selected equipment”. |
POST Cart/Validate v2
# Don't forget to add your HMAC Authorization Headers
data = {
"cartdetails": [{
"productId": "67702",
"category": "RETAIL"
}, {
"productId": "10013",
"category": "RETAIL"
}]
}
endpoint = "/marketplace/v2/cart/validate"
r = requests.post(url + endpoint, json=data, headers=headers)
print(r)
# Don't forget to add your HMAC Authorization Headers
ENDPOINT="$URL/marketplace/v2/cart/validate"
curl -X POST -H "date: $DATE" -H "Authorization: $HMAC_AUTH" -H "Content-Type:application/json" --data '{
"cartdetails": [{
"productId": "67702",
"category": "RETAIL"
}, {
"productId": "10013",
"category": "RETAIL"
}]
}
' $ENDPOINT
// Don't forget to add your HMAC Authorization Headers
var options = {
method: 'POST',
url: url + '/marketplace/v2/cart/validate',
headers: getAuthenticationHeaders(),
body: {
"cartdetails": [{
"productId": "67702",
"category": "RETAIL"
}, {
"productId": "10013",
"category": "RETAIL"
}]
}
,
json: true
};
request(options, function (error, response, body) {
if (error) throw new Error(error);
console.log(response);
});
// Don't forget to add your HMAC Authorization Headers
try {
String jsonString = "{\n" +
" \"cartdetails\": [{\n" +
" \"productId\": 67702,\n" +
" \"category\": "RETAIL"\n" +
" }, {\n" +
" \"productId\": 10013,\n" +
" \"category\": "RETAIL"\n" +
" }]\n" +
"}";
StringEntity payload = new StringEntity(jsonString);
HttpResponse response = doPost("/marketplace/v2/cart/validate", payload);
int statusCode = response.getStatusLine().getStatusCode();
String response_string = EntityUtils.toString(response.getEntity());
JSONObject json = new JSONObject(response_string);
System.out.println("json:" + json.toString());
} catch (Exception e) {
e.printStackTrace();
}
<?php
# Don't forget to add your HMAC Authorization Headers
$data = array (
'cartdetails' =>
array (
0 =>
array (
'productId' => 74862,
'category' => 'RETAIL',
),
1 =>
array (
'productId' => 10014,
'category' => 'RETAIL'
),
),
);
$data_json = json_encode($data);
$headers = array(
'date: ' . $date,
'Authorization: ' . $hmacAuth,
'Content-Type: application/json',
'Content-Length: ' . strlen($data_json)
);
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url . "/marketplace/v2/cart/validate");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data_json);
$res = curl_exec($ch);
echo($res);
?>
Example payload:
cartValidate.json
{
"cartdetails": [{
"productId": "67702",
"category": "RETAIL"
}, {
"productId": "10013",
"category": "RETAIL"
}]
}
{
"merchant": "",
"cartdetails": [{
"productId": "67702",
"category": "RETAIL"
}, {
"productId": "10013",
"category": "RETAIL"
}],
"transactionInfo": {
"mccTypes": "",
"mcc": null,
"annualVolume": null,
"averageTicket": null,
"amexVolume": null,
"amexMemberId": null,
"highestTicket": null,
"category": null
}
}
The above command returns JSON structured like this:
Success response
{
"iscartvalid":true
}
Error response
{
"iscartvalid": false,
"carterrors": [{
"errormessage": "Payment Processing",
"errortype": "ACQUIRING"
}]
}
This endpoint can be used for validation of the items in the Shopping Cart, such as products or product types required to be bought together, etc.
Request
POST /marketplace/v2/cart/validate
The endpoint takes a JSON object as input. Refer to the example request for the JSON structure of the request payload.
| Parameter | Required | Data Type | Description |
|---|---|---|---|
| merchant | string | Merchant | |
| cartdetails | ✔ | array | Collection of productId representing each product in the the Shopping Cart. |
| productId | ✔ | long | productId: Numeric value that uniquely identifies each product (canonical identifier), as returned in the GET Products endpoint. |
| category | ✔ | string | Category name eg: "RETAIL/MOTO" (refer to: GET Categories) the product belongs to. |
| transactionInfo | object | Transactions information used to determine pricing. Contains mccTypes, mcc, annualVolume, averageTicket, highestTicket and category. | |
| mccTypes | string | “Merchant Category Code” MCC description (refer to: GET MCC/Category). | |
| mcc | string | MCC Code (refer to: GET MCC/Category). | |
| mccAdditionalDetails | string | ||
| annualVolume | double | Actual or estimated annual credit card transaction volume in USD. | |
| averageTicket | double | Actual or estimated average ticket price in USD. | |
| highestTicket | double | Actual or estimated highest ticket price in USD. | |
| category | string | Category name eg: "RETAIL/MOTO" (refer to: GET Categories). |
Response
The endpoint returns an object representing the validation result. The following parameters may be in each object returned.
| Parameter | Type | Description |
|---|---|---|
| iscartvalid | boolean | Validation result: true Cart is valid, false Cart is invalid. |
| carterrors | array | If iscartvalid is false, the carterrors is returned as an array of objects where each object represents an error and contains an errortype and errormessage. See list of possible values below. |
| errortype | string | String used to filter the cart error products. |
| errormessage | string | Error Message you can display in the user interface to notify the user of the error. |
| errorOrder | string | The order in which error should be shown, used in case of multiple errors. |
| productType | string | Product type. |
Possible values for carterrors
The errortype together with errormessage in the carterrors array provides filtering and guidance on what needs to be modified in the Shopping Cart.
| errortype | errormessage | Suggested Behavior |
|---|---|---|
"ACQUIRING" | “Payment Processing” | Provide notification to user that a “Payment Processing” product is required. |
"PIN PAD" | “Pinpad” | Provide notification to user that a “PIN Pad” product is required. |
"TERM" | “POS or Gateway” | Provide notification to user that a “POS or Gateway” is required. |
"Discover" | “Discover is required for PayPal” | Provide notification to user that a “Discover is required for PayPal” payment processing option. |
"Debit" | “Debit cannot be on boarded with selected equipment” | Provide notification to user that a “Debit cannot be on boarded with selected equipment”. |
GET Industry
# Don't forget to add your HMAC Authorization Headers
endpoint = url + "/marketplace/v1/categories/RETAIL/industries"
r = requests.get(endpoint, headers=headers)
print(r)
# Don't forget to add your HMAC Authorization Headers
ENDPOINT="$URL/marketplace/v1/categories/RETAIL/industries"
curl -X GET -H "date: $DATE" -H "Authorization: $HMAC_AUTH" $ENDPOINT
// Don't forget to add your HMAC Authorization Headers
var options = {
method: 'GET',
url: url + '/marketplace/v1/categories/RETAIL/industries',
headers: getAuthenticationHeaders()
};
request(options, function (error, response, body) {
if (error) throw new Error(error);
console.log(response);
});
// Don't forget to add your HMAC Authorization Headers
HttpResponse response = null;
try {
response = doGet("/marketplace/v1/categories/RETAIL/industries");
int statusCode = response.getStatusLine().getStatusCode();
String response_string = EntityUtils.toString(response.getEntity());
System.out.println("json:" + response_string);
} catch (Exception e) {
e.printStackTrace();
}
<?php
# Don't forget to add your HMAC Authorization Headers
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url . "/marketplace/v1/categories/RETAIL/industries");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
$res = curl_exec($ch);
echo($res);
?>
The above command returns JSON structured like this:
[{
"industryDescription": "Medical Services and Doctors"
}, {
"industryDescription": "Restaurant Beverage and Food"
}, {
"industryDescription": "Home and Garden (Hardware, Florists, Home Supply)"
}, {
"industryDescription": "Contractors (Plumbers, Electricians, etc)"
}, {
"industryDescription": "Business to Business - Wholesale (Services)"
}]
This endpoint retrieves the broad industry description (industryDescription) labels for a given business category. Result values returned by this endpoint can be used in the request of the GET MCC/Industry endpoint.
Request
GET /marketplace/v1/categories/{categoryName}/industries
In the URL, use the name attribute of any selected business category to get a list of industries.
| Parameter | Required | Data Type | Default | Description |
|---|---|---|---|---|
| no input |
Response
This endpoint returns an array of objects each containing a string. These objects represent the industry.
| Parameter | Type | Description |
|---|---|---|
| industryDescription | string | Label/description for broad industry inside of the business category. |
GET MCC/Industry
# Don't forget to add your HMAC Authorization Headers
endpoint = url + "/marketplace/v1/categories/RETAIL/industries/Restaurant%20Beverage%20and%20Food/merchantcategorycodes"
r = requests.get(endpoint, headers=headers)
print(r)
# Don't forget to add your HMAC Authorization Headers
ENDPOINT="$URL/marketplace/v1/categories/RETAIL/industries/Restaurant%20Beverage%20and%20Food/merchantcategorycodes"
curl -X GET -H "date: $DATE" -H "Authorization: $HMAC_AUTH" $ENDPOINT
// Don't forget to add your HMAC Authorization Headers
var options = {
method: 'GET',
url: url + '/marketplace/v1/categories/RETAIL/industries/Restaurant%20Beverage%20and%20Food/merchantcategorycodes',
headers: getAuthenticationHeaders()
};
request(options, function (error, response, body) {
if (error) throw new Error(error);
console.log(response);
});
// Don't forget to add your HMAC Authorization Headers
HttpResponse response = null;
try {
response = doGet("/marketplace/v1/categories/RETAIL/industries/Restaurant%20Beverage%20and%20Food/merchantcategorycodes");
int statusCode = response.getStatusLine().getStatusCode();
String response_string = EntityUtils.toString(response.getEntity());
System.out.println("json:" + response_string);
} catch (Exception e) {
e.printStackTrace();
}
<?php
# Don't forget to add your HMAC Authorization Headers
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url . "/marketplace/v1/categories/RETAIL/industries/Restaurant%20Beverage%20and%20Food/merchantcategorycodes");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
$res = curl_exec($ch);
echo($res);
?>
The above command returns JSON structured like this (partial response):
[{
"mcc": "0744",
"mccList": "Champagne Producers"
},
{
"mcc": "5411",
"mccList": "Grocery Supermarkets"
},
{
"mcc": "5422",
"mccList": "Freezer and Locker Meat Provisioners"
},
{
"mcc": "5441",
"mccList": "Candy, Nut and Confectionery Stores"
},
{
"mcc": "5451",
"mccList": "Dairy Products Stores"
}]
This endpoint retrieves the MCC - Merchant Category Code(s) - for a given industry.
Request
GET /marketplace/v1/categories/{categoryName}/industries/{industryDescription}/merchantcategorycodes/
In the URL, use the name attribute of the business category and an industryDescription, as returned in the GET Industry.
| Parameter | Required | Data Type | Default | Description |
|---|---|---|---|---|
| no input |
Response
This endpoint returns an array of objects each containing two strings. Each of these objects represent one MCC code and contain the numerical code (mcc) and the associated description/label (mccList).
| Parameter | Type | Description |
|---|---|---|
| mcc | string | MCC (Merchant Category Code) is a four-digit number used to classify industry areas. The MCC is assigned by the acquiring financial institution when a merchant initially begins accepting credit cards. |
| mccList | string | Label/description for the MCC code, which can be displayed in the user interface to help the user make a selection. |
POST Pricing/Equipment v1
# Don't forget to add your HMAC Authorization Headers
data = {
"transactionInfo": {
"mccTypes": "Clothing and Shoes",
"mcc": "5611",
"annualVolume": 100000,
"averageTicket": 80,
"highestTicket": 400,
"category": "RETAIL"
},
"products": [{
"id": 67702,
"name": "Clover Mini 3G/WiFi",
"price": 649,
"type": "Clover Mini 3G/WiFi",
"term": "P",
"qty": 1
}]
}
endpoint = "/marketplace/v1/pricing/equipment"
r = requests.post(url + endpoint, json=data, headers=headers)
print(r)
# Don't forget to add your HMAC Authorization Headers
ENDPOINT="$URL/marketplace/v1/pricing/equipment"
curl -X POST -H "date: $DATE" -H "Authorization: $HMAC_AUTH" -H "Content-Type:application/json" --data '{
"transactionInfo": {
"mccTypes": "Clothing and Shoes",
"mcc": "5611",
"annualVolume": 100000,
"averageTicket": 80,
"highestTicket": 400,
"category": "RETAIL"
},
"products": [{
"id": 74042,
"name": "Clover Mini 3G/WiFi",
"price": 649,
"type": "Clover Mini 3G/WiFi",
"term": "P",
"qty": 1
}]
}' $ENDPOINT
// Don't forget to add your HMAC Authorization Headers
var options = {
method: 'POST',
url: url + '/marketplace/v1/pricing/equipment',
headers: getAuthenticationHeaders(),
body: {
"transactionInfo": {
"mccTypes": "Clothing and Shoes",
"mcc": "5611",
"annualVolume": 100000,
"averageTicket": 80,
"highestTicket": 400,
"category": "RETAIL"
},
"products": [{
"id": 74042,
"name": "Clover Mini 3G/WiFi",
"price": 649,
"type": "Clover Mini 3G/WiFi",
"term": "P",
"qty": 1
}]
},
json: true
};
request(options, function (error, response, body) {
if (error) throw new Error(error);
console.log(response);
});
// Don't forget to add your HMAC Authorization Headers
try {
String jsonString = "{\n" +
" \"transactionInfo\": {\n" +
" \"mccTypes\": \"Clothing and Shoes\",\n" +
" \"mcc\": \"5611\",\n" +
" \"annualVolume\": 100000,\n" +
" \"averageTicket\": 80,\n" +
" \"highestTicket\": 400,\n" +
" \"category\": \"RETAIL\"\n" +
" },\n" +
" \"products\": [{\n" +
" \"id\": 67702,\n" +
" \"name\": \"Clover Station W/ Cash Drawer\",\n" +
" \"price\": 1299,\n" +
" \"type\": \"Clover Station W/ Cash Drawer\",\n" +
" \"term\": \"P\",\n" +
" \"qty\": 1\n" +
" }]\n" +
"}";
StringEntity payload = new StringEntity(jsonString);
HttpResponse response = doPost("/marketplace/v1/pricing/equipment", payload);
int statusCode = response.getStatusLine().getStatusCode();
String response_string = EntityUtils.toString(response.getEntity());
JSONArray json = new JSONArray(response_string);
System.out.println("json:" + json.toString());
} catch (Exception e) {
e.printStackTrace();
}
<?php
# Don't forget to add your HMAC Authorization Headers
$data = array (
'transactionInfo' =>
array (
'mccTypes' => 'Clothing and Shoes',
'mcc' => '5611',
'annualVolume' => 100000,
'averageTicket' => 80,
'highestTicket' => 400,
'category' => 'RETAIL',
),
'products' =>
array (
0 =>
array (
'id' => 74042,
'name' => 'Clover Mini 3G/WiFi',
'price' => 649,
'type' => 'Clover Mini 3G/WiFi',
'term' => 'P',
'qty' => '1',
),
),
);
$data_json = json_encode($data);
$headers = array(
'date: ' . $date,
'Authorization: ' . $hmacAuth,
'Content-Type: application/json',
'Content-Length: ' . strlen($data_json)
);
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url . "/marketplace/v1/pricing/equipment");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data_json);
$res = curl_exec($ch);
echo($res);
?>
Example payload:
equipment.json
{
"transactionInfo": {
"mccTypes": "Clothing and Shoes",
"mcc": "5611",
"annualVolume": 100000,
"averageTicket": 80,
"highestTicket": 400,
"category": "RETAIL"
},
"products": [{
"id": 74042,
"name": "Clover Mini 3G/WiFi",
"price": 649,
"type": "Clover Mini 3G/WiFi",
"term": "P",
"qty": "1"
}]
}
The above command returns JSON structured like this (partial response):
[{
"productId": 74042,
"feeMin": 0,
"feeDefault": 0,
"feeMax": 0,
"defaultAmt": 649,
"minAmt": 499,
"maxAmt": 746,
"quantity": 1,
"rateMin": 0,
"rateDefault": 0,
"rateMax": 0,
"productName": "Clover Mini 3G/WiFi",
"productType": "IBUNDLE",
"isOverride": false,
"override": false,
"showoncart": false,
"purchaseType": "P",
"occurrence": {
"type": "Onetime_Product"
}
}, {
"pricingDetailId": 160,
"pricingTypeId": 10000,
"productId": 64262,
"description": "32I_APP_FEE",
"feeMin": 0,
"feeDefault": 0,
"feeMax": 0,
"defaultAmt": 149,
"minAmt": 0,
"maxAmt": 500,
"quantity": 1,
"rateMin": 0,
"rateDefault": 0,
"rateMax": 0,
"productName": "Application Fee",
"productType": "APP_FEE",
"isOverride": false,
"override": false,
"showoncart": true,
"occurrence": {
"type": "Onetime_Fee"
}
}]
This endpoint can be used to retrieve “pricing” for any given product (or collection of products) such as the product’s own pricing, pricing for products included, and any associated fees - each considered a “Pricing Product.”
Request
POST /marketplace/v1/pricing/equipment
The endpoint takes a JSON object as input. Refer to the “Example request payload” for the JSON structure of the request payload object.
| Parameter | Required | Data Type | Description |
|---|---|---|---|
| products | ✔ | array | Array of objects each (representing a product) contains id, name, price, type, term and qty. |
| id | ✔ | long | productId: Numeric value that uniquely identifies each product (canonical identifier), as returned in the GET Products endpoint. |
| name | ✔ | string | productName: Product name. |
| price | ✔ | float | Unit price for a product in USD. |
| type | ✔ | string | productType: Indicates the behavior of the Pricing Product, or when the merchant is charged a fee. See list of possible values here. |
| term | ✔ | string | purchaseType. See list of possible values here. |
| qty | ✔ | integer | Quantity selected. |
| transactionInfo | object | Transactions information used to determine pricing. Contains mccTypes, mcc, annualVolume, averageTicket, highestTicket and category. | |
| mccTypes | string | “Merchant Category Code” MCC description (refer to: GET MCC/Category). | |
| mcc | string | MCC Code (refer to: GET MCC/Category). | |
| annualVolume | double | Actual or estimated annual credit card transaction volume in USD. | |
| averageTicket | double | Actual or estimated average ticket price in USD. | |
| highestTicket | double | Actual or estimated highest ticket price in USD. | |
| category | string | Category name eg: "RETAIL/MOTO" (refer to: GET Categories). |
Response
This API returns an array of objects, each representing a “Pricing Product.” Each object contains the following keyword-value pairs.
Return Parameters in italic are used in our ISO program. They should be hidden from the user.
| Parameter | Data Type | Description |
|---|---|---|
| productId | integer | Numeric value that uniquely identifies a product (canonical identifier). |
| pricingDetailId | integer | Numeric value that uniquely identifies a Pricing Strategy. |
| pricingTypeId | integer | Numeric value that uniquely identifies a Pricing Type. |
| productName | string | The name of the Pricing Product that can be displayed in the user interface. |
| description | string | Short description of the product. |
| productType | string | Indicates the behavior of the Pricing Product, or when the merchant is charged this fee. See list of possible values here. |
| quantity | integer | Quantity of the Pricing Product to be added to the order. (Generally 1.) |
| defaultAmt | integer | Price/amount to be collected (usually as a one-time payment) in USD. |
| minAmt | integer | |
| maxAmt | integer | |
| feeDefault | integer | Fee charged per occurrence in USD. |
| feeMin | integer | |
| feeMax | integer | |
| rateDefault | integer | Percentage of transaction amount charged per occurrence. |
| rateMin | integer | |
| isOverride | boolean | |
| override | boolean | |
| showoncart | boolean | Flag to provide guidance on which products should be visibly displayed in the Shopping Cart. |
| occurrence | object | |
| type | string | Occurrence indicates the event the rate/fee/amount is charged: "Transaction": charged for every transaction, "Onetime_Product": charged once. i.e. Application fee, "Recurring": charged on a recurring basis, see productType for more information. |
| productAttribute | object | Contains name, value and domain. |
| name | string | Product attribute name. |
| value | string | Product attribute value. |
| domain | string | Domain like pricing. |
POST Pricing/Equipment v2
# Don't forget to add your HMAC Authorization Headers
data = {
"transactionInfo": {
"mccTypes": "Clothing and Shoes",
"mcc": "5611",
"mccAdditionalDetails": "",
"annualVolume": 23000,
"annualcardVolume": 100000,
"averageTicket": 80,
"highestTicket": 400,
"category": "RETAIL"
},
"cardNotPresent": 1,
"cartDetails": [
{
"productId": "67702",
"name": "Clover Mini 3G/WiFi",
"price": 649,
"type": "Terminal",
"term": "P",
"category": "RETAIL",
"qty": 1
}
]
}
endpoint = "/marketplace/v1/pricing/equipment"
r = requests.post(url + endpoint, json=data, headers=headers)
print(r)
# Don't forget to add your HMAC Authorization Headers
ENDPOINT="$URL/marketplace/v1/pricing/equipment"
curl -X POST -H "date: $DATE" -H "Authorization: $HMAC_AUTH" -H "Content-Type:application/json" --data '{
"transactionInfo": {
"mccTypes": "Clothing and Shoes",
"mcc": "5611",
"mccAdditionalDetails": "",
"annualVolume": 23000,
"annualcardVolume": 100000,
"averageTicket": 80,
"highestTicket": 400,
"category": "RETAIL"
},
"cardNotPresent": 1,
"cartDetails": [
{
"productId": "67702",
"name": "Clover Mini 3G/WiFi",
"price": 649,
"type": "Terminal",
"term": "P",
"category": "RETAIL",
"qty": 1
}
]
}' $ENDPOINT
// Don't forget to add your HMAC Authorization Headers
var options = {
method: 'POST',
url: url + '/marketplace/v1/pricing/equipment',
headers: getAuthenticationHeaders(),
body: {
"transactionInfo": {
"mccTypes": "Clothing and Shoes",
"mcc": "5611",
"mccAdditionalDetails": "",
"annualVolume": 23000,
"annualcardVolume": 100000,
"averageTicket": 80,
"highestTicket": 400,
"category": "RETAIL"
},
"cardNotPresent": 1,
"cartDetails": [
{
"productId": "67702",
"name": "Clover Mini 3G/WiFi",
"price": 649,
"type": "Terminal",
"term": "P",
"category": "RETAIL",
"qty": 1
}
]
}, json: true
};
request(options, function (error, response, body) {
if (error) throw new Error(error);
console.log(response);
});
// Don't forget to add your HMAC Authorization Headers
try {
String jsonString = "{\n" +
" \"transactionInfo\": {\n" +
" \"mccTypes\": \"Clothing and Shoes\",\n" +
" \"mcc\": \"5611\",\n" +
" \"annualVolume\": 100000,\n" +
" \"averageTicket\": 80,\n" +
" \"highestTicket\": 400,\n" +
" \"category\": \"RETAIL\"\n" +
" },\n" +
" \"cardNotPresent\": 1,\n" +
" \"cartDetails\": [\n" +
" {\n" +
" \"productId\": \"67702\",\n" +
" \"name\": \"Clover Mini 3G/WiFi\",\n" +
" \"price\": 649,\n" +
" \"type\": \"Terminal\",\n" +
" \"term\": \"P\",\n" +
" \"category\": \"RETAIL\",\n" +
" \"qty\": 1\n" +
" }\n" +
" ]\n" +
"}";
StringEntity payload = new StringEntity(jsonString);
HttpResponse response = doPost("/marketplace/v1/pricing/equipment", payload);
int statusCode = response.getStatusLine().getStatusCode();
String response_string = EntityUtils.toString(response.getEntity());
JSONArray json = new JSONArray(response_string);
System.out.println("json:" + json.toString());
} catch (Exception e) {
e.printStackTrace();
}
<?php
# Don't forget to add your HMAC Authorization Headers
$data = array (
'transactionInfo' =>
array (
'mccTypes' => 'Clothing and Shoes',
'mcc' => '5611',
'mccAdditionalDetails' => '',
'annualVolume' => 23000,
'annualcardVolume' => 100000,
'averageTicket' => 80,
'highestTicket' => 400,
'category' => 'RETAIL',
),
'cardNotPresent' => 1,
'cartDetails' =>
array (
0 =>
array (
'productId' => '67702',
'name' => 'Clover Mini 3G/WiFi',
'price' => 649,
'type' => 'Terminal',
'term' => 'P',
'category' => 'RETAIL',
'qty' => 1,
),
),
);
$data_json = json_encode($data);
$headers = array(
'date: ' . $date,
'Authorization: ' . $hmacAuth,
'Content-Type: application/json',
'Content-Length: ' . strlen($data_json)
);
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url . "/marketplace/v1/pricing/equipment");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data_json);
$res = curl_exec($ch);
echo($res);
?>
Example payload:
equipment.json
{
"transactionInfo": {
"mccTypes": "Clothing and Shoes",
"mcc": "5611",
"mccAdditionalDetails": "",
"annualVolume": 23000,
"annualcardVolume": 100000,
"averageTicket": 80,
"highestTicket": 400,
"category": "RETAIL"
},
"cardNotPresent": 1,
"cartDetails": [
{
"productId": "67702",
"name": "Clover Mini 3G/WiFi",
"price": 649,
"type": "Terminal",
"term": "P",
"category": "RETAIL",
"qty": 1
}
]
}
The above command returns JSON structured like this (partial response):
[{
"productId": "67702",
"feeMinAbsolute": 0,
"feeMin": 0,
"feeDefault": 0,
"feeMax": 0,
"feeMaxAbsolute": 0,
"minAmountAbsolute": 499,
"minAmt": 999,
"defaultAmt": 1599,
"maxAmt": 1840,
"maxAmountAbsolute": 1840,
"quantity": 1,
"rateMinAbsolute": 0,
"rateMin": 0,
"rateDefault": 0,
"rateMax": 0,
"rateMaxAbsolute": 0,
"productName": "Clover Station W/ Cash Drawer",
"productType": "IBUNDLE",
"isOverride": false,
"override": false,
"showoncart": false,
"purchaseType": "P",
"occurrence": {
"type": "Onetime_Product"
},
"paymentType": "P",
"paymentTerm": "",
"category": "RETAIL"
},
{
"pricingDetailId": 160,
"pricingTypeId": 10000,
"productId": "64262",
"description": "Application Fee",
"feeMinAbsolute": 0,
"feeMin": 0,
"feeDefault": 0,
"feeMax": 0,
"feeMaxAbsolute": 0,
"minAmountAbsolute": 0,
"minAmt": 0,
"defaultAmt": 149,
"maxAmt": 500,
"maxAmountAbsolute": 1000,
"quantity": 1,
"rateMinAbsolute": 0,
"rateMin": 0,
"rateDefault": 0,
"rateMax": 0,
"rateMaxAbsolute": 0,
"productName": "Application Fee",
"productType": "APP_FEE",
"isOverride": false,
"override": false,
"showoncart": true,
"purchaseType": "P",
"occurrence": {
"type": "Onetime_Fee"
},
"disclosure": ""
}]
This endpoint can be used to retrieve “pricing” for any given product (or collection of products) such as the product’s own pricing, pricing for products included, and any associated fees - each considered a “Pricing Product.”
Request
POST /marketplace/v1/pricing/equipment
The endpoint takes a JSON object as input. Refer to the “Example request payload” for the JSON structure of the request payload object.
| Parameter | Required | Data Type | Description |
|---|---|---|---|
| transactionInfo | ✔ | object | Transactions information used to determine pricing. Contains mccTypes, mcc, annualVolume, averageTicket, highestTicket and category. |
| mccTypes | ✔ | string | “Merchant Category Code” MCC description (refer to: GET MCC/Category). |
| mcc | ✔ | string | MCC Code (refer to: GET MCC/Category). |
| mccAdditionalDetails | string | ||
| annualVolume | ✔ | double | Actual or estimated annual credit card transaction volume in USD. |
| averageTicket | ✔ | double | Actual or estimated average ticket price in USD. |
| highestTicket | ✔ | double | Actual or estimated highest ticket price in USD. |
| category | ✔ | string | Category name eg: "RETAIL/MOTO" (refer to: GET Categories). |
| cardNotPresent | ✔ | integer | |
| cartDetails | ✔ | array | Array of objects each representing a product in the cart. |
| productId | ✔ | long | Numeric value that uniquely identifies each product (canonical identifier), as returned in the GET Products endpoint. |
| category | ✔ | string | Category name eg: "RETAIL/MOTO" (refer to: GET Categories) the product belongs to. |
| name | ✔ | string | productName: Product name. |
| price | ✔ | float | Unit price for a product in USD. |
| type | ✔ | string | productType: Indicates the behavior of the Pricing Product, or when the merchant is charged a fee. See list of possible values here. |
| term | ✔ | string | purchaseType. See list of possible values here. |
| qty | ✔ | integer | Quantity selected. |
Response
This API returns an array of objects, each representing a “Pricing Product.” Each object contains the following keyword-value pairs.
Return Parameters in italic are used in our ISO program. They should be hidden from the user.
| Parameter | Data Type | Description |
|---|---|---|
| productId | long | Numeric value that uniquely identifies a product (canonical identifier). |
| pricingDetailId | integer | Numeric value that uniquely identifies a Pricing Strategy. |
| pricingTypeId | integer | Numeric value that uniquely identifies a Pricing Type. |
| productName | string | The name of the Pricing Product that can be displayed in the user interface. |
| description | string | Short description of the product. |
| productType | string | Indicates the behavior of the Pricing Product, or when the merchant is charged this fee. See list of possible values here. |
| quantity | integer | Quantity of the Pricing Product to be added to the order. (Generally 1.) |
| defaultAmt | double | Price/amount to be collected (usually as a one-time payment) in USD. |
| minAmt | double | |
| maxAmt | double | |
| minAmountAbsolute | double | |
| maxAmountAbsolute | double | |
| feeDefault | double | Fee charged per occurrence in USD. |
| feeMin | double | |
| feeMax | double | |
| feeMinAbsolute | double | |
| feeMaxAbsolute | double | |
| rateDefault | double | Percentage of transaction amount charged per occurrence. |
| rateMin | double | |
| rateMax | double | |
| rateMinAbsolute | double | |
| rateMaxAbsolute | double | |
| isOverride | boolean | |
| override | boolean | |
| showoncart | boolean | Flag to provide guidance on which products should be visibly displayed in the Shopping Cart. |
| purchaseType | string | Indicates the behavior of the Pricing Product, or when the merchant is charged this fee. See list of possible values here. |
| occurrence | object | |
| type | string | Occurrence indicates the event the rate/fee/amount is charged: "Transaction": charged for every transaction, "Onetime_Product": charged once. i.e. Application fee, "Recurring": charged on a recurring basis, see productType for more information. |
| category | string | Category name eg: "RETAIL/MOTO" (refer to: GET Categories) the product belongs to. |
| paymentType | string | Indicates the behavior of the Pricing Product, or when the merchant is charged this fee. See list of possible values here. |
| productAttribute | object | Contains name, value and domain. |
| name | string | Product attribute name. |
| value | string | Product attribute value. |
| domain | string | Domain like pricing. |
POST Pricing/Acquiring v1
# Don't forget to add your HMAC Authorization Headers
data = {
"transactionInfo": {
"mccTypes": "Clothing and Shoes",
"mcc": "5611",
"annualVolume": 100000,
"averageTicket": 80,
"highestTicket": 400,
"category": "RETAIL"
},
"products": [{
"id": 10013,
"name": "Visa/MasterCard",
"price": 0,
"type": "Acquiring",
"qty": 1
}, {
"id": 10017,
"name": "Discover",
"price": 0,
"type": "Acquiring",
"qty": 1
}, {
"id": 10021,
"name": "American Express",
"price": 0,
"type": "Acquiring",
"qty": 1
}, {
"id": 10023,
"name": "PayPal",
"price": 0,
"type": "Acquiring",
"qty": 1
}]
}
endpoint = "/marketplace/v1/pricing/acquiring"
r = requests.post(url + endpoint, json=data, headers=headers)
print(r)
# Don't forget to add your HMAC Authorization Headers
ENDPOINT="$URL/marketplace/v1/pricing/acquiring"
curl -X POST -H "date: $DATE" -H "Authorization: $HMAC_AUTH" -H "Content-Type:application/json" --data '{
"transactionInfo": {
"mccTypes": "Clothing and Shoes",
"mcc": "5611",
"annualVolume": 100000,
"averageTicket": 80,
"highestTicket": 400,
"category": "RETAIL"
},
"products": [{
"id": 10013,
"name": "Visa/MasterCard",
"price": 0,
"type": "Acquiring",
"qty": 1
}, {
"id": 10017,
"name": "Discover",
"price": 0,
"type": "Acquiring",
"qty": 1
}, {
"id": 10021,
"name": "American Express",
"price": 0,
"type": "Acquiring",
"qty": 1
}, {
"id": 10023,
"name": "PayPal",
"price": 0,
"type": "Acquiring",
"qty": 1
}]
}' $ENDPOINT
// Don't forget to add your HMAC Authorization Headers
var options = { method: 'POST',
url: url + '/marketplace/v1/pricing/acquiring',
headers: getAuthenticationHeaders(),
body: {
"transactionInfo": {
"mccTypes": "Clothing and Shoes",
"mcc": "5611",
"annualVolume": 100000,
"averageTicket": 80,
"highestTicket": 400,
"category": "RETAIL"
},
"products": [{
"id": 10013,
"name": "Visa/MasterCard",
"price": 0,
"type": "Acquiring",
"qty": 1
}, {
"id": 10017,
"name": "Discover",
"price": 0,
"type": "Acquiring",
"qty": 1
}, {
"id": 10021,
"name": "American Express",
"price": 0,
"type": "Acquiring",
"qty": 1
}, {
"id": 10023,
"name": "PayPal",
"price": 0,
"type": "Acquiring",
"qty": 1
}]
},
json: true
};
request(options, function (error, response, body) {
if (error) throw new Error(error);
console.log(response);
});
// Don't forget to add your HMAC Authorization Headers
try {
String jsonString = "{\n" +
" \"transactionInfo\": {\n" +
" \"mccTypes\": \"Clothing and Shoes\",\n" +
" \"mcc\": \"5611\",\n" +
" \"annualVolume\": 100000,\n" +
" \"averageTicket\": 80,\n" +
" \"highestTicket\": 400,\n" +
" \"category\": \"RETAIL\"\n" +
" },\n" +
" \"products\": [{\n" +
" \"id\": 10013,\n" +
" \"name\": \"Visa/MasterCard\",\n" +
" \"price\": 0,\n" +
" \"type\": \"Acquiring\",\n" +
" \"qty\": 1\n" +
" }, {\n" +
" \"id\": 10017,\n" +
" \"name\": \"Discover\",\n" +
" \"price\": 0,\n" +
" \"type\": \"Acquiring\",\n" +
" \"qty\": 1\n" +
" }, {\n" +
" \"id\": 10021,\n" +
" \"name\": \"American Express\",\n" +
" \"price\": 0,\n" +
" \"type\": \"Acquiring\",\n" +
" \"qty\": 1\n" +
" }, {\n" +
" \"id\": 10023,\n" +
" \"name\": \"PayPal\",\n" +
" \"price\": 0,\n" +
" \"type\": \"Acquiring\",\n" +
" \"qty\": 1\n" +
" }]\n" +
"}";
StringEntity payload = new StringEntity(jsonString);
HttpResponse response = doPost("/marketplace/v1/pricing/acquiring", payload);
int statusCode = response.getStatusLine().getStatusCode();
String response_string = EntityUtils.toString(response.getEntity());
JSONArray json = new JSONArray(response_string);
System.out.println("json:" + json.toString());
} catch (Exception e) {
e.printStackTrace();
}
<?php
# Don't forget to add your HMAC Authorization Headers
$data = array (
'transactionInfo' =>
array (
'mccTypes' => 'Clothing and Shoes',
'mcc' => '5611',
'annualVolume' => 100000,
'averageTicket' => 80,
'highestTicket' => 400,
'category' => 'RETAIL',
),
'products' =>
array (
0 =>
array (
'id' => 10013,
'name' => 'Visa/MasterCard',
'price' => 0,
'type' => 'Acquiring',
'qty' => 1,
),
1 =>
array (
'id' => 10017,
'name' => 'Discover',
'price' => 0,
'type' => 'Acquiring',
'qty' => 1,
),
2 =>
array (
'id' => 10021,
'name' => 'American Express',
'price' => 0,
'type' => 'Acquiring',
'qty' => 1,
),
3 =>
array (
'id' => 10023,
'name' => 'PayPal',
'price' => 0,
'type' => 'Acquiring',
'qty' => 1,
),
),
);
$data_json = json_encode($data);
$headers = array(
'date: ' . $date,
'Authorization: ' . $hmacAuth,
'Content-Type: application/json',
'Content-Length: ' . strlen($data_json)
);
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url . "/marketplace/v1/pricing/acquiring");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data_json);
$res = curl_exec($ch);
echo($res);
?>
Example payload:
acquiring.json
{
"transactionInfo": {
"mccTypes": "Clothing and Shoes",
"mcc": "5611",
"annualVolume": 100000,
"averageTicket": 80,
"highestTicket": 400,
"category": "RETAIL"
},
"products": [{
"id": 10013,
"name": "Visa/MasterCard",
"price": 0,
"type": "Acquiring",
"qty": 1
}, {
"id": 10017,
"name": "Discover",
"price": 0,
"type": "Acquiring",
"qty": 1
}, {
"id": 10021,
"name": "American Express",
"price": 0,
"type": "Acquiring",
"qty": 1
}, {
"id": 10023,
"name": "PayPal",
"price": 0,
"type": "Acquiring",
"qty": 1
}]
}
The above command returns JSON structured like this:
[{
"pricingDetailId": 7,
"pricingTypeId": 10000,
"productId": 45608,
"description": "ACH_REJECT_FEE",
"feeMin": 0,
"feeDefault": 0,
"feeMax": 0,
"defaultAmt": 25,
"minAmt": 5,
"maxAmt": 25,
"quantity": 1,
"rateMin": 0,
"rateDefault": 0,
"rateMax": 0,
"productName": "ACH Reject Fee",
"productType": "OCCUR_FEE",
"isOverride": false,
"override": false,
"showoncart": false,
"occurrence": {
"type": "Onetime_Fee"
}
}, {
"pricingDetailId": 24,
"pricingTypeId": 10000,
"productId": 46164,
"description": "202_MINIMUM_PROCESSING_FEE",
"feeMin": 0,
"feeDefault": 0,
"feeMax": 0,
"defaultAmt": 25,
"minAmt": 0,
"maxAmt": 25,
"quantity": 1,
"rateMin": 0,
"rateDefault": 0,
"rateMax": 0,
"productName": "Minimum Processing Fee",
"productType": "OCCUR_FEE",
"isOverride": false,
"override": false,
"showoncart": false,
"occurrence": {
"type": "Onetime_Fee"
}
}]
The POST Pricing/Acquiring API can be used to retrieve “pricing” for the credit card processing transaction fees and rates as well as any associated flat charges - each considered a “Pricing Product.”
Request
POST /marketplace/v1/pricing/acquiring
| Parameter | Required | Data Type | Description |
|---|---|---|---|
| products | ✔ | array | List of products the user has selected, each object (representing a product) contains id, name, price, type, term and qty. |
| id | ✔ | long | productId: Numeric value that uniquely identifies each product (canonical identifier). |
| name | ✔ | string | productName: Product name. |
| price | ✔ | float | Unit price for a product. |
| type | ✔ | string | productType: Indicates the behavior of the Pricing Product, or when the merchant is charged a fee. See list of possible values here. |
| term | ✔ | string | purchaseType. See list of possible values here. |
| qty | ✔ | integer | Quantity selected. |
| transactionInfo | ✔ | object | Transactions information used to determine pricing. Contains mccTypes, mcc, annualVolume, averageTicket, highestTicket and category. |
| mccTypes | string | “Merchant Category Code” MCC description (refer to: GET MCC/Category). | |
| mcc | string | MCC Code (refer to: GET MCC/Category). | |
| annualVolume | double | Actual or estimated annual credit card transaction volume in USD. | |
| averageTicket | double | Actual or estimated average ticket price in USD. | |
| highestTicket | double | Actual or estimated highest ticket price in USD. | |
| category | ✔ | string | Category name eg: "RETAIL/MOTO" (refer to: GET Categories). |
Response
This API returns an array of objects, each representing a “Pricing Product.” Each object contains the following keyword-value pairs.
Return Parameters in italic are used in our ISO program. They should be hidden from the user.
| Parameter | Data Type | Description |
|---|---|---|
| productId | integer | Numeric value that uniquely identifies a product (canonical identifier). |
| pricingDetailId | integer | Numeric value that uniquely identifies a Pricing Strategy. |
| pricingTypeId | integer | Numeric value that uniquely identifies a Pricing Type. |
| productName | string | The name of the Pricing Product that can be displayed in the user interface. |
| description | string | Short description of the product. |
| productType | string | Indicates the behavior of the Pricing Product, or when the merchant is charged this fee. See list of possible values here. |
| quantity | integer | Quantity of the Pricing Product to be added to the Order. (Generally 1.) |
| defaultAmt | integer | Price/amount to be collected (usually as a one-time payment) in USD. |
| minAmt | integer | |
| maxAmt | integer | |
| feeDefault | integer | Fee charged per occurrence in USD. |
| feeMin | integer | |
| feeMax | integer | |
| rateDefault | integer | Percentage of transaction amount charged per occurrence. |
| rateMin | integer | |
| isOverride | boolean | |
| override | boolean | |
| showoncart | boolean | Flag to provide guidance on which products should be visibly displayed in the Shopping Cart. |
| occurrence | object | |
| type | string | Occurrence indicates the event the rate/fee/amount is charged: "Transaction": charged for every transaction, "Onetime_Product": charged once. i.e. Application fee, "Recurring": charged on a recurring basis, see productType for more information. |
| productAttribute | object | Contains name, value and domain. |
| name | string | Product attribute name. |
| value | string | Product attribute value. |
| domain | string | Domain like pricing. |
POST Pricing/Acquiring v2
# Don't forget to add your HMAC Authorization Headers
data = {
"transactionInfo": {
"mccTypes": "Clothing and Shoes",
"mcc": "5611",
"mccAdditionalDetails": "",
"annualVolume": 23000,
"annualcardVolume": 100000,
"averageTicket": 80,
"highestTicket": 400,
"category": "RETAIL"
},
"cardNotPresent": 1,
"cartDetails": [
{
"productId": "67702",
"category": "RETAIL",
"productType": "Terminal"
}, {
"productId": "10013",
"category": "RETAIL",
"productType": "ACQUIRING"
}
]
}
endpoint = "/marketplace/v2/pricing/acquiring"
r = requests.post(url + endpoint, json=data, headers=headers)
print(r)
# Don't forget to add your HMAC Authorization Headers
ENDPOINT="$URL/marketplace/v2/pricing/acquiring"
curl -X POST -H "date: $DATE" -H "Authorization: $HMAC_AUTH" -H "Content-Type:application/json" --data '{
"transactionInfo": {
"mccTypes": "Clothing and Shoes",
"mcc": "5611",
"mccAdditionalDetails": "",
"annualVolume": 23000,
"annualcardVolume": 100000,
"averageTicket": 80,
"highestTicket": 400,
"category": "RETAIL"
},
"cardNotPresent": 1,
"cartDetails": [
{
"productId": "67702",
"category": "RETAIL",
"productType": "Terminal"
}, {
"productId": "10013",
"category": "RETAIL",
"productType": "ACQUIRING"
}
]
}' $ENDPOINT
// Don't forget to add your HMAC Authorization Headers
var options = { method: 'POST',
url: url + '/marketplace/v2/pricing/acquiring',
headers: getAuthenticationHeaders(),
body: {
"transactionInfo": {
"mccTypes": "Clothing and Shoes",
"mcc": "5611",
"mccAdditionalDetails": "",
"annualVolume": 23000,
"annualcardVolume": 100000,
"averageTicket": 80,
"highestTicket": 400,
"category": "RETAIL"
},
"cardNotPresent": 1,
"cartDetails": [
{
"productId": "67702",
"category": "RETAIL",
"productType": "Terminal"
}, {
"productId": "10013",
"category": "RETAIL",
"productType": "ACQUIRING"
}
]
},
json: true
};
request(options, function (error, response, body) {
if (error) throw new Error(error);
console.log(response);
});
// Don't forget to add your HMAC Authorization Headers
try {
String jsonString = "{\n" +
" \"transactionInfo\": {\n" +
" \"mccTypes\": \"Clothing and Shoes\",\n" +
" \"mcc\": \"5611\",\n" +
" \"annualVolume\": 100000,\n" +
" \"averageTicket\": 80,\n" +
" \"highestTicket\": 400,\n" +
" \"category\": \"RETAIL\"\n" +
" },\n" +
" \"cardNotPresent\": 1,\n" +
" \"cartDetails\": [\n" +
" {\n" +
" \"productId\": \"67702\",\n" +
" \"productType\": \"Terminal\",\n" +
" \"category\": \"RETAIL\"\n" +
" },\n" +
" {\n" +
" \"productId\": \"10013\",\n" +
" \"productType\": \"ACQUIRING\",\n" +
" \"category\": \"RETAIL\"\n" +
" }\n" +
" ]\n" +
"}";
StringEntity payload = new StringEntity(jsonString);
HttpResponse response = doPost("/marketplace/v2/pricing/acquiring", payload);
int statusCode = response.getStatusLine().getStatusCode();
String response_string = EntityUtils.toString(response.getEntity());
JSONArray json = new JSONArray(response_string);
System.out.println("json:" + json.toString());
} catch (Exception e) {
e.printStackTrace();
}
<?php
# Don't forget to add your HMAC Authorization Headers
$data = array (
'transactionInfo' =>
array (
'mccTypes' => 'Clothing and Shoes',
'mcc' => '5611',
'mccAdditionalDetails' => '',
'annualVolume' => 23000,
'annualcardVolume' => 100000,
'averageTicket' => 80,
'highestTicket' => 400,
'category' => 'RETAIL',
),
'cardNotPresent' => 1,
'cartDetails' =>
array (
0 =>
array (
'productId' => '67702',
'productType' => 'Terminal',
'category' => 'RETAIL',
),
1 =>
array (
'productId' => '10013',
'productType' => 'ACQUIRING',
'category' => 'RETAIL',
),
),
);
$data_json = json_encode($data);
$headers = array(
'date: ' . $date,
'Authorization: ' . $hmacAuth,
'Content-Type: application/json',
'Content-Length: ' . strlen($data_json)
);
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url . "/marketplace/v2/pricing/acquiring");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data_json);
$res = curl_exec($ch);
echo($res);
?>
Example payload:
acquiring.json
{
"transactionInfo": {
"mccTypes": "Clothing and Shoes",
"mcc": "5611",
"mccAdditionalDetails": "",
"annualVolume": 23000,
"annualcardVolume": 100000,
"averageTicket": 80,
"highestTicket": 400,
"category": "RETAIL"
},
"cardNotPresent": 1,
"cartDetails": [
{
"productId": "67702",
"category": "RETAIL",
"productType": "Terminal"
}, {
"productId": "10013",
"category": "RETAIL",
"productType": "ACQUIRING"
}
]
}
The above command returns JSON structured like this:
{
"discountRates":
[{
"pricingDetailId": 9556,
"pricingTypeId": 10000,
"productId": "50072",
"description": "MasterCard Cross Border Fee Non-USD",
"feeMinAbsolute": 0,
"feeMin": 0,
"feeDefault": 0,
"feeMax": 0,
"feeMaxAbsolute": 0,
"minAmountAbsolute": 0,
"minAmt": 0,
"defaultAmt": 0,
"maxAmt": 0,
"maxAmountAbsolute": 0,
"quantity": 1,
"rateMinAbsolute": 0.85,
"rateMin": 0.85,
"rateDefault": 0.85,
"rateMax": 0.85,
"rateMaxAbsolute": 0.85,
"productName": "MasterCard Cross Border Fee Non-USD",
"productType": "NET_FEE",
"isOverride": false,
"override": false,
"showoncart": false,
"purchaseType": "P",
"occurrence": {
"type": "Transaction"
},
"groupName": "International Fees",
"parentOrder": 15
}],
"cardPresentDiscountRates":
[{
"pricingDetailId": 7034,
"pricingTypeId": 4,
"productId": "31849",
"description": "MasterCard Qualified Signature Debit",
"feeMinAbsolute": 0,
"feeMin": 0,
"feeDefault": 0,
"feeMax": 0,
"feeMaxAbsolute": 0,
"minAmountAbsolute": 0,
"minAmt": 0,
"defaultAmt": 0.29,
"maxAmt": 10,
"maxAmountAbsolute": 10,
"quantity": 1,
"rateMinAbsolute": 0,
"rateMin": 0.525,
"rateDefault": 0.975,
"rateMax": 3.175,
"rateMaxAbsolute": 5,
"productName": "MasterCard Qualified Signature Debit",
"productType": "NET_FEE",
"isOverride": false,
"override": false,
"showoncart": false,
"purchaseType": "P",
"occurrence": {
"type": "Transaction"
},
"groupName": "Qualified Signature Debit",
"cardPresntFlag": 0,
"cardNotPresent": 0,
"parentOrder": 2
}],
"cartTransactionRates":
[{
"pricingDetailId": 7003,
"pricingTypeId": 4,
"productId": "2",
"description": "Visa Qualified Credit",
"feeMinAbsolute": 0,
"feeMin": 0,
"feeDefault": 0,
"feeMax": 0,
"feeMaxAbsolute": 0,
"minAmountAbsolute": 0,
"minAmt": 0,
"defaultAmt": 0.29,
"maxAmt": 10,
"maxAmountAbsolute": 10,
"quantity": 1,
"rateMinAbsolute": 0,
"rateMin": 0,
"rateDefault": 1.381,
"rateMax": 0,
"rateMaxAbsolute": 5,
"productName": "Visa Qualified Credit",
"productType": "ACQUIRING",
"isOverride": false,
"override": false,
"showoncart": false,
"purchaseType": "P",
"occurrence": {
"type": "Transaction"
},
"parentProduct": {
"name": "2 Tier",
"id": "10009",
"rate": 1.381,
"fee": 0.29
},
"groupName": "Card Present",
"cardPresntFlag": 0,
"cardNotPresent": 0,
"parentOrder": 100
}]
}
The POST Pricing/Acquiring API can be used to retrieve “pricing” for the credit card processing transaction fees and rates as well as any associated flat charges - each considered a “Pricing Product.”
Request
POST /marketplace/v2/pricing/acquiring
| Parameter | Required | Data Type | Description |
|---|---|---|---|
| transactionInfo | ✔ | object | Transactions information used to determine pricing. Contains mccTypes, mcc, annualVolume, averageTicket, highestTicket and category. |
| mccTypes | ✔ | string | “Merchant Category Code” MCC description (refer to: GET MCC/Category). |
| mcc | ✔ | string | MCC Code (refer to: GET MCC/Category). |
| mccAdditionalDetails | string | ||
| annualVolume | ✔ | double | Actual or estimated annual credit card transaction volume in USD. |
| averageTicket | ✔ | double | Actual or estimated average ticket price in USD. |
| highestTicket | ✔ | double | Actual or estimated highest ticket price in USD. |
| category | ✔ | string | Category name eg: "RETAIL/MOTO" (refer to: GET Categories). |
| cardNotPresent | ✔ | integer | |
| cartDetails | ✔ | array | Array of objects each representing a product in the cart. |
| productId | ✔ | long | Numeric value that uniquely identifies each product (canonical identifier), as returned in the GET Products endpoint. |
| category | ✔ | string | Category name eg: "RETAIL/MOTO" (refer to: GET Categories) the product belongs to. |
| productType | ✔ | string | productType: Indicates the behavior of the Pricing Product, or when the merchant is charged a fee. See list of possible values here. |
Response
This API returns an array of objects, each representing a “Pricing Product.” Each object contains the following keyword-value pairs.
Return Parameters in italic are used in our ISO program. They should be hidden from the user.
| Parameter | Data Type | Description |
|---|---|---|
| cartTransactionRates | array | Transnational products price. |
| discountRates | array | Rates of acquirer card prices which will contain rate and fee %. |
| cardPresentDiscountRates | array | If one or more equipment in the order is card present: acquiring rates which appear based on equipment added to the cart. |
| cardNotPresentDiscountRates | array | If one or more equipment in the order is card not present: acquiring rates which appear based on equipment added to the cart. |
| productId | lond | Numeric value that uniquely identifies a product (canonical identifier). |
| pricingDetailId | integer | Numeric value that uniquely identifies a Pricing Strategy. |
| pricingTypeId | integer | Numeric value that uniquely identifies a Pricing Type. |
| productName | string | The name of the Pricing Product that can be displayed in the user interface. |
| description | string | Short description of the product. |
| productType | string | Indicates the behavior of the Pricing Product, or when the merchant is charged this fee. See list of possible values here. |
| quantity | double | Quantity of the Pricing Product to be added to the order. (Generally 1.) |
| defaultAmt | double | Price/amount to be collected (usually as a one-time payment) in USD. |
| minAmt | double | |
| maxAmt | double | |
| minAmountAbsolute | double | |
| maxAmountAbsolute | double | |
| feeDefault | double | Fee charged per occurrence in USD. |
| feeMin | double | |
| feeMax | double | |
| feeMinAbsolute | double | |
| feeMaxAbsolute | double | |
| rateDefault | double | Percentage of transaction amount charged per occurrence. |
| rateMin | double | |
| rateMax | double | |
| rateMinAbsolute | double | |
| rateMaxAbsolute | double | |
| isOverride | boolean | |
| override | boolean | |
| showoncart | boolean | Flag to provide guidance on which products should be visibly displayed in the Shopping Cart. |
| purchaseType | string | Indicates the behavior of the Pricing Product, or when the merchant is charged this fee. See list of possible values here. |
| occurrence | object | |
| type | string | Occurrence indicates the event the rate/fee/amount is charged: "Transaction": charged for every transaction, "Onetime_Product": charged once. i.e. Application fee, "Recurring": charged on a recurring basis, see productType for more information. |
| category | string | Category name eg: "RETAIL/MOTO" (refer to: GET Categories) the product belongs to. |
| paymentType | string | Indicates the behavior of the Pricing Product, or when the merchant is charged this fee. See list of possible values here. |
| groupName | string | Group name of products . |
| parentOrder | long | Parent order. |
| cardPresentFlag | integer | |
| cardNotPresent | integer | |
| parentProduct | object | Parent product. |
| name | string | productName: Product name. |
| id | long | Numeric value that uniquely identifies a product (canonical identifier). |
| rate | double | |
| fee | double |
POST Pricing/Global
# Don't forget to add your HMAC Authorization Headers
data = {} # send and empty JSON object as a string for this request
endpoint = url + "/marketplace/v1/pricing/global"
r = requests.post(endpoint, json=data, headers=headers)
ENDPOINT="$URL/marketplace/v1/pricing/global"
curl -X POST -H "date: $DATE" -H "Authorization: $HMAC_AUTH" -H "Content-Type:application/json" --data '{}' $ENDPOINT
// Don't forget to add your HMAC Authorization Headers
var options = { method: 'POST',
url: url + '/marketplace/v1/pricing/global',
headers: getAuthenticationHeaders(),
body: { }, // send and empty JSON object as a string for this request
json: true
};
request(options, function (error, response, body) {
if (error) throw new Error(error);
console.log(response);
});
// Don't forget to add your HMAC Authorization Headers
try {
String jsonString = "{}"; // send and empty JSON object as a string for this request
StringEntity payload = new StringEntity(jsonString);
HttpResponse response = doPost("/marketplace/v1/pricing/global", payload);
int statusCode = response.getStatusLine().getStatusCode();
String response_string = EntityUtils.toString(response.getEntity());
JSONArray json = new JSONArray(response_string);
System.out.println("json:" + json.toString());
} catch (Exception e) {
e.printStackTrace();
}
<?php
# Don't forget to add your HMAC Authorization Headers
$data = array ();
$data_json = json_encode($data);
$headers = array();
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url . "/marketplace/v1/pricing/global");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data_json);
$res = curl_exec($ch);
echo($res);
?>
The above command returns JSON structured like this:
[{
"pricingDetailId": 9,
"pricingTypeId": 10000,
"productId": 45615,
"description": "AVS_WATS_AUTH_FEE",
"feeMin": 0,
"feeDefault": 0,
"feeMax": 0,
"defaultAmt": 0.1,
"minAmt": 0.02,
"maxAmt": 0.1,
"quantity": 1,
"rateMin": 0,
"rateDefault": 0,
"rateMax": 0,
"productName": "Address Verification Wats Authorization Fee",
"productType": "OCCUR_FEE",
"isOverride": false,
"override": false,
"showoncart": false,
"occurrence": {
"type": "Onetime_Fee"
}
}, {
"pricingDetailId": 32,
"pricingTypeId": 10000,
"productId": 46657,
"description": "DISCOVER CHGBCK",
"feeMin": 0,
"feeDefault": 0,
"feeMax": 0,
"defaultAmt": 25,
"minAmt": 10,
"maxAmt": 25,
"quantity": 1,
"rateMin": 0,
"rateDefault": 0,
"rateMax": 0,
"productName": "Discover Chargeback Fee",
"productType": "CHGBK_FEE",
"isOverride": false,
"override": false,
"showoncart": false,
"occurrence": {
"type": "Onetime_Fee"
}
}]
The POST Pricing/Equipment API can be used to retrieve “pricing” that applies to every merchant regardless of equipment purchased or qualifying criteria - each object returned is considered a “Pricing Product.”
Request
POST /marketplace/v1/pricing/global
| Parameter | Required | Data Type | Default | Description |
|---|---|---|---|---|
| no input |
Response
This API returns an array of objects, each representing a “Pricing Product.” Each object contains the following keyword-value pairs.
Return Parameters in italic are used in our ISO program. They should be hidden from the user.
| Parameter | Data Type | Description |
|---|---|---|
| productId | integer | Numeric value that uniquely identifies a product (canonical identifier). |
| pricingDetailId | integer | Numeric value that uniquely identifies a Pricing Strategy. |
| pricingTypeId | integer | Numeric value that uniquely identifies a Pricing Type. |
| productName | string | The name of the Pricing Product that can be displayed in the user interface. |
| description | string | Short description of the product. |
| productType | string | Indicates the behavior of the Pricing Product, or when the merchant is charged this fee. See list of possible values here. |
| quantity | integer | Quantity of the Pricing Product to be added to the Order. (Generally 1). |
| defaultAmt | integer | Price/amount to be collected (usually as a one-time payment) in USD. |
| minAmt | integer | |
| maxAmt | integer | |
| feeDefault | integer | Fee charged per occurrence in USD. |
| feeMin | integer | |
| feeMax | integer | |
| rateDefault | integer | Percentage of transaction amount charged per occurrence. |
| rateMin | integer | |
| isOverride | boolean | |
| override | boolean | |
| showoncart | boolean | Flag to provide guidance on which products should be visibly displayed in the Shopping Cart. |
| occurrence | object | |
| type | string | Occurrence indicates the event the rate/fee/amount is charged: "Transaction": charged for every transaction, "Onetime_Product": charged once. i.e. Application fee, "Recurring": charged on a recurring basis, see productType for more information. |
| productAttribute | object | Contains name, value and domain. |
| name | string | Product attribute name. |
| value | string | Product attribute value. |
| domain | string | Domain like pricing. |
POST Merchantorders
data = {
"company": "John's Business Supplies",
"numberofLocations": 1,
"firstName": "John",
"lastName": "Smith",
"email": "johnsmith@emai.com",
"phone": "1234567890",
"address1": "123 Main Street",
"address2": "Suite 123",
"city": "SCHENECTADY",
"state": "NY",
"postalCode": "12345",
"recordType": "Lead",
"cardNotPresent": 1,
"pricingDetails": [
{
"productId": "67702",
"quantity": 1,
"productName": "Clover Station W/ Cash Drawer",
"feeMinAbsolute": 0,
"feeMin": 0,
"feeDefault": 0,
"feeMax": 0,
"feeMaxAbsolute": 0,
"minAmountAbsolute": 499.00,
"minAmt": 999.00,
"defaultAmt": 1599.00,
"maxAmt": 1840.00,
"maxAmountAbsolute": 1840.00,
"rateMinAbsolute": 0,
"rateMin": 0,
"rateDefault": 0,
"rateMax": 0,
"rateMaxAbsolute": 0,
"productType": "IBUNDLE",
"isOverride": false,
"override": false,
"showoncart": false,
"purchaseType": "P",
"occurrence": {
"type": "Onetime_Product"
},
"paymentType": "P",
"paymentTerm": "",
"category": "RETAIL"
},
{
"productId": "59462",
"quantity": 1,
"productName": "Transarmor Monthly Fee",
"description": "4TA_TA_MOFEE",
"feeMinAbsolute": 0,
"feeMin": 0,
"feeDefault": 0,
"feeMax": 0,
"feeMaxAbsolute": 0,
"minAmountAbsolute": 0,
"minAmt": 0,
"defaultAmt": 0,
"maxAmt": 0,
"maxAmountAbsolute": 0,
"rateMinAbsolute": 0,
"rateMin": 0,
"rateDefault": 0,
"rateMax": 0,
"rateMaxAbsolute": 0,
"productType": "MO_FEE",
"isOverride": false,
"override": false,
"showoncart": true,
"occurrence": {
"type": "Recurring"
},
"disclosure": "Per Location",
"productAttribute": {
"name": "SOLUTION_FEE",
"value": "Clover Security Plus",
"domain": "PRICING"
}
},
{
"productId": "3",
"quantity": 1,
"productName": "MasterCard Qualified Credit",
"description": "MC",
"feeMinAbsolute": 0,
"feeMin": 0,
"feeDefault": 0,
"feeMax": 0,
"feeMaxAbsolute": 0,
"minAmountAbsolute": 0,
"minAmt": 0,
"defaultAmt": 0.29,
"maxAmt": 10,
"maxAmountAbsolute": 10,
"rateMinAbsolute": 0,
"rateMin": 0,
"rateDefault": 0.109,
"rateMax": 2.309,
"rateMaxAbsolute": 5,
"productType": "NET_FEE",
"isOverride": false,
"override": false,
"showoncart": false,
"occurrence": {
"type": "Transaction"
},
"groupName": "Qualified Credit",
"cardPresntFlag": 0,
"cardNotPresent": 0,
"parentOrder": 1
}
],
"pricingOptions": {
"companyId": 386,
"transactionInfo": {
"mccTypes": "Appliances, Electronics, Computers",
"mcc": "5734",
"annualVolume": 200000,
"creditCardVolume": 150000,
"averageTicket": 20,
"highestTicket": 300,
"category": "RETAIL"
}
},
"shippingAddress": [
{
"company_name": "John's Business Supplies",
"firstName": "John",
"lastName": "Smith",
"address1": "123 Main Street",
"address2": "Suite 123",
"city": "SCHENECTADY",
"state": "NY",
"postalCode": "12345",
"email": "johnsmith@email.com",
"email2": "johnsmith@email.com",
"phone": "1234567890",
"productstoShip": [
{
"productId": "67702",
"term": "P"
}
]
}
],
"cartDetails": {
"data": [
{
"productId": "67702",
"name": "Clover Station W/ Cash Drawer",
"price": 1599,
"term": "P",
"qty": 1,
"category": "RETAIL",
"productType": "Terminal"
},
{
"productId": 50712,
"name": "Gnd",
"price": 19.95,
"term": "P",
"qty": 1,
"category": "RETAIL",
"productType": "SHIPPING"
},
{
"productId": "10013",
"name": "Visa/MasterCard",
"price": 0,
"qty": 1,
"category": "RETAIL",
"productType": "ACQUIRING"
},
{
"productId": "10017",
"name": "Discover",
"price": 0,
"qty": 1,
"category": "RETAIL",
"productType": "ACQUIRING"
},
{
"productId": "10021",
"name": "American Express",
"price": 0,
"qty": 1,
"category": "RETAIL",
"productType": "ACQUIRING"
},
{
"productId": "10023",
"name": "PayPal",
"price": 0,
"qty": 1,
"category": "RETAIL",
"productType": "ACQUIRING"
}
],
"amount": 1599.00,
"shipping_amount": 19.95,
"tax": 111.93,
"taxPercent": 0.07,
"total": 1730.88,
"shipping_option_id": 1,
"purchaseEnabled": true,
"total_qty": 1
}
}
endpoint = "/marketplace/v1/merchantorders"
r = requests.post(url + endpoint, json=data, headers=headers)
print(r)
ENDPOINT="$URL/marketplace/v1/merchantorders"
curl -X POST -H "date: $DATE" -H "Authorization: $HMAC_AUTH" -H "Content-Type:application/json" --data '{
"company": "John's Business Supplies",
"numberofLocations": 1,
"firstName": "John",
"lastName": "Smith",
"email": "johnsmith@emai.com",
"phone": "1234567890",
"address1": "123 Main Street",
"address2": "Suite 123",
"city": "SCHENECTADY",
"state": "NY",
"postalCode": "12345",
"recordType": "Lead",
"cardNotPresent": 1,
"pricingDetails": [
{
"productId": "67702",
"quantity": 1,
"productName": "Clover Station W/ Cash Drawer",
"feeMinAbsolute": 0,
"feeMin": 0,
"feeDefault": 0,
"feeMax": 0,
"feeMaxAbsolute": 0,
"minAmountAbsolute": 499.00,
"minAmt": 999.00,
"defaultAmt": 1599.00,
"maxAmt": 1840.00,
"maxAmountAbsolute": 1840.00,
"rateMinAbsolute": 0,
"rateMin": 0,
"rateDefault": 0,
"rateMax": 0,
"rateMaxAbsolute": 0,
"productType": "IBUNDLE",
"isOverride": false,
"override": false,
"showoncart": false,
"purchaseType": "P",
"occurrence": {
"type": "Onetime_Product"
},
"paymentType": "P",
"paymentTerm": "",
"category": "RETAIL"
},
{
"productId": "59462",
"quantity": 1,
"productName": "Transarmor Monthly Fee",
"description": "4TA_TA_MOFEE",
"feeMinAbsolute": 0,
"feeMin": 0,
"feeDefault": 0,
"feeMax": 0,
"feeMaxAbsolute": 0,
"minAmountAbsolute": 0,
"minAmt": 0,
"defaultAmt": 0,
"maxAmt": 0,
"maxAmountAbsolute": 0,
"rateMinAbsolute": 0,
"rateMin": 0,
"rateDefault": 0,
"rateMax": 0,
"rateMaxAbsolute": 0,
"productType": "MO_FEE",
"isOverride": false,
"override": false,
"showoncart": true,
"occurrence": {
"type": "Recurring"
},
"disclosure": "Per Location",
"productAttribute": {
"name": "SOLUTION_FEE",
"value": "Clover Security Plus",
"domain": "PRICING"
}
},
{
"productId": "3",
"quantity": 1,
"productName": "MasterCard Qualified Credit",
"description": "MC",
"feeMinAbsolute": 0,
"feeMin": 0,
"feeDefault": 0,
"feeMax": 0,
"feeMaxAbsolute": 0,
"minAmountAbsolute": 0,
"minAmt": 0,
"defaultAmt": 0.29,
"maxAmt": 10,
"maxAmountAbsolute": 10,
"rateMinAbsolute": 0,
"rateMin": 0,
"rateDefault": 0.109,
"rateMax": 2.309,
"rateMaxAbsolute": 5,
"productType": "NET_FEE",
"isOverride": false,
"override": false,
"showoncart": false,
"occurrence": {
"type": "Transaction"
},
"groupName": "Qualified Credit",
"cardPresntFlag": 0,
"cardNotPresent": 0,
"parentOrder": 1
}
],
"pricingOptions": {
"companyId": 386,
"transactionInfo": {
"mccTypes": "Appliances, Electronics, Computers",
"mcc": "5734",
"annualVolume": 200000,
"creditCardVolume": 150000,
"averageTicket": 20,
"highestTicket": 300,
"category": "RETAIL"
}
},
"shippingAddress": [
{
"company_name": "John's Business Supplies",
"firstName": "John",
"lastName": "Smith",
"address1": "123 Main Street",
"address2": "Suite 123",
"city": "SCHENECTADY",
"state": "NY",
"postalCode": "12345",
"email": "johnsmith@email.com",
"email2": "johnsmith@email.com",
"phone": "1234567890",
"productstoShip": [
{
"productId": "67702",
"term": "P"
}
]
}
],
"cartDetails": {
"data": [
{
"productId": "67702",
"name": "Clover Station W/ Cash Drawer",
"price": 1599,
"term": "P",
"qty": 1,
"category": "RETAIL",
"productType": "Terminal"
},
{
"productId": 50712,
"name": "Gnd",
"price": 19.95,
"term": "P",
"qty": 1,
"category": "RETAIL",
"productType": "SHIPPING"
},
{
"productId": "10013",
"name": "Visa/MasterCard",
"price": 0,
"qty": 1,
"category": "RETAIL",
"productType": "ACQUIRING"
},
{
"productId": "10017",
"name": "Discover",
"price": 0,
"qty": 1,
"category": "RETAIL",
"productType": "ACQUIRING"
},
{
"productId": "10021",
"name": "American Express",
"price": 0,
"qty": 1,
"category": "RETAIL",
"productType": "ACQUIRING"
},
{
"productId": "10023",
"name": "PayPal",
"price": 0,
"qty": 1,
"category": "RETAIL",
"productType": "ACQUIRING"
}
],
"amount": 1599.00,
"shipping_amount": 19.95,
"tax": 111.93,
"taxPercent": 0.07,
"total": 1730.88,
"shipping_option_id": 1,
"purchaseEnabled": true,
"total_qty": 1
}
}' $ENDPOINT
var options = {
method: 'POST',
url: url + '/marketplace/v1/merchantorders',
headers: getAuthenticationHeaders(),
body: {
"company": "John's Business Supplies",
"numberofLocations": 1,
"firstName": "John",
"lastName": "Smith",
"email": "johnsmith@emai.com",
"phone": "1234567890",
"address1": "123 Main Street",
"address2": "Suite 123",
"city": "SCHENECTADY",
"state": "NY",
"postalCode": "12345",
"recordType": "Lead",
"cardNotPresent": 1,
"pricingDetails": [
{
"productId": "67702",
"quantity": 1,
"productName": "Clover Station W/ Cash Drawer",
"feeMinAbsolute": 0,
"feeMin": 0,
"feeDefault": 0,
"feeMax": 0,
"feeMaxAbsolute": 0,
"minAmountAbsolute": 499.00,
"minAmt": 999.00,
"defaultAmt": 1599.00,
"maxAmt": 1840.00,
"maxAmountAbsolute": 1840.00,
"rateMinAbsolute": 0,
"rateMin": 0,
"rateDefault": 0,
"rateMax": 0,
"rateMaxAbsolute": 0,
"productType": "IBUNDLE",
"isOverride": false,
"override": false,
"showoncart": false,
"purchaseType": "P",
"occurrence": {
"type": "Onetime_Product"
},
"paymentType": "P",
"paymentTerm": "",
"category": "RETAIL"
},
{
"productId": "59462",
"quantity": 1,
"productName": "Transarmor Monthly Fee",
"description": "4TA_TA_MOFEE",
"feeMinAbsolute": 0,
"feeMin": 0,
"feeDefault": 0,
"feeMax": 0,
"feeMaxAbsolute": 0,
"minAmountAbsolute": 0,
"minAmt": 0,
"defaultAmt": 0,
"maxAmt": 0,
"maxAmountAbsolute": 0,
"rateMinAbsolute": 0,
"rateMin": 0,
"rateDefault": 0,
"rateMax": 0,
"rateMaxAbsolute": 0,
"productType": "MO_FEE",
"isOverride": false,
"override": false,
"showoncart": true,
"occurrence": {
"type": "Recurring"
},
"disclosure": "Per Location",
"productAttribute": {
"name": "SOLUTION_FEE",
"value": "Clover Security Plus",
"domain": "PRICING"
}
},
{
"productId": "3",
"quantity": 1,
"productName": "MasterCard Qualified Credit",
"description": "MC",
"feeMinAbsolute": 0,
"feeMin": 0,
"feeDefault": 0,
"feeMax": 0,
"feeMaxAbsolute": 0,
"minAmountAbsolute": 0,
"minAmt": 0,
"defaultAmt": 0.29,
"maxAmt": 10,
"maxAmountAbsolute": 10,
"rateMinAbsolute": 0,
"rateMin": 0,
"rateDefault": 0.109,
"rateMax": 2.309,
"rateMaxAbsolute": 5,
"productType": "NET_FEE",
"isOverride": false,
"override": false,
"showoncart": false,
"occurrence": {
"type": "Transaction"
},
"groupName": "Qualified Credit",
"cardPresntFlag": 0,
"cardNotPresent": 0,
"parentOrder": 1
}
],
"pricingOptions": {
"companyId": 386,
"transactionInfo": {
"mccTypes": "Appliances, Electronics, Computers",
"mcc": "5734",
"annualVolume": 200000,
"creditCardVolume": 150000,
"averageTicket": 20,
"highestTicket": 300,
"category": "RETAIL"
}
},
"shippingAddress": [
{
"company_name": "John's Business Supplies",
"firstName": "John",
"lastName": "Smith",
"address1": "123 Main Street",
"address2": "Suite 123",
"city": "SCHENECTADY",
"state": "NY",
"postalCode": "12345",
"email": "johnsmith@email.com",
"email2": "johnsmith@email.com",
"phone": "1234567890",
"productstoShip": [
{
"productId": "67702",
"term": "P"
}
]
}
],
"cartDetails": {
"data": [
{
"productId": "67702",
"name": "Clover Station W/ Cash Drawer",
"price": 1599,
"term": "P",
"qty": 1,
"category": "RETAIL",
"productType": "Terminal"
},
{
"productId": 50712,
"name": "Gnd",
"price": 19.95,
"term": "P",
"qty": 1,
"category": "RETAIL",
"productType": "SHIPPING"
},
{
"productId": "10013",
"name": "Visa/MasterCard",
"price": 0,
"qty": 1,
"category": "RETAIL",
"productType": "ACQUIRING"
},
{
"productId": "10017",
"name": "Discover",
"price": 0,
"qty": 1,
"category": "RETAIL",
"productType": "ACQUIRING"
},
{
"productId": "10021",
"name": "American Express",
"price": 0,
"qty": 1,
"category": "RETAIL",
"productType": "ACQUIRING"
},
{
"productId": "10023",
"name": "PayPal",
"price": 0,
"qty": 1,
"category": "RETAIL",
"productType": "ACQUIRING"
}
],
"amount": 1599.00,
"shipping_amount": 19.95,
"tax": 111.93,
"taxPercent": 0.07,
"total": 1730.88,
"shipping_option_id": 1,
"purchaseEnabled": true,
"total_qty": 1
}
},
json: true
};
request(options, function (error, response, body) {
if (error) throw new Error(error);
console.log(response);
});
// Don't forget to add your HMAC Authorization Headers
try {
String jsonString = "{\n" +
" \"company\": \"John's Business Supplies\",\n" +
" \"numberofLocations\": 1,\n" +
" \"firstName\": \"John\",\n" +
" \"lastName\": \"Smith\",\n" +
" \"email\": \"johnsmith@emai.com\",\n" +
" \"phone\": \"1234567890\",\n" +
" \"address1\": \"123 Main Street\",\n" +
" \"address2\": \"Suite 123\",\n" +
" \"city\": \"SCHENECTADY\",\n" +
" \"state\": \"NY\",\n" +
" \"postalCode\": \"12345\",\n" +
" \"recordType\": \"Lead\",\n" +
" \"cardNotPresent\": 1,\n" +
" \"pricingDetails\": ["+
" {"+
" \"productId\": \"67702\",\n" +
" \"quantity\": 1,\n" +
" \"productName\": \"Clover Station W/ Cash Drawer\",\n" +
" \"feeMinAbsolute\": 0,\n" +
" \"feeMin\": 0,\n" +
" \"feeDefault\": 0,\n" +
" \"feeMax\": 0,\n" +
" \"feeMaxAbsolute\": 0,\n" +
" \"minAmountAbsolute\": 499.00,\n" +
" \"minAmt\": 999.00,\n" +
" \"defaultAmt\": 1599.00,\n" +
" \"maxAmt\": 1840.00,\n" +
" \"maxAmountAbsolute\": 1840.00,\n" +
" \"rateMinAbsolute\": 0,\n" +
" \"rateMin\": 0,\n" +
" \"rateDefault\": 0,\n" +
" \"rateMax\": 0,\n" +
" \"rateMaxAbsolute\": 0,\n" +
" \"productType\": \"IBUNDLE\",\n" +
" \"isOverride\": false,\n" +
" \"override\": false,\n" +
" \"showoncart\": false,\n" +
" \"purchaseType\": \"P\",\n" +
" \"occurrence\": {"+
" \"type\": \"Onetime_Product\""+
" },\n" +
" \"paymentType\": \"P\",\n" +
" \"paymentTerm\": \"\",\n" +
" \"category\": \"RETAIL\""+
" },\n" +
" {"+
" \"productId\": \"59462\",\n" +
" \"quantity\": 1,\n" +
" \"productName\": \"Transarmor Monthly Fee\",\n" +
" \"description\": \"4TA_TA_MOFEE\",\n" +
" \"feeMinAbsolute\": 0,\n" +
" \"feeMin\": 0,\n" +
" \"feeDefault\": 0,\n" +
" \"feeMax\": 0,\n" +
" \"feeMaxAbsolute\": 0,\n" +
" \"minAmountAbsolute\": 0,\n" +
" \"minAmt\": 0,\n" +
" \"defaultAmt\": 0,\n" +
" \"maxAmt\": 0,\n" +
" \"maxAmountAbsolute\": 0,\n" +
" \"rateMinAbsolute\": 0,\n" +
" \"rateMin\": 0,\n" +
" \"rateDefault\": 0,\n" +
" \"rateMax\": 0,\n" +
" \"rateMaxAbsolute\": 0,\n" +
" \"productType\": \"MO_FEE\",\n" +
" \"isOverride\": false,\n" +
" \"override\": false,\n" +
" \"showoncart\": true,\n" +
" \"occurrence\": {"+
" \"type\": \"Recurring\""+
" },\n" +
" \"disclosure\": \"Per Location\",\n" +
" \"productAttribute\": {"+
" \"name\": \"SOLUTION_FEE\",\n" +
" \"value\": \"Clover Security Plus\",\n" +
" \"domain\": \"PRICING\""+
" }"+
" },\n" +
" {"+
" \"productId\": \"3\",\n" +
" \"quantity\": 1,\n" +
" \"productName\": \"MasterCard Qualified Credit\",\n" +
" \"description\": \"MC\",\n" +
" \"feeMinAbsolute\": 0,\n" +
" \"feeMin\": 0,\n" +
" \"feeDefault\": 0,\n" +
" \"feeMax\": 0,\n" +
" \"feeMaxAbsolute\": 0,\n" +
" \"minAmountAbsolute\": 0,\n" +
" \"minAmt\": 0,\n" +
" \"defaultAmt\": 0.29,\n" +
" \"maxAmt\": 10,\n" +
" \"maxAmountAbsolute\": 10,\n" +
" \"rateMinAbsolute\": 0,\n" +
" \"rateMin\": 0,\n" +
" \"rateDefault\": 0.109,\n" +
" \"rateMax\": 2.309,\n" +
" \"rateMaxAbsolute\": 5,\n" +
" \"productType\": \"NET_FEE\",\n" +
" \"isOverride\": false,\n" +
" \"override\": false,\n" +
" \"showoncart\": false,\n" +
" \"occurrence\": {"+
" \"type\": \"Transaction\""+
" },\n" +
" \"groupName\": \"Qualified Credit\",\n" +
" \"cardPresntFlag\": 0,\n" +
" \"cardNotPresent\": 0,\n" +
" \"parentOrder\": 1"+
" }"+
" ],\n" +
" \"pricingOptions\": {"+
" \"companyId\": 386,\n" +
" \"transactionInfo\": {"+
" \"mccTypes\": \"Appliances, Electronics, Computers\",\n" +
" \"mcc\": \"5734\",\n" +
" \"annualVolume\": 200000,\n" +
" \"creditCardVolume\": 150000,\n" +
" \"averageTicket\": 20,\n" +
" \"highestTicket\": 300,\n" +
" \"category\": \"RETAIL\""+
" }"+
" },\n" +
" \"shippingAddress\": ["+
" {"+
" \"company_name\": \"John's Business Supplies\",\n" +
" \"firstName\": \"John\",\n" +
" \"lastName\": \"Smith\",\n" +
" \"address1\": \"123 Main Street\",\n" +
" \"address2\": \"Suite 123\",\n" +
" \"city\": \"SCHENECTADY\",\n" +
" \"state\": \"NY\",\n" +
" \"postalCode\": \"12345\",\n" +
" \"email\": \"johnsmith@email.com\",\n" +
" \"email2\": \"johnsmith@email.com\",\n" +
" \"phone\": \"1234567890\",\n" +
" \"productstoShip\": ["+
" {"+
" \"productId\": \"67702\",\n" +
" \"term\": \"P\""+
" }"+
" ]"+
" }"+
" ],\n" +
" \"cartDetails\": {"+
" \"data\": ["+
" {"+
" \"productId\": \"67702\",\n" +
" \"name\": \"Clover Station W/ Cash Drawer\",\n" +
" \"price\": 1599,\n" +
" \"term\": \"P\",\n" +
" \"qty\": 1,\n" +
" \"category\": \"RETAIL\",\n" +
" \"productType\": \"Terminal\""+
" },\n" +
" {"+
" \"productId\": 50712,\n" +
" \"name\": \"Gnd\",\n" +
" \"price\": 19.95,\n" +
" \"term\": \"P\",\n" +
" \"qty\": 1,\n" +
" \"category\": \"RETAIL\",\n" +
" \"productType\": \"SHIPPING\""+
" },\n" +
" {"+
" \"productId\": \"10013\",\n" +
" \"name\": \"Visa/MasterCard\",\n" +
" \"price\": 0,\n" +
" \"qty\": 1,\n" +
" \"category\": \"RETAIL\",\n" +
" \"productType\": \"ACQUIRING\""+
" },\n" +
" {"+
" \"productId\": \"10017\",\n" +
" \"name\": \"Discover\",\n" +
" \"price\": 0,\n" +
" \"qty\": 1,\n" +
" \"category\": \"RETAIL\",\n" +
" \"productType\": \"ACQUIRING\""+
" },\n" +
" {"+
" \"productId\": \"10021\",\n" +
" \"name\": \"American Express\",\n" +
" \"price\": 0,\n" +
" \"qty\": 1,\n" +
" \"category\": \"RETAIL\",\n" +
" \"productType\": \"ACQUIRING\""+
" },\n" +
" {"+
" \"productId\": \"10023\",\n" +
" \"name\": \"PayPal\",\n" +
" \"price\": 0,\n" +
" \"qty\": 1,\n" +
" \"category\": \"RETAIL\",\n" +
" \"productType\": \"ACQUIRING\""+
" }"+
" ],\n" +
" \"amount\": 1599.00,\n" +
" \"shipping_amount\": 19.95,\n" +
" \"tax\": 111.93,\n" +
" \"taxPercent\": 0.07,\n" +
" \"total\": 1730.88,\n" +
" \"shipping_option_id\": 1,\n" +
" \"purchaseEnabled\": true,\n" +
" \"total_qty\": 1"+
" }"+
"}";
StringEntity payload = new StringEntity(jsonString);
HttpResponse response = doPost("/marketplace/v1/merchantorders", payload);
int statusCode = response.getStatusLine().getStatusCode();
String response_string = EntityUtils.toString(response.getEntity());
JSONArray json = new JSONArray(response_string);
System.out.println("json:" + json.toString());
} catch (Exception e) {
e.printStackTrace();
}
<?php
# Don't forget to add your HMAC Authorization Headers
$data = array (
'company' => 'John\'s Business Supplies',
'numberofLocations' => 1,
'firstName' => 'John',
'lastName' => 'Smith',
'email' => 'johnsmith@emai.com',
'phone' => '1234567890',
'address1' => '123 Main Street',
'address2' => 'Suite 123',
'city' => 'SCHENECTADY',
'state' => 'NY',
'postalCode' => '12345',
'recordType' => 'Lead',
'cardNotPresent' => 1,
'pricingDetails' =>
array (
0 =>
array (
'productId' => '67702',
'quantity' => 1,
'productName' => 'Clover Station W/ Cash Drawer',
'feeMinAbsolute' => 0,
'feeMin' => 0,
'feeDefault' => 0,
'feeMax' => 0,
'feeMaxAbsolute' => 0,
'minAmountAbsolute' => 499,
'minAmt' => 999,
'defaultAmt' => 1599,
'maxAmt' => 1840,
'maxAmountAbsolute' => 1840,
'rateMinAbsolute' => 0,
'rateMin' => 0,
'rateDefault' => 0,
'rateMax' => 0,
'rateMaxAbsolute' => 0,
'productType' => 'IBUNDLE',
'isOverride' => false,
'override' => false,
'showoncart' => false,
'purchaseType' => 'P',
'occurrence' =>
array (
'type' => 'Onetime_Product',
),
'paymentType' => 'P',
'paymentTerm' => '',
'category' => 'RETAIL',
),
1 =>
array (
'productId' => '59462',
'quantity' => 1,
'productName' => 'Transarmor Monthly Fee',
'description' => '4TA_TA_MOFEE',
'feeMinAbsolute' => 0,
'feeMin' => 0,
'feeDefault' => 0,
'feeMax' => 0,
'feeMaxAbsolute' => 0,
'minAmountAbsolute' => 0,
'minAmt' => 0,
'defaultAmt' => 0,
'maxAmt' => 0,
'maxAmountAbsolute' => 0,
'rateMinAbsolute' => 0,
'rateMin' => 0,
'rateDefault' => 0,
'rateMax' => 0,
'rateMaxAbsolute' => 0,
'productType' => 'MO_FEE',
'isOverride' => false,
'override' => false,
'showoncart' => true,
'occurrence' =>
array (
'type' => 'Recurring',
),
'disclosure' => 'Per Location',
'productAttribute' =>
array (
'name' => 'SOLUTION_FEE',
'value' => 'Clover Security Plus',
'domain' => 'PRICING',
),
),
2 =>
array (
'productId' => '3',
'quantity' => 1,
'productName' => 'MasterCard Qualified Credit',
'description' => 'MC',
'feeMinAbsolute' => 0,
'feeMin' => 0,
'feeDefault' => 0,
'feeMax' => 0,
'feeMaxAbsolute' => 0,
'minAmountAbsolute' => 0,
'minAmt' => 0,
'defaultAmt' => 0.28999999999999998,
'maxAmt' => 10,
'maxAmountAbsolute' => 10,
'rateMinAbsolute' => 0,
'rateMin' => 0,
'rateDefault' => 0.109,
'rateMax' => 2.3090000000000002,
'rateMaxAbsolute' => 5,
'productType' => 'NET_FEE',
'isOverride' => false,
'override' => false,
'showoncart' => false,
'occurrence' =>
array (
'type' => 'Transaction',
),
'groupName' => 'Qualified Credit',
'cardPresntFlag' => 0,
'cardNotPresent' => 0,
'parentOrder' => 1,
),
),
'pricingOptions' =>
array (
'companyId' => 386,
'transactionInfo' =>
array (
'mccTypes' => 'Appliances, Electronics, Computers',
'mcc' => '5734',
'annualVolume' => 200000,
'creditCardVolume' => 150000,
'averageTicket' => 20,
'highestTicket' => 300,
'category' => 'RETAIL',
),
),
'shippingAddress' =>
array (
0 =>
array (
'company_name' => 'John\'s Business Supplies',
'firstName' => 'John',
'lastName' => 'Smith',
'address1' => '123 Main Street',
'address2' => 'Suite 123',
'city' => 'SCHENECTADY',
'state' => 'NY',
'postalCode' => '12345',
'email' => 'johnsmith@email.com',
'email2' => 'johnsmith@email.com',
'phone' => '1234567890',
'productstoShip' =>
array (
0 =>
array (
'productId' => '67702',
'term' => 'P',
),
),
),
),
'cartDetails' =>
array (
'data' =>
array (
0 =>
array (
'productId' => '67702',
'name' => 'Clover Station W/ Cash Drawer',
'price' => 1599,
'term' => 'P',
'qty' => 1,
'category' => 'RETAIL',
'productType' => 'Terminal',
),
1 =>
array (
'productId' => 50712,
'name' => 'Gnd',
'price' => 19.949999999999999,
'term' => 'P',
'qty' => 1,
'category' => 'RETAIL',
'productType' => 'SHIPPING',
),
2 =>
array (
'productId' => '10013',
'name' => 'Visa/MasterCard',
'price' => 0,
'qty' => 1,
'category' => 'RETAIL',
'productType' => 'ACQUIRING',
),
3 =>
array (
'productId' => '10017',
'name' => 'Discover',
'price' => 0,
'qty' => 1,
'category' => 'RETAIL',
'productType' => 'ACQUIRING',
),
4 =>
array (
'productId' => '10021',
'name' => 'American Express',
'price' => 0,
'qty' => 1,
'category' => 'RETAIL',
'productType' => 'ACQUIRING',
),
5 =>
array (
'productId' => '10023',
'name' => 'PayPal',
'price' => 0,
'qty' => 1,
'category' => 'RETAIL',
'productType' => 'ACQUIRING',
),
),
'amount' => 1599,
'shipping_amount' => 19.949999999999999,
'tax' => 111.93000000000001,
'taxPercent' => 0.070000000000000007,
'total' => 1730.8800000000001,
'shipping_option_id' => 1,
'purchaseEnabled' => true,
'total_qty' => 1,
),
)
$data_json = json_encode($data);
$headers = array(
'date: ' . $date,
'Authorization: ' . $hmacAuth,
'Content-Type: application/json',
'Content-Length: ' . strlen($data_json)
);
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url . "/marketplace/v1/merchantorders");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data_json);
$res = curl_exec($ch);
echo($res);
?>
The above command returns JSON structured like this:
{
"orderId": "nmwDl"
}
This endpoint retrieves a unique orderId once the shopping cart checkout process is completed. This numeric identifier is then used in the merchant boarding process as input to reference the order.
It is used for purposes of collecting information about shipping the product(s) to the merchant after the merchant boarding process is completed and approved.
Request
POST /marketplace/v1/merchantorders
The endpoint takes a JSON object as input, which contains following information.
| Parameter | Required | Data Type | Short Description |
|---|---|---|---|
| company | ✔ | string | Company name (DBA name). |
| numberofLocations | integer | Number of locations the business has, including e-commerce locations. | |
| firstName | ✔ | string | Contact first name. |
| lastName | ✔ | string | Contact last name. |
| ✔ | string | Contact email address. | |
| phone | ✔ | string | Contact phone number. |
| address1 | ✔ | string | Street address. |
| city | ✔ | string | City. |
| state | ✔ | string | State in abbreviated format. i.e. for California send "CA". |
| postalCode | ✔ | string | ZIP/postal code. |
| recordType | ✔ | string | SalesForce object. Possible Values: "Lead", "Opportunity". |
| cardNotPresent | ✔ | integer | |
| pricingDetails | ✔ | array | Array of object each containing the detailed pricing information of a product (hardware, software, acquiring, fees, etc.) in the order. |
| productId | ✔ | integer | Numeric value that uniquely identifies a product (canonical identifier). |
| productName | string | The name of the Pricing Product that can be displayed in the user interface. | |
| description | string | Short description of the product. | |
| productType | string | Indicates the behavior of the product, or when the merchant is charged a fee in case of “Processing/Pricing” products. See list of possible values here. | |
| quantity | ✔ | integer | Quantity of the Pricing Product to be added to the Order. (Generally 1.) |
| defaultAmt | ✔ | integer | Price/amount to be collected (usually as a one-time payment) in USD. |
| minAmt | integer | ||
| maxAmt | integer | ||
| feeDefault | ✔ | integer | Fee charged per occurrence in USD. |
| feeMin | integer | ||
| feeMax | integer | ||
| rateDefault | ✔ | integer | Percentage of transaction amount charged per occurrence. |
| rateMin | integer | ||
| isOverride | boolean | ||
| override | boolean | ||
| showoncart | boolean | Flag to provide guidance on which products should be visibly displayed in the Shopping Cart. | |
| occurrence | ✔ | object | |
| type | ✔ | string | Occurrence indicates the event the rate/fee/amount is charged: "Transaction": charged for every transaction, "Onetime_Product": charged once. i.e. Application fee, "Recurring": charged on a recurring basis, see productType for more information. |
| productAttribute | object | Contains name, value and domain. | |
| name | string | Product attribute name. | |
| value | string | Product attribute value. | |
| domain | string | Domain like pricing. | |
| groupName | string | ||
| parentOrder | long | ||
| pricingOptions | ✔ | object | Object containing the merchant’s expected processing information. |
| transactionInfo | ✔ | object | Transactions information used to determine pricing. |
| annualVolume | ✔ | double | Annual transaction volume in USD. |
| mccTypes | ✔ | string | “Merchant Category Code” MCC description (refer to: GET MCC/Category). |
| mcc | ✔ | string | MCC Code (refer to: GET MCC/Category). |
| creditCardVolume | ✔ | double | Annual credit card transaction volume in USD. |
| averageTicket | ✔ | double | Average ticket price in USD. |
| highestTicket | ✔ | double | Highest ticket price in USD. |
| category | ✔ | string | Category eg: "RETAIL/MOTO" (refer to: GET Categories). |
| amexVolume | double | Annual American Express credit card transaction volume in USD. | |
| mccAdditionalDetails | string | ||
| amexMemberId | long | American Express member ID. | |
| telecheckVolume | double | Annual TeleCheck/check transaction volume in USD. | |
| shippingAddress | ✔ | array | Array ob objects containing shipping information. Each object contains a shipping address (with additional contact infotmation) and the products from the order to ship to that particular address. |
| company_name | string | Company name. | |
| firstName | ✔ | string | First name. |
| lastName | ✔ | string | Last name. |
| address1 | ✔ | string | Street address. |
| address2 | string | Second line of street address, if applicable. i.e. Unit, Floor, Suite, etc. | |
| city | ✔ | string | City. |
| state | ✔ | string | State in abbreviated format. i.e. for California send "CA". |
| country | ✔ | string | ISO Standard Country Code of the country. |
| postalCode | ✔ | string | ZIP/postal code. |
| phone | string | Phone number. | |
| email1 | ✔ | string | Email address. |
| email2 | string | Alternate email address. | |
| productstoShip | ✔ | array | Array of objects, each representing a product which will be shipped to the merchant. Each object contains productId and term. |
| productId | ✔ | long | Numeric value that uniquely identifies a product (canonical identifier). |
| term | ✔ | string | purchaseType eg: Purchase, Rent, Lease etc. See list of possible values here. |
| cartDetails | object | Object containing the details of the Order Summary. Contains data, amount, shipping_amount, tax taxPercent, total, status, shipping_option_id, purchaseEnabled and total_qty. | |
| data | array | Array of objects containing products in the cart. Contains productId, name, price, term, qty and productType. | |
| productId | string | productId as string. Numeric value that uniquely identifies each product (canonical identifier). | |
| name | string | productName: Product name. | |
| price | double | Unit price for a product. | |
| term | string | purchaseType eg: Purchase, Rent, Lease etc. See list of possible values here. | |
| qty | integer | Quantity selected. | |
| productType | string | Indicates the behavior of the product, or when the merchant is charged a fee in case of “Processing/Pricing” products. See list of possible values here. | |
| category | string | Category selected for that product eg: "RETAIL/MOTO" (refer to: GET Categories). | |
| cardNotPresent | boolean | ||
| amount | double | Sum of prices of products in cart in USD. | |
| shipping_amount | double | Amount to be charged for shipping and handling in USD. | |
| tax | double | Amount of tax to be collected (based on taxPercent) in USD. | |
| taxPercent | double | Tax rate in %. You may use any external service to calculate taxes based on location. | |
| total | double | Total amount to be charged in USD. Sum of amount, shipping_amount and tax. | |
| shipping_option_id | integer | Numeric identifier for shipping method. Default to 1. Currently only “Ground Shipping” is available, which corresponds to the value 1. | |
| purchaseEnabled | boolean | Default to true. | |
| total_qty | integer | Total quantity of equipment products in the Shopping Cart. |
Response
The endpoint returns an object containing one string which represents the orderId.
| Parameter | Data Type | Description |
|---|---|---|
| orderId | string | Order Id. The numeric identifier to be used in the merchant boarding process as input to reference the order. |
POST Merchantorders/Businessinformation
data = {
"ownerInformation": [
{
"sequenceNo": 1,
"firstName": "John",
"lastName": "Smith",
"nationalId": "989898989",
"nationalIdType": "SSN",
"dateofBirth": "1973-10-08",
"title": "PARTNER",
"percentOwned": 60,
"contactInformation": {
"contactType": "OWNER",
"address1": "12 Peninsula Avenue",
"address2": "Apt 1",
"city": "SCHENECTADY",
"state": "NY",
"postalCode": "12345",
"country": "US",
"phone": "1234567890",
"mobilePhone": "8234567890",
"email": "johnsmith@emai.com"
}
},
{
"sequenceNo": 2,
"firstName": "William",
"lastName": "Smith",
"nationalId": "989898989",
"nationalIdType": "SSN",
"dateofBirth": "1976-07-11",
"title": "PARTNER",
"percentOwned": 40,
"contactInformation": {
"contactType": "OWNER",
"address1": "123 Market Street",
"city": "SCHENECTADY",
"state": "NY",
"postalCode": "12345",
"country": "US",
"phone": "1234567890",
"email": "williamsmith@email.com"
}
}
],
"merchantInformation": [
{
"sequenceNo": 3,
"businessType": "RETAIL",
"dbaName": "John's Business Supplies",
"legalName": "John's Business Supplies",
"taxFilingName": "John Business Supplies, Inc.",
"taxId": "989898989",
"yearsInBusiness": "2003-06-01",
"organizationType": "Partnerships",
"stateOfIncorporation": "ME",
"foreignEntityOption": "N",
"tinRequestedGuid": "1748795A0246D3244",
"tinType": 1,
"url": "www.jonhnsbusinesssupplies.com",
"registrationNumber": "12342",
"principalNationality": "American",
"contactInformation": [
{
"contactType": "CORPORATE",
"address1": "123 Main Street",
"address2": "Suite 123",
"city": "SCHENECTADY",
"state": "NY",
"postalCode": "12345",
"country": "US",
"email": "johnsmith@email.com",
"phone": "1234567890"
}, {
"contactType": "LOCATION",
"address1": "123 Main Street",
"address2": "Suite 124",
"city": "SCHENECTADY",
"state": "NY",
"postalCode": "12345",
"country": "US",
"email": "johnsmith@email.com",
"phone": "1234567890"
}
]
}
]
}
endpoint = "/marketplace/v1/merchantorders/12345/businessinformation"
r = requests.post(url + endpoint, json=data, headers=headers)
print(r)
ENDPOINT="$URL/marketplace/v1/merchantorders/12345/businessinformation"
curl -X POST -H "date: $DATE" -H "Authorization: $HMAC_AUTH" -H "Content-Type:application/json" --data '{
"ownerInformation": [
{
"sequenceNo": 1,
"firstName": "John",
"lastName": "Smith",
"nationalId": "989898989",
"nationalIdType": "SSN",
"dateofBirth": "1973-10-08",
"title": "PARTNER",
"percentOwned": 60,
"contactInformation": {
"contactType": "OWNER",
"address1": "12 Peninsula Avenue",
"address2": "Apt 1",
"city": "SCHENECTADY",
"state": "NY",
"postalCode": "12345",
"country": "US",
"phone": "1234567890",
"mobilePhone": "8234567890",
"email": "johnsmith@emai.com"
}
},
{
"sequenceNo": 2,
"firstName": "William",
"lastName": "Smith",
"nationalId": "989898989",
"nationalIdType": "SSN",
"dateofBirth": "1976-07-11",
"title": "PARTNER",
"percentOwned": 40,
"contactInformation": {
"contactType": "OWNER",
"address1": "123 Market Street",
"city": "SCHENECTADY",
"state": "NY",
"postalCode": "12345",
"country": "US",
"phone": "1234567890",
"email": "williamsmith@email.com"
}
}
],
"merchantInformation": [
{
"sequenceNo": 3,
"businessType": "RETAIL",
"dbaName": "John's Business Supplies",
"legalName": "John's Business Supplies",
"taxFilingName": "John Business Supplies, Inc.",
"taxId": "989898989",
"yearsInBusiness": "2003-06-01",
"organizationType": "Partnerships",
"stateOfIncorporation": "ME",
"foreignEntityOption": "N",
"tinRequestedGuid": "1748795A0246D3244",
"tinType": 1,
"url": "www.jonhnsbusinesssupplies.com",
"registrationNumber": "12342",
"principalNationality": "American",
"contactInformation": [
{
"contactType": "CORPORATE",
"address1": "123 Main Street",
"address2": "Suite 123",
"city": "SCHENECTADY",
"state": "NY",
"postalCode": "12345",
"country": "US",
"email": "johnsmith@email.com",
"phone": "1234567890"
}, {
"contactType": "LOCATION",
"address1": "123 Main Street",
"address2": "Suite 124",
"city": "SCHENECTADY",
"state": "NY",
"postalCode": "12345",
"country": "US",
"email": "johnsmith@email.com",
"phone": "1234567890"
}
]
}
]
}' $ENDPOINT
var options = {
method: 'POST',
url: url + '/marketplace/v1/merchantorders/12345/businessinformation',
headers: getAuthenticationHeaders(),
body: {
"ownerInformation": [
{
"sequenceNo": 1,
"firstName": "John",
"lastName": "Smith",
"nationalId": "989898989",
"nationalIdType": "SSN",
"dateofBirth": "1973-10-08",
"title": "PARTNER",
"percentOwned": 60,
"contactInformation": {
"contactType": "OWNER",
"address1": "12 Peninsula Avenue",
"address2": "Apt 1",
"city": "SCHENECTADY",
"state": "NY",
"postalCode": "12345",
"country": "US",
"phone": "1234567890",
"mobilePhone": "8234567890",
"email": "johnsmith@emai.com"
}
},
{
"sequenceNo": 2,
"firstName": "William",
"lastName": "Smith",
"nationalId": "989898989",
"nationalIdType": "SSN",
"dateofBirth": "1976-07-11",
"title": "PARTNER",
"percentOwned": 40,
"contactInformation": {
"contactType": "OWNER",
"address1": "123 Market Street",
"city": "SCHENECTADY",
"state": "NY",
"postalCode": "12345",
"country": "US",
"phone": "1234567890",
"email": "williamsmith@email.com"
}
}
],
"merchantInformation": [
{
"sequenceNo": 3,
"businessType": "RETAIL",
"dbaName": "John's Business Supplies",
"legalName": "John's Business Supplies",
"taxFilingName": "John Business Supplies, Inc.",
"taxId": "989898989",
"yearsInBusiness": "2003-06-01",
"organizationType": "Partnerships",
"stateOfIncorporation": "ME",
"foreignEntityOption": "N",
"tinRequestedGuid": "1748795A0246D3244",
"tinType": 1,
"url": "www.jonhnsbusinesssupplies.com",
"registrationNumber": "12342",
"principalNationality": "American",
"contactInformation": [
{
"contactType": "CORPORATE",
"address1": "123 Main Street",
"address2": "Suite 123",
"city": "SCHENECTADY",
"state": "NY",
"postalCode": "12345",
"country": "US",
"email": "johnsmith@email.com",
"phone": "1234567890"
}, {
"contactType": "LOCATION",
"address1": "123 Main Street",
"address2": "Suite 124",
"city": "SCHENECTADY",
"state": "NY",
"postalCode": "12345",
"country": "US",
"email": "johnsmith@email.com",
"phone": "1234567890"
}
]
}
]
},
json: true
};
request(options, function (error, response, body) {
if (error) throw new Error(error);
console.log(response);
});
// Don't forget to add your HMAC Authorization Headers
try {
String jsonString = "{\n" +
" \"ownerInformation\": [\n" +
" {\n" +
" \"sequenceNo\": 1,\n" +
" \"firstName\": \"JON\",\n" +
" \"lastName\": \"CONSUMER\",\n" +
" \"idType\": \"ssn\",\n" +
" \"ssn\": \"989898989\",\n" +
" \"registrationNumber\": \"12345\",\n" +
" \"dateOfBirth\": \"1973-10-08\",\n" +
" \"title\": \"PARTNER\",\n" +
" \"percentOwned\": 60,\n" +
" \"contactType\": \"OWNER\",\n" +
" \"address1\": \"123 PRM OWNER\",\n" +
" \"address2\": \"APT 1\",\n" +
" \"city\": \"SCHENECTADY\",\n" +
" \"state\": \"NY\",\n" +
" \"zip\": \"12345\",\n" +
" \"country\": \"US\",\n" +
" \"phone\": \"1111111111\",\n" +
" \"mobilePhone\": \"8234567890\",\n" +
" \"email\": \"email@email.com\",\n" +
" \"driverLicenceNo\": \"123456\",\n" +
" \"dlStateIssued\": \"AL\",\n" +
" \"dlExpirationMonth\": \"01\",\n" +
" \"dlExpirationYear\": \"2027\"\n" +
" }\n" +
" ],\n" +
" \"merchantInformation\": [\n" +
" {\n" +
" \"sequenceNo\": 3,\n" +
" \"category\": \"RETAIL\",\n" +
" \"legalName\": \"MMIS TEST LEGAL FDMP\",\n" +
" \"taxId\": \"989898989\",\n" +
" \"yearsInBusiness\": \"2003-06-01\",\n" +
" \"organizationType\": \"Partnerships\",\n" +
" \"stateOfIncorporation\": \"ME\",\n" +
" \"taxFilingName\": \"MMIS TEST TAX FDMP\",\n" +
" \"foreignEntityOption\": \"N\",\n" +
" \"tinRequestedGuid\": \"1748795A0246D3244\",\n" +
" \"tinType\": 1,\n" +
" \"url\": \"www.site.com\",\n" +
" \"websiteReviewed\": \"No\",\n" +
" \"contactInformation\": [\n" +
" {\n" +
" \"contactType\": \"CORPORATE\",\n" +
" \"address1\": \"123 BUS ADDR\",\n" +
" \"address2\": \"ST 123\",\n" +
" \"city\": \"SCHENECTADY\",\n" +
" \"state\": \"NY\",\n" +
" \"postalCode\": \"12345\",\n" +
" \"country\": \"US\",\n" +
" \"phone\": \"3333333333\",\n" +
" \"fax\": \"3333333333\",\n" +
" \"neighborhood\": \"Test\",\n" +
" \"stateInscription\": \"StateIns\",\n" +
" \"cityInscription\": \"CityIns\",\n" +
" \"stateCode\": \"StateCode\",\n" +
" \"countryCode\": \"CountryCode\",\n" +
" \"principalNationality\": \"American\",\n" +
" \"contactTime\": \"M-F 9-5\",\n" +
" \"email\": \"email@email.com\"\n" +
" }\n" +
" ]\n" +
" }\n" +
" ]\n" +
"}";
StringEntity payload = new StringEntity(jsonString);
HttpResponse response = doPost("/marketplace/v1/merchantorders/12345/businessinformation", payload);
int statusCode = response.getStatusLine().getStatusCode();
String response_string = EntityUtils.toString(response.getEntity());
JSONArray json = new JSONArray(response_string);
System.out.println("json:" + json.toString());
} catch (Exception e) {
e.printStackTrace();
}
<?php
# Don't forget to add your HMAC Authorization Headers
$data = array (
'ownerInformation' =>
array (
0 =>
array (
'sequenceNo' => 1,
'firstName' => 'John',
'lastName' => 'Smith',
'nationalId' => '989898989',
'nationalIdType' => 'SSN',
'dateofBirth' => '1973-10-08',
'title' => 'PARTNER',
'percentOwned' => 60,
'contactInformation' =>
array (
'contactType' => 'OWNER',
'address1' => '12 Peninsula Avenue',
'address2' => 'Apt 1',
'city' => 'SCHENECTADY',
'state' => 'NY',
'postalCode' => '12345',
'country' => 'US',
'phone' => '1234567890',
'mobilePhone' => '8234567890',
'email' => 'johnsmith@emai.com',
),
),
1 =>
array (
'sequenceNo' => 2,
'firstName' => 'William',
'lastName' => 'Smith',
'nationalId' => '989898989',
'nationalIdType' => 'SSN',
'dateofBirth' => '1976-07-11',
'title' => 'PARTNER',
'percentOwned' => 40,
'contactInformation' =>
array (
'contactType' => 'OWNER',
'address1' => '123 Market Street',
'city' => 'SCHENECTADY',
'state' => 'NY',
'postalCode' => '12345',
'country' => 'US',
'phone' => '1234567890',
'email' => 'williamsmith@email.com',
),
),
),
'merchantInformation' =>
array (
0 =>
array (
'sequenceNo' => 3,
'businessType' => 'RETAIL',
'dbaName' => 'John\'s Business Supplies',
'legalName' => 'John\'s Business Supplies',
'taxFilingName' => 'John Business Supplies, Inc.',
'taxId' => '989898989',
'yearsInBusiness' => '2003-06-01',
'organizationType' => 'Partnerships',
'stateOfIncorporation' => 'ME',
'foreignEntityOption' => 'N',
'tinRequestedGuid' => '1748795A0246D3244',
'tinType' => 1,
'url' => 'www.jonhnsbusinesssupplies.com',
'registrationNumber' => '12342',
'principalNationality' => 'American',
'contactInformation' =>
array (
0 =>
array (
'contactType' => 'CORPORATE',
'address1' => '123 Main Street',
'address2' => 'Suite 123',
'city' => 'SCHENECTADY',
'state' => 'NY',
'postalCode' => '12345',
'country' => 'US',
'email' => 'johnsmith@email.com',
'phone' => '1234567890',
),
1 =>
array (
'contactType' => 'LOCATION',
'address1' => '123 Main Street',
'address2' => 'Suite 124',
'city' => 'SCHENECTADY',
'state' => 'NY',
'postalCode' => '12345',
'country' => 'US',
'email' => 'johnsmith@email.com',
'phone' => '1234567890',
),
),
),
),
)
$data_json = json_encode($data);
$headers = array(
'date: ' . $date,
'Authorization: ' . $hmacAuth,
'Content-Type: application/json',
'Content-Length: ' . strlen($data_json)
);
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url . "/marketplace/v1/merchantorders/12345/businessinformation");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data_json);
$res = curl_exec($ch);
echo($res);
?>
The above command returns JSON structured like this:
{
"orderId": "nmwDl"
}
This endpoint collects merchant and owner information for merchant boarding purposes.
Request
POST /marketplace/v1/merchantorders/{orderId}/businessinformation
In the request URL, use the orderId as it was returned in the response of the POST Merchantorders API.
The endpoint takes a JSON object as input, which contains following information.
| Parameter | Required | Data Type | Short Description |
|---|---|---|---|
| ownerInformation | ✔ | array | Array of (minimum one) objects, each containing the information of the owner(s) of the business. |
| sequenceNo | ✔ | integer | Index of the object representing the owner. |
| firstName | ✔ | string | Owner’s first name. |
| lastName | ✔ | string | Owner’s last name. |
| nationalIdType | ✔ | string | Type of ID document used. Possible values: "SSN", "Drivers License", "AN Card", "Other". |
| nationalId | ✔ | string | Identification number on ID document. |
| dateofBirth | ✔ | string | Owner’s date of birth in “YYYY-MM-DD” format. |
| title | ✔ | string | Title of the listed contact. Possible values: "Owner", "Partner", "President", etc. |
| percentOwned | ✔ | integer | Percentage of the company owned by this owner. All owners must equal 100%. |
| contactInformation | ✔ | array | Array of (minimum one) object(s), each of which represents the contact information of the owner. Each can contain contactType, address1, address2, address3, city, state, postalCode, country, phone,mobilePhone, and email. |
| contactType | ✔ | string | Type of location. Possible values: "OWNER", "PRINCIPAL", "LANDLORD", "BENEFICIARY". |
| address1 | ✔ | string | Street address. |
| address2 | string | Second line of street address, if applicable. i.e. Unit, Floor, Suite, etc. | |
| address3 | string | Third line of street address. | |
| city | ✔ | string | City. |
| state | ✔ | string | State in abbreviated format. i.e. for California send "CA". |
| country | ✔ | string | ISO Standard Country Code of the country. |
| postalCode | ✔ | string | ZIP/postal code. |
| phone | string | Phone number. | |
| mobilePhone | string | Mobile number. | |
string | Email address. | ||
| merchantInformation | ✔ | array | Array of (minimum one) objects, each containing the information about a location of the business. |
| sequenceNo | integer | Index. | |
| businessType | ✔ | string | Category eg: "RETAIL" (refer to: GET Categories). |
| dbaName | ✔ | string | DBA name. |
| legalName | ✔ | string | Legal business name. |
| taxFilingName | ✔ | string | IRS tax filing name for the business. Can be validated against taxId using the POST TIN/Validate service. |
| yearsInBusiness | ✔ | string | Business started date in “YYYY-MM-DD” format. |
| organizationType | ✔ | string | Organization type represented by an abbreviated code. See possible values here. |
| stateOfIncorporation | ✔ | string | State of incorporation in abbreviated format. i.e. for California send "CA". |
| taxId | ✔ | string | A Taxpayer Identification Number (TIN) is an identification number used by the Internal Revenue Service (IRS). Can be validated against taxFilingName using the POST TIN/Validate service. |
| foreignEntityOption | ✔ | string | Indicates if the business can claim foreign status according to IRS regulations. Possible values: "Y" or "N". |
| tinType | ✔ | integer | Type of Taxpayer Identification Number (TIN). |
| tinRequestedGuid | ✔ | string | Universal ID for the request of the POST TIN/Validate service. |
| url | string | URL of business website. | |
| contactInformation | ✔ | array | Array of (minimum one) object(s), each of which represents a business location. contactType, address1, address2, address3, city, state, postalCode, country, phone, and email. |
| contactType | ✔ | string | Type of location. Possible values: "LOCATION", "CORPORATE", "SHIPPING", "SHIP_TO", "TRADING", "BILLING", "PRIMARY", "DISPUTE", "TRAIN_BY", "STANDARD". |
| address1 | ✔ | string | Street address. |
| address2 | string | Second line of street address, if applicable. i.e. Unit, Floor, Suite, etc. | |
| address3 | string | Third line of street address. | |
| city | ✔ | string | City. |
| state | ✔ | string | State in abbreviated format. i.e. for California send "CA". |
| country | ✔ | string | ISO Standard Country Code of the country. |
| postalCode | ✔ | string | ZIP/postal code. |
| contactTime | string | Preference on contact time. | |
| phone | string | Phone number. | |
string | Email address. |
Response
The endpoint returns an object containing one string which represents the orderId.
| Parameter | Data Type | Description |
|---|---|---|
| orderId | string | The unique identifier of an order returned after successful submission. Used in following processes as input data. |
POST Merchantorders/Locations
data = {
"locationInformation": [
{
"dbaName": "John's Computer Business",
"merchantId": "120107",
"averageTicket": 20,
"mccDescription": "Appliances, Electronics, Computers",
"mcc": "5734",
"annualVolume": 100000,
"highestTicket": 300,
"isPrimaryLocation": true,
"faceToFace": "100",
"phoneOrEmail": "0",
"internet": "0",
"rollupIndicator": "2",
"category": "RETAIL",
"contactInformation": [
{
"contactType": "OWNER",
"address1": "123 Main Street",
"address2": "Suite 2",
"city": "Beverly Hills",
"state": "CA",
"country": "us",
"postalCode": "90210",
"phone": "1234567890"
}
],
"equipmentLocation": [
{
"lineItemId": 6911701,
"configurableLineItemId": 6911702,
"attributes": [
{
"attributeName": "AUTO_SETTLE",
"attributeValue": "YES",
"attributeDomain": "TERM_ATTR"
},
{
"attributeName": "TOKEN_TYPE",
"attributeValue": "9999",
"attributeDomain": "AEGIS"
},
{
"attributeName": "AUTO_CLOSE_HHMM",
"attributeValue": "2100",
"attributeDomain": "MERCURY_TERM_ATTR"
}
]
}
],
"bankInformation": [
{
"instName": "JPMORGAN CHASE BANK, NA",
"abaNumber": "021000021",
"accountNumber": "9898",
"ordinal": 2,
"isPrimary": true
}
],
"shippingPlanSelection":{
"productId": "777-1000105053",
"price": 5.78423,
"shippingName": "FedEx Ground"
},
"isShippingAddressSame" : true
}
]
}
endpoint = "/marketplace/v1/merchantorders/nmwDl/locations"
r = requests.post(url + endpoint, json=data, headers=headers)
print(r)
ENDPOINT="$URL/marketplace/v1/merchantorders/nmwDl/locations"
curl -X POST -H "date: $DATE" -H "Authorization: $HMAC_AUTH" -H "Content-Type:application/json" --data '{
"locationInformation": [
{
"dbaName": "John's Computer Business",
"merchantId": "120107",
"averageTicket": 20,
"mccDescription": "Appliances, Electronics, Computers",
"mcc": "5734",
"annualVolume": 100000,
"highestTicket": 300,
"isPrimaryLocation": true,
"faceToFace": "100",
"phoneOrEmail": "0",
"internet": "0",
"rollupIndicator": "2",
"category": "RETAIL",
"contactInformation": [
{
"contactType": "OWNER",
"address1": "123 Main Street",
"address2": "Suite 2",
"city": "Beverly Hills",
"state": "CA",
"country": "us",
"postalCode": "90210",
"phone": "1234567890"
}
],
"equipmentLocation": [
{
"lineItemId": 6911701,
"configurableLineItemId": 6911702,
"attributes": [
{
"attributeName": "AUTO_SETTLE",
"attributeValue": "YES",
"attributeDomain": "TERM_ATTR"
},
{
"attributeName": "TOKEN_TYPE",
"attributeValue": "9999",
"attributeDomain": "AEGIS"
},
{
"attributeName": "AUTO_CLOSE_HHMM",
"attributeValue": "2100",
"attributeDomain": "MERCURY_TERM_ATTR"
}
]
}
],
"bankInformation": [
{
"instName": "JPMORGAN CHASE BANK, NA",
"abaNumber": "021000021",
"accountNumber": "9898",
"ordinal": 2,
"isPrimary": true
}
],
"shippingPlanSelection":{
"productId": "777-1000105053",
"price": 5.78423,
"shippingName": "FedEx Ground"
},
"isShippingAddressSame" : true
}
]
}' $ENDPOINT
var options = {
method: 'POST',
url: url + '/marketplace/v1/merchantorders/nmwDl/locations',
headers: getAuthenticationHeaders(),
body: {
"locationInformation": [
{
"dbaName": "John's Computer Business",
"merchantId": "120107",
"averageTicket": 20,
"mccDescription": "Appliances, Electronics, Computers",
"mcc": "5734",
"annualVolume": 100000,
"highestTicket": 300,
"isPrimaryLocation": true,
"faceToFace": "100",
"phoneOrEmail": "0",
"internet": "0",
"rollupIndicator": "2",
"category": "RETAIL",
"contactInformation": [
{
"contactType": "OWNER",
"address1": "123 Main Street",
"city": "Beverly Hills",
"state": "CA",
"country": "us",
"postalCode": "90210",
"phone": "1234567890"
}
],
"equipmentLocation": [
{
"lineItemId": 6911701,
"configurableLineItemId": 6911702,
"attributes": [
{
"attributeName": "AUTO_SETTLE",
"attributeValue": "YES",
"attributeDomain": "TERM_ATTR"
},
{
"attributeName": "TOKEN_TYPE",
"attributeValue": "9999",
"attributeDomain": "AEGIS"
},
{
"attributeName": "AUTO_CLOSE_HHMM",
"attributeValue": "2100",
"attributeDomain": "MERCURY_TERM_ATTR"
}
]
}
],
"bankInformation": [
{
"instName": "JPMORGAN CHASE BANK, NA",
"abaNumber": "021000021",
"accountNumber": "9898",
"ordinal": 2,
"isPrimary": true
}
],
"shippingPlanSelection":{
"productId": "777-1000105053",
"price": 5.78423,
"shippingName": "FedEx Ground"
},
"isShippingAddressSame" : true
}
]
},
json: true
};
request(options, function (error, response, body) {
if (error) throw new Error(error);
console.log(response);
});
// Don't forget to add your HMAC Authorization Headers
try {
String jsonString = "{\n" +
" \"locationInformation\": [\n" +
" {\n" +
" \"dbaName\": \"John's Computer Business\",\n" +
" \"merchantId\": \"120107\",\n" +
" \"averageTicket\": 20,\n" +
" \"mccDescription\": \"Appliances, Electronics, Computers\",\n" +
" \"mcc\": \"5734\",\n" +
" \"annualVolume\": 100000,\n" +
" \"highestTicket\": 300,\n" +
" \"isPrimaryLocation\": true,\n" +
" \"faceToFace\": \"100\",\n" +
" \"phoneOrEmail\": \"0\",\n" +
" \"internet\": \"0\",\n" +
" \"rollupIndicator\": \"2\",\n" +
" \"category\": \"RETAIL\",\n" +
" \"contactInformation\": [\n" +
" {\n" +
" \"contactType\": \"OWNER\",\n" +
" \"address1\": \"123 Main Street\",\n" +
" \"city\": \"Beverly Hills\",\n" +
" \"state\": \"CA\",\n" +
" \"country\": \"us\",\n" +
" \"postalCode\": \"90210\",\n" +
" \"phone\": \"1234567890\"\n" +
" }\n" +
" ],\n" +
" \"equipmentLocation\": [\n" +
" {\n" +
" \"lineItemId\": 6911701,\n" +
" \"configurableLineItemId\": 6911702,\n" +
" \"attributes\": [\n" +
" {\n" +
" \"attributeName\": \"AUTO_SETTLE\",\n" +
" \"attributeValue\": \"YES\",\n" +
" \"attributeDomain\": \"TERM_ATTR\"\n" +
" },\n" +
" {\n" +
" \"attributeName\": \"TOKEN_TYPE\",\n" +
" \"attributeValue\": \"9999\",\n" +
" \"attributeDomain\": \"AEGIS\"\n" +
" },\n" +
" {\n" +
" \"attributeName\": \"AUTO_CLOSE_HHMM\",\n" +
" \"attributeValue\": \"2100\",\n" +
" \"attributeDomain\": \"MERCURY_TERM_ATTR\"\n" +
" }\n" +
" ]\n" +
" }\n" +
" ],\n" +
" \"bankInformation\": [\n" +
" {\n" +
" \"instName\": \"JPMORGAN CHASE BANK, NA\",\n" +
" \"abaNumber\": \"021000021\",\n" +
" \"accountNumber\": \"9898\",\n" +
" \"ordinal\": 2,\n" +
" \"isPrimary\": true\n" +
" }
" ]
" }
" ]
"}";
StringEntity payload = new StringEntity(jsonString);
HttpResponse response = doPost("/marketplace/v1/merchantorders/nmwDl/locations", payload);
int statusCode = response.getStatusLine().getStatusCode();
String response_string = EntityUtils.toString(response.getEntity());
JSONArray json = new JSONArray(response_string);
System.out.println("json:" + json.toString());
} catch (Exception e) {
e.printStackTrace();
}
<?php
# Don't forget to add your HMAC Authorization Headers
$data = array (
'locationInformation' =>
array (
0 =>
array (
'dbaName' => 'John\'s Computer Business',
'merchantId' => '120107',
'averageTicket' => 20,
'mccDescription' => 'Appliances, Electronics, Computers',
'mcc' => '5734',
'annualVolume' => 100000,
'highestTicket' => 300,
'isPrimaryLocation' => true,
'faceToFace' => '100',
'phoneOrEmail' => '0',
'internet' => '0',
'rollupIndicator' => '2',
'category' => 'RETAIL',
'contactInformation' =>
array (
0 =>
array (
'contactType' => 'OWNER',
'address1' => '123 Main Street',
'city' => 'Beverly Hills',
'state' => 'CA',
'country' => 'us',
'postalCode' => '90210',
'phone' => '1234567890',
),
),
'equipmentLocation' =>
array (
0 =>
array (
'lineItemId' => 6911701,
'configurableLineItemId' => 6911702,
'attributes' =>
array (
0 =>
array (
'attributeName' => 'AUTO_SETTLE',
'attributeValue' => 'YES',
'attributeDomain' => 'TERM_ATTR',
),
1 =>
array (
'attributeName' => 'TOKEN_TYPE',
'attributeValue' => '9999',
'attributeDomain' => 'AEGIS',
),
2 =>
array (
'attributeName' => 'AUTO_CLOSE_HHMM',
'attributeValue' => '2100',
'attributeDomain' => 'MERCURY_TERM_ATTR',
),
),
),
),
'bankInformation' =>
array (
0 =>
array (
'instName' => 'JPMORGAN CHASE BANK, NA',
'abaNumber' => '021000021',
'accountNumber' => '9898',
'ordinal' => 2,
'isPrimary' => true,
),
),
),
),
)
$data_json = json_encode($data);
$headers = array(
'date: ' . $date,
'Authorization: ' . $hmacAuth,
'Content-Type: application/json',
'Content-Length: ' . strlen($data_json)
);
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url . "/marketplace/v1/merchantorders/nmwDl/locations");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data_json);
$res = curl_exec($ch);
echo($res);
?>
The above command returns JSON structured like this:
{
"hashedOrderId": "nmwDl",
"primaryMerchantId": "119932"
}
This endpoint collects information about each location of the business for merchant boarding purposes.
Request
POST /marketplace/v1/merchantorders/{orderId}/locations
In the request URL, use the orderId as it was returned in the response of the POST Merchantorders API.
The endpoint takes a JSON object as input, which contains following information.
| Parameter | Required | Data Type | Short Description |
|---|---|---|---|
| locationInformation | ✔ | array | Array of (minimum one) objects, each containing the information about each business location, including e-commerce locations. |
| dbaName | ✔ | string | DBA name. |
| merchantId | ✔ | string | Merchant identifier. |
| mccDescription | ✔ | string | “Merchant Category Code” MCC description (refer to: GET MCC/Category). |
| mcc | ✔ | string | MCC Code (refer to: GET MCC/Category). |
| annualVolume | ✔ | double | Annual credit card transaction volume in USD. |
| averageTicket | ✔ | double | Actual or estimated average ticket price in USD. |
| highestTicket | ✔ | double | Actual or estimated highest ticket price in USD. |
| isPrimaryLocation | ✔ | boolean | Indicates whether this object represents the primary business location. |
| faceToFace | ✔ | string | Percentage (converted to string) of payments/transactions made face to face (can’t exceed 100%). |
| phoneOrEmail | ✔ | string | Percentage (converted to string) of payments/transactions made by phone or email (can’t exceed 100%). |
| internet | ✔ | string | Percentage (converted to string) of payments/transactions made on the internet (can’t exceed 100%). |
| rollupIndicator | ✔ | string | |
| category | string | Category eg: "RETAIL" (refer to: GET Categories). | |
| productId | string | These field are required if the shipping amount is not sent under place order.(refer to: POST shippingOptions) | |
| price | BigDecimal | These field are required if the shipping amount is not sent under place order.(refer to: POST shippingOptions) | |
| shippingName | string | These field are required if the shipping amount is not sent under place order.(refer to: POST shippingOptions) | |
| isShippingAddressSame | boolean | These field are required if the shipping amount is not sent under place order.(refer to: POST shippingOptions) | |
| contactInformation | ✔ | array | Array of (minimum one) object(s), each of which represent business information for a location. Each can contain contactType, address1, address2, address3, city, state, postalCode, country, and phone. |
| contactType | ✔ | string | Type of location. Possible values: "BILLING", "CORPORATE", "LOCATION", "OWNER", "PRINCIPAL", "SHIP TO", "TRADING". |
| address1 | ✔ | string | Street address. |
| address2 | string | Second line of street address, if applicable. i.e. Unit, Floor, Suite, etc. | |
| address3 | string | Third line of street address. | |
| city | ✔ | string | City. |
| state | ✔ | string | State in abbreviated format. i.e. for California send "CA". |
| country | ✔ | string | ISO Standard Country Code of the country. |
| postalCode | ✔ | string | ZIP/postal code. |
| phone | string | Phone number. | |
| equipmentLocation | ✔ | array | |
| lineItemId | ✔ | long | |
| configurableLineItemId | long | ||
| attributes | array | ||
| attributeName | string | ||
| attributeValue | string | ||
| attributeDomain | string | ||
| bankInformation | ✔ | array | Array of (minimum one) object(s) that collects the ACH information. |
| instName | ✔ | string | Financial institution name such as "JPMORGAN CHASE BANK", etc. |
| abaNumber | ✔ | string | ABA routing transit number. A nine digit code to identify a financial institution. Needs to be validated using the POST Banks/Validate service. |
| accountNumber | ✔ | string | Checking account number. Usually 10-12 digit number to identify the merchant’s account. |
| ordinal | ✔ | integer | Default to 2 |
| isPrimary | boolean | Indicates whether this object represents the primary bank. |
Response
The endpoint returns an object containing merchant location details and the orderId.
| Parameter | Data Type | Description |
|---|---|---|
| orderId | string | The unique identifier of an order returned after successful submission. |
| primaryMerchantId | string | Primary merchant identifier. |
| merchantIdList | array | |
| merchantId | string |
POST Merchantorders/AccountPreferences
data = {
"advancedPreferences": {
"statementDeliveryType": "Email",
"statementType": "F",
"statementEmailAddress": "johnsmith@email.com",
"form1099Electronically": "Yes",
"form1099ToEmail": "Yes",
"chargeBack": "1",
"chargeBackDeliveryType": "Mail",
"contactName": "John Smith",
"contactPhone": "1234567890",
"installContact": "",
"openDate": "10/31/2018",
"languagePreference": "ENG",
"trainingProvider": "MAG",
"preferredTrainingFrom": "11:00AM",
"preferredTrainingTo": "12:00PM",
"thirdPartyProcessor": "00",
"requiredPersonalGuarantee": false
},
"contractNotes": {
"commentToCreditOfficer": "",
"managerNotes": ""
}
}
endpoint = "/marketplace/v1/merchantorders/nmwDl/accountpreferences"
r = requests.post(url + endpoint, json=data, headers=headers)
print(r)
ENDPOINT="$URL/marketplace/v1/merchantorders/nmwDl/accountpreferences"
curl -X POST -H "date: $DATE" -H "Authorization: $HMAC_AUTH" -H "Content-Type:application/json" --data '{
"advancedPreferences": {
"statementDeliveryType": "Email",
"statementType": "F",
"statementEmailAddress": "johnsmith@email.com",
"form1099Electronically": "Yes",
"form1099ToEmail": "Yes",
"chargeBack": "1",
"chargeBackDeliveryType": "Mail",
"contactName": "John Smith",
"contactPhone": "1234567890",
"installContact": "",
"openDate": "10/31/2018",
"languagePreference": "ENG",
"trainingProvider": "MAG",
"preferredTrainingFrom": "11:00AM",
"preferredTrainingTo": "12:00PM",
"thirdPartyProcessor": "00",
"requiredPersonalGuarantee": false
},
"contractNotes": {
"commentToCreditOfficer": "",
"managerNotes": ""
}
}' $ENDPOINT
var options = {
method: 'POST',
url: url + '/marketplace/v1/merchantorders/nmwDl/accountpreferences',
headers: getAuthenticationHeaders(),
body: {
"advancedPreferences": {
"statementDeliveryType": "Email",
"statementType": "F",
"statementEmailAddress": "johnsmith@email.com",
"form1099Electronically": "Yes",
"form1099ToEmail": "Yes",
"chargeBack": "1",
"chargeBackDeliveryType": "Mail",
"contactName": "John Smith",
"contactPhone": "1234567890",
"installContact": "",
"openDate": "10/31/2018",
"languagePreference": "ENG",
"trainingProvider": "MAG",
"preferredTrainingFrom": "11:00AM",
"preferredTrainingTo": "12:00PM",
"thirdPartyProcessor": "00",
"requiredPersonalGuarantee": false
},
"contractNotes": {
"commentToCreditOfficer": "",
"managerNotes": ""
}
},
json: true
};
request(options, function (error, response, body) {
if (error) throw new Error(error);
console.log(response);
});
// Don't forget to add your HMAC Authorization Headers
try {
String jsonString = "{\n"
\"advancedPreferences\": {\n \"statementDeliveryType\": \"Email\",
\n \"statementType\": \"F\",
\n \"statementEmailAddress\": \"johnsmith@email.com\",
\n \"form1099Electronically\": \"Yes\",
\n \"form1099ToEmail\": \"Yes\",
\n \"chargeBack\": \"1\",
\n \"chargeBackDeliveryType\": \"Mail\",
\n \"contactName\": \"John Smith\",
\n \"contactPhone\": \"1234567890\",
\n \"installContact\": \"\",
\n \"openDate\": \"10\/31\/2018\",
\n \"languagePreference\": \"ENG\",
\n \"trainingProvider\": \"MAG\",
\n \"preferredTrainingFrom\": \"11:00AM\",
\n \"preferredTrainingTo\": \"12:00PM\",
\n \"thirdPartyProcessor\": \"00\",
\n \"requiredPersonalGuarantee\": false
\n },
\n \"contractNotes\": {
\n \"commentToCreditOfficer\": \"\",
\n \"managerNotes\": \"\"
\n }
\n}";
StringEntity payload = new StringEntity(jsonString);
HttpResponse response = doPost("/marketplace/v1/merchantorders/nmwDl/accountpreferences", payload);
int statusCode = response.getStatusLine().getStatusCode();
String response_string = EntityUtils.toString(response.getEntity());
JSONArray json = new JSONArray(response_string);
System.out.println("json:" + json.toString());
} catch (Exception e) {
e.printStackTrace();
}
<?php
# Don't forget to add your HMAC Authorization Headers
$data = array (
'advancedPreferences' =>
array (
'statementDeliveryType' => 'Email',
'statementType' => 'F',
'statementEmailAddress' => 'johnsmith@email.com',
'form1099Electronically' => 'Yes',
'form1099ToEmail' => 'Yes',
'chargeBack' => '1',
'chargeBackDeliveryType' => 'Mail',
'contactName' => 'John Smith',
'contactPhone' => '1234567890',
'installContact' => '',
'openDate' => '10/31/2018',
'languagePreference' => 'ENG',
'trainingProvider' => 'MAG',
'preferredTrainingFrom' => '11:00AM',
'preferredTrainingTo' => '12:00PM',
'thirdPartyProcessor' => '00',
'requiredPersonalGuarantee' => false,
),
'contractNotes' =>
array (
'commentToCreditOfficer' => '',
'managerNotes' => '',
),
)
$data_json = json_encode($data);
$headers = array(
'date: ' . $date,
'Authorization: ' . $hmacAuth,
'Content-Type: application/json',
'Content-Length: ' . strlen($data_json)
);
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url . "/marketplace/v1/merchantorders/nmwDl/locations");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data_json);
$res = curl_exec($ch);
echo($res);
?>
The above command returns JSON structured like this:
{
"orderId": "nmwDl"
}
This endpoint collects advanced setup and account preferences for the merchant order.
Request
POST /marketplace/v1/merchantorders/{orderId}/accountpreferences
In the request URL, use the orderId as it was returned in the response of the POST Merchantorders API.
The endpoint takes two JSON objects as input, which contain the following information.
| Parameter | Required | Data Type | Short Description |
|---|---|---|---|
| advancedPreferences | ✔ | object | |
| statementDeliveryType | string | Method of delivery for Account Statement. Possible values: "Email", "Online" | |
| statementEmailAddress | string | Email address to deliver the Account Statement. | |
| form1099Electronically | string | Option for merchant to get Form 1099 form electronically. Possible values: "Yes", "No" | |
| form1099ToEmail | string | Option to send Form 1099 to the same email as Account Statement. Possible values: "Yes", "No" | |
| emailAddressFor1099k | string | Email Address for 1009 Statement. Only if merchant selected "No" for form1099ToEmail. | |
| chargeBack | string | Address to respond the Chargeback or Retrieval Disputes. Possible values: "0", "1", "2" (refer to: chargeBack Values). | |
| chargeBackDeliveryType | string | Method of delivery for Chargeback or Retrieval Disputes. Possible values: "Mail", "Fax", "Dispute Manager" | |
| fax | string | Fax number to which Charge back information will be Sent. Only if merchant selects "Fax" for chargeBackDeliveryType. | |
| contactName | string | Contact name for installation. | |
| contactPhone | string | Merchant phone number for installation. | |
| preferredTrainingFrom | string | Preferred start time for installation and training (configuring terminals and software). Possible values: "09:00AM", "10:00AM", "11:00AM", "12:00PM", "1:00PM", "2:00PM", "3:00PM", "4:00PM". | |
| preferredTrainingTo | string | Preferred end time for installation and training (configuring terminals and software). Possible values: "10:00AM", "11:00AM", "12:00PM", "1:00PM", "2:00PM“, "3:00PM", "4:00PM", "5:00PM". | |
| trainingProvider | string | Training provider, the person to conduct training. Possible values: "INSTALLER", "MAG", "OSR", "SELF" (refer to: trainingProvider Values). | |
| thirdPartyProcessor | string | Option to select Any software used for storing, transmitting, or processing card transactions or authorized requests | |
| thirdPartyProcessorSoftware | string | If any third party selected, what is the name of it? | |
| openDate | string | Date merchant is open to install the equipment format Ex: "08/30/2017". | |
| installContact | string | Contact from merchant to connect while installing the equipment. | |
| languagePreference | string | Language preference of the contact during installation. See possible values here. | |
| statementType | string | Type of the Statement to provide a comprehensive record of submission, Chargebacks, funding info and fees. Possible values: "F" (Detail), "G" (Summary). | |
| requiredPersonalGuarantee | boolean | Personal Guarantee is required for contract. | |
| contractNotes | object | ||
| managerNotes | string | Any specific contract notes for Manager. | |
| commentToCreditOfficer | string | Comments to the Credit Officer who has to approve the contract. |
chargeBack values
| Value | Meaning |
|---|---|
| "0” | None |
| “1” | Business Address |
| “2” | Owner Address |
triningProider values
| Value | Meaning |
|---|---|
| “INSTALLER” | The terminal/software installer will do training. |
| “MAG” | Manager will do training. |
| “OSR” | Sales representative will do training. |
| “SELF” | No training. |
thirdPartyProcessor values
| Value | Meaning |
|---|---|
| “00” | None |
| “01” | Yahoo |
| “02” | Authorize.net |
| “03” | CyberSource |
| “04” | Verifone |
| “05” | Merchant Link |
| “06” | Shift 4 |
| “07” | Apriva |
| “08” | FIS |
| “09” | Siz Payment Services Group |
| “10” | Verisign |
| “99” | Other |
languagePreference values
| Value | Meaning |
|---|---|
| “CHI” | Chinese. |
| “ENG” | English. |
| “MAN” | Mandarin. |
| “SPA” | Spanish. |
| “VIE” | Vietnamese. |
Response
The endpoint returns an object containing the orderId.
| Parameter | Data Type | Description |
|---|---|---|
| orderId | string | The unique identifier of an order returned after successful submission. |
POST Application/Submit v3
data = {
"orderId": "PaGl7",
"contractAuditTrail": {
"merchantName": "JON CONSUMER",
"merchantEmail": "test@gmail.com",
"geoLocation": "41.247185699999996,-96.0200888",
"signDate": "2017-05-31T15:28:39.781Z",
"acceptedAgreementDate": "2017-05-31T15:28:39.781Z",
"ipAddress": "172.58.41.5"
},
"threatMetrixGuid": "000e3b78-bdc4-b1e2-e9fe-15df241c7105",
"solicitationType":"06"
}
endpoint = "/marketplace/v3/application/submit"
r = requests.post(url + endpoint, json=data, headers=headers)
print(r)
ENDPOINT="$URL/marketplace/v3/application/submit"
curl -X POST -H "date: $DATE" -H "Authorization: $HMAC_AUTH" -H "Content-Type:application/json" --data '
{
"orderId": "PaGl7",
"contractAuditTrail": {
"merchantName": "JON CONSUMER",
"merchantEmail": "test@gmail.com",
"geoLocation": "41.247185699999996,-96.0200888",
"signDate": "2017-05-31T15:28:39.781Z",
"acceptedAgreementDate": "2017-05-31T15:28:39.781Z",
"ipAddress": "172.58.41.5"
},
"threatMetrixGuid": "000e3b78-bdc4-b1e2-e9fe-15df241c7105",
"solicitationType":"06"
}' $ENDPOINT
var options = {
method: 'POST',
url: url + '/marketplace/v3/application/submit',
headers: getAuthenticationHeaders(),
body: {
"orderId": "PaGl7",
"contractAuditTrail": {
"merchantName": "JON CONSUMER",
"merchantEmail": "test@gmail.com",
"geoLocation": "41.247185699999996,-96.0200888",
"signDate": "2017-05-31T15:28:39.781Z",
"acceptedAgreementDate": "2017-05-31T15:28:39.781Z",
"ipAddress": "172.58.41.5"
},
"threatMetrixGuid": "000e3b78-bdc4-b1e2-e9fe-15df241c7105",
"solicitationType":"06"
},
json: true
};
request(options, function (error, response, body) {
if (error) throw new Error(error);
console.log(response);
});
// Don't forget to add your HMAC Authorization Headers
try {
String jsonString = "{\n \"orderId\": \"PaGl7\",\n \"contractAuditTrail\": {\n \"merchantName\": \"JON CONSUMER\",\n \"merchantEmail\": \"test@gmail.com\",\n \"geoLocation\": \"41.247185699999996,-96.0200888\",\n \"signDate\": \"2017-05-31T15:28:39.781Z\",\n \"acceptedAgreementDate\": \"2017-05-31T15:28:39.781Z\",\n \"ipAddress\": \"172.58.41.5\"\n },\n \"threatMetrixGuid\": \"000e3b78-bdc4-b1e2-e9fe-15df241c7105\"\n , \"solicitationType\":\"06\"\n}";
StringEntity payload = new StringEntity(jsonString);
HttpResponse response = doPost("/marketplace/v3/application/submit", payload);
int statusCode = response.getStatusLine().getStatusCode();
String response_string = EntityUtils.toString(response.getEntity());
JSONArray json = new JSONArray(response_string);
System.out.println("json:" + json.toString());
} catch (Exception e) {
e.printStackTrace();
}
<?php
# Don't forget to add your HMAC Authorization Headers
$data = array (
'orderId' => 'PaGl7',
'contractAuditTrail' =>
array (
'merchantName' => 'JON CONSUMER',
'merchantEmail' => 'test@gmail.com',
'geoLocation' => '41.247185699999996,-96.0200888',
'signDate' => '2017-05-31T15:28:39.781Z',
'acceptedAgreementDate' => '2017-05-31T15:28:39.781Z',
'ipAddress' => '172.58.41.5',
),
'threatMetrixGuid' => '000e3b78-bdc4-b1e2-e9fe-15df241c7105',
'solicitationType':'06',
)
$data_json = json_encode($data);
$headers = array(
'date: ' . $date,
'Authorization: ' . $hmacAuth,
'Content-Type: application/json',
'Content-Length: ' . strlen($data_json)
);
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url . "/marketplace/v3/application/submit");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data_json);
$res = curl_exec($ch);
echo($res);
?>
The above command returns JSON structured like this:
{
"orderId": "PaGl7"
}
Request
POST /marketplace/v3/application/submit
The endpoint takes JSON object as input, which contains the following information.
| Parameter | Required | Data Type | Short Description |
|---|---|---|---|
| orderId | ✔ | string | Order Id. The identifier to be used in the merchant boarding process as input to reference the order. |
| contractAuditTrail | Object | Audit trail that saved along with the contract. Audit trail is not mandatory , if the client wants to save the Audit information of the Order, it can be included. | |
| merchantName | string | Merchant Name. | |
| merchantEmail | string | Merchant Email. | |
| geoLocation | string | Geo location details. | |
| signDate | string | Signed date. Expected date format - 2017-03-28T17:28:39.781Z | |
| acceptedAgreementDate | string | Agreement Accepeted Date. Expected date format - 2017-03-28T17:28:39.781Z | |
| ipAddress | string | IP Address from which Conrtact is Submitted. | |
| documentName | string | Name of the document, that is included as part the request in the variable base64EncodedPDF. | |
| threatMetrixGuid | string | Id from Threat Metrix. This is required if the client wants to save Threat Metrix information along with Order. | |
| solicitationType | string | Allows user to drive when submitting contracts. See possible values here. | |
| base64EncodedPDF | String | Document that is submitted along with Contract (in base 64 format). |
Response
The endpoint returns an object containing the orderId.
| Parameter | Data Type | Description |
|---|---|---|
| orderId | string | Order Id. The identifier to be used in the merchant boarding process as input to reference the order. |
Possible values for solicitationtype
| 2 Byte Indicator | Boarding Tool Definition | New Segmentation | MAMA/AMA/Dynamics Definition | Original Interpretation as per Definition |
|---|---|---|---|---|
01 | Sales rep fills out in front of merchant and merchant signs electronically | Field Sales Remote | FACE TO FACE -SIGNED ONLINE E-sign = Face to Face | F2F |
02 | Sales rep takes app over phone, chat, digital, etc and emails the MPA to the applicant | TeleSales Mixed | NON FACE TO FACE – EMAIL C2A = Non F2F | Non-F2F TeleSales |
03 | Sales rep calls merchant, fills out application, Faxes to merchant for signature | TeleSales Mixed | NON FACE TO FACE – FAX | Non-F2F TeleSales |
04 | No physical site inspection – home-based | TeleSales Mixed | HOME BASED | Non-F2F TeleSales |
05 | True internet – online app, click to agree signature | Self-Service | NON FACE TO FACE –SELF SERVICE | Non-F2F Self-Boarded |
06 | Sales rep takes app over the phone, chat, digital, etc and emails the link to the MPA to the applicant | TeleSales Inbound | NON FACE TO FACE – ELECTRONIC | Non-F2F TeleSales |
07 | Kiosk at bank | Self-Service | NON FACE TO FACE – KIOSK | Non-F2F Self-Boarded |
08 | Sales rep fills out in front of merchant and prints and signs in front of merchant | Field Sales Onsite | FACE TO FACE- PAPER Standard = F2F | F2F |
09 | No physical site inspection – Internet | TeleSales Mixed | Sales rep reviewed an Internet web site as opposed to a physical site | Non-F2F TeleSales |
POST Banks/Validate
# Don't forget to add your HMAC Authorization Headers
data = {
"routingNumber":"122100024"
}
endpoint = "/marketplace/v1/banks/validate"
r = requests.post(url + endpoint, json=data, headers=headers)
print(r)
# Don't forget to add your HMAC Authorization Headers
ENDPOINT="$URL/marketplace/v1/banks/validate"
curl -X POST -H "date: $DATE" -H "Authorization: $HMAC_AUTH" -H "Content-Type:application/json" --data '{
"routingNumber": "122100024"
}' $ENDPOINT
// Don't forget to add your HMAC Authorization Headers
var options = { method: 'POST',
url: url + '/marketplace/v1/banks/validate',
headers: getAuthenticationHeaders(),
body: {
"routingNumber": "122100024"
},
json: true
};
request(options, function (error, response, body) {
if (error) throw new Error(error);
console.log(response);
});
// Don't forget to add your HMAC Authorization Headers
try {
String jsonString = "{\n" +
" \"routingNumber\": \"122100024\"\n" +
"}";
StringEntity payload = new StringEntity(jsonString);
HttpResponse response = doPost("/marketplace/v1/banks/validate", payload);
int statusCode = response.getStatusLine().getStatusCode();
String response_string = EntityUtils.toString(response.getEntity());
JSONObject json = new JSONObject(response_string);
System.out.println("json:" + json.toString());
} catch (Exception e) {
e.printStackTrace();
}
<?php
# Don't forget to add your HMAC Authorization Headers
$data = array (
'routingNumber' => '122100024',
);
$data_json = json_encode($data);
$headers = array(
'date: ' . $date,
'Authorization: ' . $hmacAuth,
'Content-Type: application/json',
'Content-Length: ' . strlen($data_json)
);
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url . "/marketplace/v1/banks/validate");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data_json);
$res = curl_exec($ch);
echo($res);
?>
Example payload:
routing.json
{
"routingNumber": "122100024"
}
The above command returns JSON structured like this:
Success response
{
"status": {
"success": "true",
"message": "000 OPERATION WAS SUCCESSFUL"
},
"data": {
"bankName": "JPMORGAN CHASE BANK, NA",
"bankCity": "COLUMBUS",
"bankState": "OH",
"bankZip": "43240"
}
}
This endpoint can be used to verify the abaNumber entered in the ACH information section (contactsInformation) of the Merchant Application form before submission. For every successful match this endpoint also retrieves additional information about the matched bank.
Request
POST /marketplace/v1/banks/validate
The endpoint takes a JSON object as input, which contains the Bank Routing number (string) entered by the user in the Merchant Application form.
| Parameter | Required | Data Type | Description |
|---|---|---|---|
| routingNumber | ✔ | string | The Bank Routing number as entered in the Merchant Application form as the abaNumber parameter. |
Response
The endpoint returns an object representing the validation result, and in the case of success, the bank information. The following parameters may be in each object returned.
| Parameter | Type | Description |
|---|---|---|
| status | object | Object containing the validation results of the routing number matching an existing bank. Contains success and message. |
| success | string | Validation result. "true": successful match. "false": error, no matching record. |
| message | string | Validation result description. |
| data | object | JSON object containing information about the matched bank. Contains name, bankCity, bankState and bankZip. |
| name | string | Name of bank in all caps format. |
| bankCity | string | City the bank is located in all caps format. |
| bankState | string | State the bank is located in, abbreviated format. i.e. for California send "CA". |
| bankZip | string | Zip code of bank. |
POST Application/Update
# Don't forget to add your HMAC Authorization Headers
data = { "merchantContactInformation": [{
"contactType": "LOCATION",
"state": "NE",
"postalCode": "68127",
"address1": "123 DONOT SHIP",
"email": "PA1N12@GMAIL.COM",
"url": "ABC.COM",
"mobile": "4353534534",
"voice": "3453453453",
"country": "USA",
"name": "MMIS TEST LEGAL",
"city": "OMAHA"
}, {
"contactType": "CORPORATE",
"state": "NE",
"postalCode": "68127",
"address1": "123 DONOT SHIP",
"address2": "null",
"mobile": "4353534534",
"voice": "3453453453",
"country": "USA",
"name": "MMIS TEST LEGAL",
"city": "OMAHA",
"email": "PA1N12@GMAIL.COM",
"url": "ABC.COM"
}],
"merchantAttributesRequestInformation": [{
"orderId": 13931,
"highestTicket": 333,
"faceToFace": "91",
"phoneOrEmail": "6",
"internet": "3",
"businessWebsite": "ABC.COM",
"typicalSaleAmount": 32,
"stateOfIncorporation": "IA",
"IRSFilingName": "MMIS TEST LEGAL",
"IRSForeignIndicator": "N",
"guid": ""
}],
"contactsInformation": [{
"instName": "JPMORGAN CHASE BANK, NA",
"abaNumber": "122100024",
"accountNumber": "12345",
"ordinal": 2
}],
"employeeInformation": [{
"lastName": "EMPLASTNAME",
"firstName": "EMPFIRSTNAME",
"ssn": "989898989",
"dateOfBirth": "1985-05-13",
"title": "VICE PRESIDENT",
"homeContactId": "111"
}],
"additionalMerchantDetails": [
{ "statementDelivery": "ONLINE" }
],
"siteSurvey": {
"siteVisitation": "NOT REQUIRED",
"surveyPerformed": "F6MICSO",
"businessZone": "MALL",
"merchantBusinessLocation": "COMBINATION",
"seasonalMerchant": "YES",
"totalFloors": "4",
"floorOccupied": "4",
"merchantsNameDisplayed": "DOOR",
"apartmentSquareFoot": "251-500",
"merchantsOwnBuildSpace": "OWN",
"totalRegister": 1,
"licenceDisplayed": "YES",
"returnPolicy": "EXCHANGE ONLY",
"separateRefundPolicy": "YES",
"customerDeposit": "YES",
"deliveryTimeFrame_0_To_7": "60",
"deliveryTimeFrame_8_To_14": "40",
"deliveryTimeFrame_15_To_30": "",
"deliveryTimeFrame_Over_30": "",
"salesDeposit": "DATE OF DELIVERY",
"autoRenew": "YES"
},
"merchantReferenceCode": "MERC",
"merchantType": "RETAIL",
"dbaName": "MMIS TEST LEGAL",
"legalName": "MMIS TEST LEGAL",
"taxId": "989898989",
"sicCode": " ",
"yearsInBusiness": "2003-09-01",
"yearsAtLocation": "2003-09-01",
"productDescription": "",
"createdByCoId": 10,
"billReferenceCode": "O",
"organizationTypeReferenceCode": "C"
}
endpoint = "/marketplace/v1/application/update"
r = requests.post(url + endpoint, json=data, headers=headers)
print(r)
# Don't forget to add your HMAC Authorization Headers
ENDPOINT="$URL/marketplace/v1/application/update"
curl -X POST -H "date: $DATE" -H "Authorization: $HMAC_AUTH" -H "Content-Type:application/json" --data '{
"merchantContactInformation": [{
"contactType": "LOCATION",
"state": "CO",
"postalCode": "80111",
"address1": "0 Nowhere Ave.",
"email": "RAO.foo@FIRSTDATA.COM",
"url": "WWW.FD.COM",
"mobile": "5534253275",
"voice": "1239489489",
"country": "USA",
"name": "MMIS TEST PARAM",
"city": "ENGLEWOOD"
}, {
"contactType": "CORPORATE",
"state": "NE",
"postalCode": "68106",
"address1": "0 Nowhere Ave.",
"mobile": "5534253275",
"voice": "1239489489",
"country": "USA",
"name": "MMIS TEST PARAM",
"city": "OMAHA",
"email": "RAO.foo@FIRSTDATA.COM",
"url": "WWW.FD.COM"
}],
"merchantAttributesRequestInformation": [{
"orderId": "5812",
"highestTicket": 20,
"faceToFace": "100",
"phoneOrEmail": "0",
"businessWebsite": "WWW.FD.COM",
"typicalSaleAmount": 10,
"stateOfIncorporation": "LA",
"IRSFilingName": "MMIS TEST PARAM",
"IRSForeignIndicator": "A",
"guid": "174878B69E1617556"
}],
"contactsInformation": [{
"instName":"JP Morgan Chase",
"abaNumber": "021000021",
"accountNumber": "9898",
"ordinal": 2
}],
"employeeInformation": [{
"lastName": "RAO",
"firstName": "foo",
"ssn": "000000000",
"dateOfBirth": "1983-01-01",
"homeContactId": "111"
}],
"additionalMerchantDetails": [
{ "statementDelivery": "ONLINE" }
],
"merchantReferenceCode": "MERC",
"merchantType": "RETAIL",
"dbaName": "MMIS TEST PARAM",
"legalName": "MMIS TEST PARAM",
"taxId": "000000000",
"sicCode": " ",
"yearsInBusiness": "2002-01-01",
"yearsAtLocation": "2002-01-01",
"productDescription": "",
"createdByCoId": 10,
"billReferenceCode": "O",
"organizationTypeReferenceCode": "C"
}' $ENDPOINT
// Don't forget to add your HMAC Authorization Headers
var options = { method: 'POST',
url: url + '/marketplace/v1/application/update',
headers: getAuthenticationHeaders(),
body:
{ merchantContactInformation:
[ { contactType: 'LOCATION',
state: 'NE',
postalCode: '68127',
address1: '123 DONOT SHIP',
email: 'PA1N12@GMAIL.COM',
url: 'ABC.COM',
mobile: '4353534534',
voice: '3453453453',
country: 'USA',
name: 'MMIS TEST LEGAL',
city: 'OMAHA' },
{ contactType: 'CORPORATE',
state: 'NE',
postalCode: '68127',
address1: '123 DONOT SHIP',
address2: null,
mobile: '4353534534',
voice: '3453453453',
country: 'USA',
name: 'MMIS TEST LEGAL',
city: 'OMAHA',
email: 'PA1N12@GMAIL.COM',
url: 'ABC.COM' } ],
merchantAttributesRequestInformation:
[ { orderId: 13931,
highestTicket: 333,
faceToFace: '91',
phoneOrEmail: '6',
internet: '3',
businessWebsite: 'ABC.COM',
typicalSaleAmount: 32,
stateOfIncorporation: 'IA',
IRSFilingName: 'MMIS TEST LEGAL',
IRSForeignIndicator: 'N',
guid: '' } ],
contactsInformation:
[ { instName: 'JPMORGAN CHASE BANK, NA',
abaNumber: '122100024',
accountNumber: '12345',
ordinal: 2 } ],
employeeInformation:
[ { lastName: 'EMPLASTNAME',
firstName: 'EMPFIRSTNAME',
ssn: '989898989',
dateOfBirth: '1985-05-13',
title: 'VICE PRESIDENT',
homeContactId: '111' } ],
additionalMerchantDetails:
[ { statementDelivery: "ONLINE" } ],
siteSurvey:
{ siteVisitation: 'NOT REQUIRED',
surveyPerformed: 'F6MICSO',
businessZone: 'MALL',
merchantBusinessLocation: 'COMBINATION',
seasonalMerchant: 'YES',
totalFloors: '4',
floorOccupied: '4',
merchantsNameDisplayed: 'DOOR',
apartmentSquareFoot: '251-500',
merchantsOwnBuildSpace: 'OWN',
totalRegister: 1,
licenceDisplayed: 'YES',
returnPolicy: 'EXCHANGE ONLY',
separateRefundPolicy: 'YES',
customerDeposit: 'YES',
deliveryTimeFrame_0_To_7: '60',
deliveryTimeFrame_8_To_14: '40',
deliveryTimeFrame_15_To_30: '',
deliveryTimeFrame_Over_30: '',
salesDeposit: 'DATE OF DELIVERY',
autoRenew: 'YES' },
merchantReferenceCode: 'MERC',
merchantType: 'RETAIL',
dbaName: 'MMIS TEST LEGAL',
legalName: 'MMIS TEST LEGAL',
taxId: '989898989',
sicCode: ' ',
yearsInBusiness: '2003-09-01',
yearsAtLocation: '2003-09-01',
productDescription: '',
createdByCoId: 10,
billReferenceCode: 'O',
organizationTypeReferenceCode: 'C' },
json: true };
request(options, function (error, response, body) {
if (error) throw new Error(error);
console.log(response);
});
// Don't forget to add your HMAC Authorization Headers
try {
String jsonString = "{ \"merchantContactInformation\": [{\n" +
" \"contactType\": \"LOCATION\",\n" +
" \"state\": \"NE\",\n" +
" \"postalCode\": \"68127\",\n" +
" \"address1\": \"123 DONOT SHIP\",\n" +
" \"email\": \"PA1N12@GMAIL.COM\",\n" +
" \"url\": \"ABC.COM\",\n" +
" \"mobile\": \"4353534534\",\n" +
" \"voice\": \"3453453453\",\n" +
" \"country\": \"USA\",\n" +
" \"name\": \"MMIS TEST LEGAL\",\n" +
" \"city\": \"OMAHA\"\n" +
" }, {\n" +
" \"contactType\": \"CORPORATE\",\n" +
" \"state\": \"NE\",\n" +
" \"postalCode\": \"68127\",\n" +
" \"address1\": \"123 DONOT SHIP\",\n" +
" \"address2\": null,\n" +
" \"mobile\": \"4353534534\",\n" +
" \"voice\": \"3453453453\",\n" +
" \"country\": \"USA\",\n" +
" \"name\": \"MMIS TEST LEGAL\",\n" +
" \"city\": \"OMAHA\",\n" +
" \"email\": \"PA1N12@GMAIL.COM\",\n" +
" \"url\": \"ABC.COM\"\n" +
" }],\n" +
" \"merchantAttributesRequestInformation\": [{\n" +
" \"orderId\": 13931,\n" +
" \"highestTicket\": 333,\n" +
" \"faceToFace\": \"91\",\n" +
" \"phoneOrEmail\": \"6\",\n" +
" \"internet\": \"3\",\n" +
" \"businessWebsite\": \"ABC.COM\",\n" +
" \"typicalSaleAmount\": 32,\n" +
" \"stateOfIncorporation\": \"IA\",\n" +
" \"IRSFilingName\": \"MMIS TEST LEGAL\",\n" +
" \"IRSForeignIndicator\": \"N\",\n" +
" \"guid\": \"\"\n" +
" }],\n" +
" \"contactsInformation\": [{\n" +
" \"instName\": \"JPMORGAN CHASE BANK, NA\",\n" +
" \"abaNumber\": \"122100024\",\n" +
" \"accountNumber\": \"12345\",\n" +
" \"ordinal\": 2\n" +
" }],\n" +
" \"employeeInformation\": [{\n" +
" \"lastName\": \"EMPLASTNAME\",\n" +
" \"firstName\": \"EMPFIRSTNAME\",\n" +
" \"ssn\": \"989898989\",\n" +
" \"dateOfBirth\": \"1985-05-13\",\n" +
" \"title\": \"VICE PRESIDENT\",\n" +
" \"homeContactId\": \"111\"\n" +
" }],\n" +
" \"additionalMerchantDetails\": [{\n" +
" \"statementDelivery\": \"ONLINE\",\n" +
" }],\n" +
" \"siteSurvey\": {\n" +
" \"siteVisitation\": \"NOT REQUIRED\",\n" +
" \"surveyPerformed\": \"F6MICSO\",\n" +
" \"businessZone\": \"MALL\",\n" +
" \"merchantBusinessLocation\": \"COMBINATION\",\n" +
" \"seasonalMerchant\": \"YES\",\n" +
" \"totalFloors\": \"4\",\n" +
" \"floorOccupied\": \"4\",\n" +
" \"merchantsNameDisplayed\": \"DOOR\",\n" +
" \"apartmentSquareFoot\": \"251-500\",\n" +
" \"merchantsOwnBuildSpace\": \"OWN\",\n" +
" \"totalRegister\": 1,\n" +
" \"licenceDisplayed\": \"YES\",\n" +
" \"returnPolicy\": \"EXCHANGE ONLY\",\n" +
" \"separateRefundPolicy\": \"YES\",\n" +
" \"customerDeposit\": \"YES\",\n" +
" \"deliveryTimeFrame_0_To_7\": \"60\",\n" +
" \"deliveryTimeFrame_8_To_14\": \"40\",\n" +
" \"deliveryTimeFrame_15_To_30\": \"\",\n" +
" \"deliveryTimeFrame_Over_30\": \"\",\n" +
" \"salesDeposit\": \"DATE OF DELIVERY\",\n" +
" \"autoRenew\": \"YES\"\n" +
" },\n" +
" \"merchantReferenceCode\": \"MERC\",\n" +
" \"merchantType\": \"RETAIL\",\n" +
" \"dbaName\": \"MMIS TEST LEGAL\",\n" +
" \"legalName\": \"MMIS TEST LEGAL\",\n" +
" \"taxId\": \"989898989\",\n" +
" \"sicCode\": \" \",\n" +
" \"yearsInBusiness\": \"2003-09-01\",\n" +
" \"yearsAtLocation\": \"2003-09-01\",\n" +
" \"productDescription\": \"\",\n" +
" \"createdByCoId\": 10,\n" +
" \"billReferenceCode\": \"O\",\n" +
" \"organizationTypeReferenceCode\": \"C\"\n" +
"}";
StringEntity payload = new StringEntity(jsonString);
HttpResponse response = doPost("/marketplace/v1/application/update", payload);
int statusCode = response.getStatusLine().getStatusCode();
String response_string = EntityUtils.toString(response.getEntity());
JSONArray json = new JSONArray(response_string);
System.out.println("json:" + json.toString());
} catch (Exception e) {
e.printStackTrace();
}
<?php
# Don't forget to add your HMAC Authorization Headers
$data = array (
'merchantContactInformation' =>
array (
0 =>
array (
'contactType' => 'LOCATION',
'state' => 'NE',
'postalCode' => '68127',
'address1' => '123 DONOT SHIP',
'email' => 'PA1N12@GMAIL.COM',
'url' => 'ABC.COM',
'mobile' => '4353534534',
'voice' => '3453453453',
'country' => 'USA',
'name' => 'MMIS TEST LEGAL',
'city' => 'OMAHA',
),
1 =>
array (
'contactType' => 'CORPORATE',
'state' => 'NE',
'postalCode' => '68127',
'address1' => '123 DONOT SHIP',
'address2' => 'null',
'mobile' => '4353534534',
'voice' => '3453453453',
'country' => 'USA',
'name' => 'MMIS TEST LEGAL',
'city' => 'OMAHA',
'email' => 'PA1N12@GMAIL.COM',
'url' => 'ABC.COM',
),
),
'merchantAttributesRequestInformation' =>
array (
0 =>
array (
'orderId' => 13931,
'highestTicket' => 333,
'faceToFace' => '91',
'phoneOrEmail' => '6',
'internet' => '3',
'businessWebsite' => 'ABC.COM',
'typicalSaleAmount' => 32,
'stateOfIncorporation' => 'IA',
'IRSFilingName' => 'MMIS TEST LEGAL',
'IRSForeignIndicator' => 'N',
'guid' => '',
),
),
'contactsInformation' =>
array (
0 =>
array (
'instName' => 'JPMORGAN CHASE BANK, NA',
'abaNumber' => '122100024',
'accountNumber' => '12345',
'ordinal' => 2,
),
),
'employeeInformation' =>
array (
0 =>
array (
'lastName' => 'EMPLASTNAME',
'firstName' => 'EMPFIRSTNAME',
'ssn' => '989898989',
'dateOfBirth' => '1985-05-13',
'title' => 'VICE PRESIDENT',
'homeContactId' => '111',
),
),
'additionalMerchantDetails' =>
array (
0 =>
array (
'statementDelivery' => 'ONLINE',
),
),
'siteSurvey' =>
array (
'siteVisitation' => 'NOT REQUIRED',
'surveyPerformed' => 'F6MICSO',
'businessZone' => 'MALL',
'merchantBusinessLocation' => 'COMBINATION',
'seasonalMerchant' => 'YES',
'totalFloors' => '4',
'floorOccupied' => '4',
'merchantsNameDisplayed' => 'DOOR',
'apartmentSquareFoot' => '251-500',
'merchantsOwnBuildSpace' => 'OWN',
'totalRegister' => 1,
'licenceDisplayed' => 'YES',
'returnPolicy' => 'EXCHANGE ONLY',
'separateRefundPolicy' => 'YES',
'customerDeposit' => 'YES',
'deliveryTimeFrame_0_To_7' => '60',
'deliveryTimeFrame_8_To_14' => '40',
'deliveryTimeFrame_15_To_30' => '',
'deliveryTimeFrame_Over_30' => '',
'salesDeposit' => 'DATE OF DELIVERY',
'autoRenew' => 'YES',
),
'merchantReferenceCode' => 'MERC',
'merchantType' => 'RETAIL',
'dbaName' => 'MMIS TEST LEGAL',
'legalName' => 'MMIS TEST LEGAL',
'taxId' => '989898989',
'sicCode' => ' ',
'yearsInBusiness' => '2003-09-01',
'yearsAtLocation' => '2003-09-01',
'productDescription' => '',
'createdByCoId' => 10,
'billReferenceCode' => 'O',
'organizationTypeReferenceCode' => 'C',
);
$data_json = json_encode($data);
$headers = array(
'date: ' . $date,
'Authorization: ' . $hmacAuth,
'Content-Type: application/json',
'Content-Length: ' . strlen($data_json)
);
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url . "/marketplace/v1/application/update");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data_json);
$res = curl_exec($ch);
echo($res);
?>
Example payload:
update.json(partial file - see full file on Github)
{
"merchantContactInformation": [{
"contactType": "LOCATION",
"state": "NE",
"postalCode": "68127",
"address1": "123 DONOT SHIP",
"email": "PA1N12@GMAIL.COM",
"url": "ABC.COM",
"mobile": "4353534534",
"voice": "3453453453",
"country": "USA",
"name": "MMIS TEST LEGAL",
"city": "OMAHA"
}, {
"contactType": "CORPORATE",
"state": "NE",
"postalCode": "68127",
"address1": "123 DONOT SHIP",
"address2": "null",
"mobile": "4353534534",
"voice": "3453453453",
"country": "USA",
"name": "MMIS TEST LEGAL",
"city": "OMAHA",
"email": "PA1N12@GMAIL.COM",
"url": "ABC.COM"
}],
"merchantAttributesRequestInformation": [{
"orderId": 13931,
"highestTicket": 333,
"faceToFace": "91",
"phoneOrEmail": "6",
"internet": "3",
"businessWebsite": "ABC.COM",
"typicalSaleAmount": 32,
"stateOfIncorporation": "IA",
"IRSFilingName": "MMIS TEST LEGAL",
"IRSForeignIndicator": "N",
"guid": ""
}],
"contactsInformation": [{
"instName": "JPMORGAN CHASE BANK, NA",
"abaNumber": "122100024",
"accountNumber": "12345",
"ordinal": 2
}],
"employeeInformation": [{
"lastName": "EMPLASTNAME",
"firstName": "EMPFIRSTNAME",
"ssn": "989898989",
"dateOfBirth": "1985-05-13",
"title": "VICE PRESIDENT",
"homeContactId": "111"
}],
"additionalMerchantDetails": [
{ "statementDelivery": "ONLINE" }
],
"siteSurvey": {
"siteVisitation": "NOT REQUIRED",
"surveyPerformed": "F6MICSO",
"businessZone": "MALL",
"merchantBusinessLocation": "COMBINATION",
"seasonalMerchant": "YES",
"totalFloors": "4",
"floorOccupied": "4",
"merchantsNameDisplayed": "DOOR",
"apartmentSquareFoot": "251-500",
"merchantsOwnBuildSpace": "OWN",
"totalRegister": 1,
"licenceDisplayed": "YES",
"returnPolicy": "EXCHANGE ONLY",
"separateRefundPolicy": "YES",
"customerDeposit": "YES",
"deliveryTimeFrame_0_To_7": "60",
"deliveryTimeFrame_8_To_14": "40",
"deliveryTimeFrame_15_To_30": "",
"deliveryTimeFrame_Over_30": "",
"salesDeposit": "DATE OF DELIVERY",
"autoRenew": "YES"
},
"merchantReferenceCode": "MERC",
"merchantType": "RETAIL",
"dbaName": "MMIS TEST LEGAL",
"legalName": "MMIS TEST LEGAL",
"taxId": "989898989",
"sicCode": " ",
"yearsInBusiness": "2003-09-01",
"yearsAtLocation": "2003-09-01",
"productDescription": "",
"createdByCoId": 10,
"billReferenceCode": "O",
"organizationTypeReferenceCode": "C"
}
The above command returns JSON structured like this:
{
"orderRefId": "5812",
"orderHash": "Order Delivered",
"merchantId": 6333,
"orderIdForMerchant": 5812,
"errorText": ""
}
This endpoint submits the Merchant Application form.
Note: This request should only occur after the user has completed all of the required fields.
Request
POST /marketplace/v1/application/update
| Parameter | Required | Data Type | Short Description |
|---|---|---|---|
| merchantAttributes RequestInformation | ✔ | array | Array of (minimum one) object(s) that is required to submit the application form. |
| orderId | ✔ | integer | orderId as it was returned in the response of the POST Application/Checkout API. |
| highestTicket | double | Actual or estimated highest ticket price in USD. | |
| faceToFace | integer | Percentage of payments/transactions made face to face (can’t exceed 100%). | |
| phoneOrEmail | integer | Percentage of payments/transactions made by phone or email (can’t exceed 100%). | |
| internet | integer | Percentage of payments/transactions made on the internet (can’t exceed 100%). | |
| businessWebsite | string | URL of business website. | |
| typicalSaleAmount | double | Actual or estimated average ticket price in USD. Values for averageTicket may be used to populate this field. | |
| stateOfIncorporation | string | State of incorporation in abbreviated format. i.e. for California send "CA". | |
| IRSFilingName | string | IRS tax filing name for the business. Needs to be validated against taxId using the POST TIN/Validate service. | |
| IRSForeignIndicator | string | Indicates if the business can claim foreign status according to IRS regulations. Possible values: "Y" or "N". | |
| guid | string | Universal ID for the request of the POST TIN/Validate service. | |
| merchantContactInformation | array | Array of (minimum one) object(s) that collects business information. Contains name, address1, address2, city, state, postalCode, country, email, url, mobile and voice. | |
| name | string | Business name. | |
| address1 | string | Street address of the business. | |
| address2 | string | Second line of street address, if applicable. i.e. Unit, Floor, Suite etc. | |
| city | string | City the business is located in. | |
| state | string | State the business is located in, in abbreviated format. i.e. for California send "CA". | |
| postalCode | string | Business ZIP code. | |
| country | string | Country the business is located in. | |
string | Primary contact email address. | ||
| url | string | URL of business website, can be populated from same input as businessWebsite. | |
| mobile | string | Primary contact cell phone number. | |
| voice | string | Primary contact phone number OR business primary phone number. | |
| contactsInformation | array | Array of (minimum one) object(s) that collects the ACH information abaNumber and accountNumber. | |
| abaNumber | string | ABA routing transit number. A nine digit code to identify a financial institution. Needs to be validated using the POST Banks/Validate service. | |
| accountNumber | string | Checking account number. Usually 10-12 digit number to identify the merchant’s account. | |
| employeeInformation | array | Array of (minimum one) object(s) to collect information about the owner(s) of the business. Contains firstName, lastName, ssn, dateOfBirth and homeContactId. | |
| lastName | string | Owner’s last name. | |
| firstName | string | Owner’s first name. | |
| ssn | string | Owner’s Social Security Number in “#########” format. | |
| dateOfBirth | string | Owner’s date of birth in “YYYY-MM-DD” format. | |
| homeContactId | string | Home Contact Id Number. Not required, but if sent always default to "111". | |
| additionalMerchantDetails | ✔ | object | Additional information including statement delivery. |
| statementDelivery | ✔ | string | Preference on how statements should be delivered to merchant. Default to "ONLINE". |
| dbaName | string | DBA name. | |
| legalName | string | Legal business name. | |
| taxId | string | A Taxpayer Identification Number (TIN) is an identification number used by the Internal Revenue Service (IRS). Needs to be validated against IRSFilingName using the POST TIN/Validate service. | |
| yearsInBusiness | string | Number of years in business. | |
| yearsAtLocation | string | Number of years the business has been operating at the current location. | |
| billReferenceCode | string | Billing Reference code. Not required, but if sent always default to "O". | |
| organizationTypeReferenceCode | string | Organization type represented by an abbreviated code. See possible values here. |
Possible values for organizationTypeReferenceCode
| Value | Meaning |
|---|---|
"I" | Sole Proprietorship |
"P" | Partnership |
"C" | Public Corporation |
"PRC" | Private Corporation |
"L" | Limited Liability Company |
"T" | Tax Exempt |
"G" | Government |
Response
The endpoint returns an object containing the Application Form submission results. The following parameters may be in each object returned.
| Parameter | Data Type | Description |
|---|---|---|
| orderRefId | string | Order Id. |
| orderHash | string | Order hash value. |
| merchantId | integer | Merchant Id. |
| orderIdForMerchant | integer | Order Id for merchant. |
| errorText | string | Error text. |
POST Identity/Questions
# Don't forget to add your HMAC Authorization Headers
data = {
"orderId": "15407"
}
endpoint = "/marketplace/v1/identity/questions"
r = requests.post(url + endpoint, json=data, headers=headers)
print(r.text)
# Don't forget to add your HMAC Authorization Headers
ENDPOINT="$URL/marketplace/v1/identity/questions"
curl -X POST -H "date: $DATE" -H "Authorization: $HMAC_AUTH" -H "Content-Type:application/json" --data '{ "orderId": "15407" }' $ENDPOINT
// Don't forget to add your HMAC Authorization Headers
var options = { method: 'POST',
url: url + '/marketplace/v1/identity/questions',
headers: getAuthenticationHeaders(),
body: {
"orderId": "15407"
},
json: true
};
request(options, function (error, response, body) {
if (error) throw new Error(error);
console.log(response);
});
// Don't forget to add your HMAC Authorization Headers
try {
String jsonString = "{\n" +
" \"orderId\": \"15407\"\n" +
"}";
StringEntity payload = new StringEntity(jsonString);
HttpResponse response = doPost("/marketplace/v1/identity/questions", payload);
int statusCode = response.getStatusLine().getStatusCode();
String response_string = EntityUtils.toString(response.getEntity());
JSONObject json = new JSONObject(response_string);
System.out.println("json:" + json.toString());
} catch (Exception e) {
e.printStackTrace();
}
<?php
# Don't forget to add your HMAC Authorization Headers
$data = array (
'orderId' => '15407',
);
$data_json = json_encode($data);
$headers = array(
'date: ' . $date,
'Authorization: ' . $hmacAuth,
'Content-Type: application/json',
'Content-Length: ' . strlen($data_json)
);
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url . "/marketplace/v1/identity/questions");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data_json);
$res = curl_exec($ch);
echo($res);
?>
The above command returns JSON structured like this:
Success response
{
"idologyQuestionsResponse": {
"response": {
"idNumber": 1075647199,
"questions": {
"question": [{
"answer": [
"Less than 2 years",
"2 - 3 years",
"3 - 4 years",
"4 - 5 years",
"Over 5 years",
"None of the above",
"Skip Question"
],
"type": "time.at.current.address",
"prompt": "How long have you been associated with the property at 3210 TOTH RD?"
}, {
"answer": [
"ST MARY'S MEDICAL CENTER",
"CENTENNIAL PEAKS HOSPITAL",
"SAINT JOSEPH HOSPITAL",
"ADVOCATE GOOD SHEPHERD HOSP",
"TRINITY MEDICAL CENTER",
"SAINT NICHOLAS HOSPITAL",
"Skip Question"
],
"type": "geo.closest.hospital",
"prompt": "Which of these hospitals is closest to your address on TOTH RD?"
}, {
"answer": [
"Michigan",
"Virginia",
"Connecticut",
"Kansas",
"Nevada",
"None of the above",
"Skip Question"
],
"type": "ssn.issued.in",
"prompt": "Where was your social security number issued?"
}, {
"answer": [
"SAGINAW",
"COATSBURG",
"NORTH TARRYTOWN",
"WEST HAVEN",
"WORTHINGTON",
"None of the above",
"Skip Question"
],
"type": "city.of.residence",
"prompt": "In which city is JANES AVE?"
}]
},
"qualifiers": {
"qualifier": [{
"message": "Address Does Not Match",
"key": "resultcode.address.does.not.match"
}, {
"message": "Street Number Does Not Match",
"key": "resultcode.street.number.does.not.match"
}, {
"message": "Street Name Does Not Match",
"key": "resultcode.street.name.does.not.match"
}]
},
"summary-result": {
"message": "PASS",
"key": "id.success"
},
"results": {
"message": "ID Located",
"key": "result.match"
}
}
},
"message": "Success"
}
Example error response. This response indicated that the provided information (TIN information) could not be associated with a known record.
{
"code": 1030,
"additional message": "Error received from Idology Question service",
"message": "Error Retrieving Idology Questions"
}
This endpoint returns the multiple-choice questions and the list of possible answers for each of them. These can be presented to the user to verify their identity. The user’s answers are then submitted using the POST Identity/Answers endpoint.
This service uses the TIN information after submitting the Merchant Application using the POST Application/Update endpoint.
Request
POST /marketplace/v1/identity/questions
| Parameter | Required | Data Type | Description |
|---|---|---|---|
| orderId | ✔ | string | orderId as it was returned in the response of the POST Application/Checkout API. |
Response
The endpoint returns an object containing the results of the record lookup, and if the record is successfully located (see message), a list of multiple-choice questions and the list of possible answers for each. The following parameters may be in each object returned.
| Parameter | Data Type | Description |
|---|---|---|
| message | string | Response message from the service. In case a record is found it is "Success." In case of error it provides details about the problem together with code and additional message. |
| code | integer | In case of error it is the error code. |
| additional message | string | In case of error it provides additional information on the problem. |
| idologyQuestionsResponse | object | Wrapper object containing the response. |
| response | object | Object containing the questions, possible answers and request identification. Contains idNumber, questions, qualifiers, summary-result and results. |
| idNumber | integer | Unique identification for the identity verification for this record. Used as input in the POST Identity/Answers endpoint. |
| questions | object | Collection of 4 objects, each representing a multiple choice question (question) to present to the user. |
| question | array | One question entry. Contains prompt, answer and type. |
| ↳ answer | array | An array of string each representing a possible answer to the multiple choice question. |
| ↳ type | string | String identifier of the question to use as input in the POST Identity/Answers endpoint. |
| ↳ prompt | string | The question label to show in the user interface or to ask to the user. |
| qualifiers | object | Wrapper object containing qualifying messages (qualifier arrays). This provides information on the record lookup based on verifying the data provided before, such as the address, TIN, name, etc. |
| qualifier | array | One qualifier message. Contains key and message. |
| ↳ message | string | Display message for the qualifier. |
| ↳ key | string | Message identifier for the qualifier. |
| summary-result | object | Wrapper object containing result of the record lookup. This provides information on the success or failure to locate the record to verify. Contains key and message. |
| ↳ message | string | Display message for summary-results: "PASS" or "FAIL". |
| ↳ key | string | Message identifier for summary-results. |
| results | object | Wrapper object containing result of the record lookup. This provides information on the success or failure to locate the record to verify. Contains key and message. |
| ↳ message | string | Display message for results. |
| ↳ key | string | Message identifier for results. |
POST Identity/Answers
# Don't forget to add your HMAC Authorization Headers
data = {
"merchantOrderId":"15407",
"responseId":"1075647199",
"idologyAnswersList": [{
"questionType":"time.at.current.address",
"questionAnswer":"Less+than+2+years"
}, {
"questionType":"geo.closest.hospital",
"questionAnswer":"ST+MARY'S+MEDICAL+CENTER"
}, {
"questionType":"ssn.issued.in",
"questionAnswer":"Michigan"
}]
}
endpoint = "/marketplace/v1/identity/answers"
r = requests.post(url + endpoint, json=data, headers=headers)
print(r.text)
# Don't forget to add your HMAC Authorization Headers
ENDPOINT="$URL/marketplace/v1/identity/answers"
curl -X POST -H "date: $DATE" -H "Authorization: $HMAC_AUTH" -H "Content-Type:application/json" --data '{
"merchantOrderId":"15407",
"responseId":"1075647199",
"idologyAnswersList": [{
"questionType":"time.at.current.address",
"questionAnswer":"Less+than+2+years"
}, {
"questionType":"geo.closest.hospital",
"questionAnswer":"ST+MARY'S+MEDICAL+CENTER"
}, {
"questionType":"ssn.issued.in",
"questionAnswer":"Michigan"
}]
}' $ENDPOINT
// Don't forget to add your HMAC Authorization Headers
var options = { method: 'POST',
url: url + '/marketplace/v1/identity/answers',
headers: getAuthenticationHeaders(),
body:
{
"merchantOrderId":"15407",
"responseId":"1075647199",
"idologyAnswersList": [{
"questionType":"time.at.current.address",
"questionAnswer":"Less+than+2+years"
}, {
"questionType":"geo.closest.hospital",
"questionAnswer":"ST+MARY'S+MEDICAL+CENTER"
}, {
"questionType":"ssn.issued.in",
"questionAnswer":"Michigan"
}]
},
json: true };
request(options, function (error, response, body) {
if (error) throw new Error(error);
console.log(body);
});
// Don't forget to add your HMAC Authorization Headers
try {
String jsonString = "{\n" +
"\"merchantOrderId\":\"15407\",\n" +
"\"responseId\":\"1075647199\",\n"+
"\"idologyAnswersList\":\n" +
"[\n" +
"{\"questionAnswer\":\"Less+than+2+years\",\"questionType\":\"time.at.current.address\"},\n" +
"{\"questionAnswer\":\"ST+MARY'S+MEDICAL+CENTER\",\"questionType\":\"geo.closest.hospital\"},\n" +
"{\"questionAnswer\":\"Michigan\",\"questionType\":\"ssn.issued.in\"}\n" +
"]\n" +
"}";
StringEntity payload = new StringEntity(jsonString);
HttpResponse response = doPost("/marketplace/v1/identity/answers", payload);
int statusCode = response.getStatusLine().getStatusCode();
String response_string = EntityUtils.toString(response.getEntity());
JSONObject json = new JSONObject(response_string);
System.out.println("json:" + json.toString());
} catch (Exception e) {
e.printStackTrace();
}
<?php
# Don't forget to add your HMAC Authorization Headers
$data = array (
'merchantOrderId' => '15407',
'responseId' => '1075647199',
'idologyAnswersList' =>
array (
0 =>
array (
'questionType' => 'time.at.current.address',
'questionAnswer' => 'Less+than+2+years'
),
1 =>
array (
'questionType' => 'geo.closest.hospital',
'questionAnswer' => 'ST+MARY'S+MEDICAL+CENTER'
),
2 =>
array (
'questionType' => 'ssn.issued.in',
'questionAnswer' => 'Michigan'
),
),
),
);
$data_json = json_encode($data);
$headers = array(
'date: ' . $date,
'Authorization: ' . $hmacAuth,
'Content-Type: application/json',
'Content-Length: ' . strlen($data_json)
);
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url . "/marketplace/v1/identity/answers");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data_json);
$res = curl_exec($ch);
echo($res);
?>
The above command returns JSON structured like this:
Success response
{
"response": {
"idNumber": 1076900839,
"qualifiers": {
"qualifier": [
{
"message": "Address Does Not Match",
"key": "resultcode.address.does.not.match"
},
{
"message": "Street Number Does Not Match",
"key": "resultcode.street.number.does.not.match"
},
{
"message": "Street Name Does Not Match",
"key": "resultcode.street.name.does.not.match"
}
]
},
"idliveq-result": {
"message": "Two Incorrect Answers",
"key": "result.questions.2.incorrect"
},
"summary-result": {
"message": "PASS",
"key": "id.success"
},
"answers-received": 3,
"results": {
"message": "ID Located",
"key": "result.match"
}
}
}
This endpoint returns the results of the identity verification.
It uses the input from the user as they answer the questions presented to them from the POST Identity/Questions endpoint.
Request
POST /marketplace/v1/identity/answers
| Parameter | Required | Data Type | Description |
|---|---|---|---|
| merchantOrderId | ✔ | string | orderId as it was returned in the response of the POST Application/Checkout API. Same as in previous service. |
| responseId | ✔ | string | Numeric response ID (idNumber) that was returned by the POST Identity/Questions service. |
| idologyAnswersList | ✔ | array | Array of object each representing and answer (containing questionType and questionAnswer pairs) from the user. You must send 3 answer objects. |
| questionType | ✔ | string | String identifier of the question returned by the POST Identity/Questions service. |
| questionAnswer | ✔ | string | The user’s choice from the answer array returned by the POST Identity/Questions service. |
Response
The endpoint returns an object containing the results of the identity verification. The following parameters may be in each object returned.
| Parameter | Data Type | Description |
|---|---|---|
| response | object | Object containing the verification results. Contains idNumber, answers-received, idequiv-result, qualifiers, summary-result and results. |
| idNumber | integer | Unique identification for the Identity Verification for this record. |
| answers-received | integer | Number of answers received. Note: You must send 3 answers in order to get a successful response. |
| idequiv-result | object | Wrapper object containing result of the overall submission. Contains key and message. |
| ↳ message | string | Display message for idequiv-result. |
| ↳ key | string | Message identifier for idequiv-result. |
| qualifiers | object | Wrapper object containing qualifying messages (qualifier arrays). This provides information on the record lookup based on verifying the data provided before, such as the address, TIN, name, etc. |
| qualifier | array | One qualifier message. Contains key and message. |
| ↳ message | string | Display message for the qualifier. |
| ↳ key | string | Message identifier for the qualifier. |
| summary-result | object | Wrapper object containing result of the record lookup. This provides information on the success or failure to locate the record to verify. Contains key and message. |
| ↳ message | string | Display message for summary message: "PASS" or "FAIL". |
| ↳ key | string | Message identifier for summary-results. |
| results | object | Wrapper object containing result of the record lookup. This provides information on the success or failure to locate the record to verify. Contains key and message. |
| ↳ message | string | Display message for results. |
| ↳ key | string | Message identifier for results. |
POST Merchant/Identity
# Don't forget to add your HMAC Authorization Headers
data = {
"firstName": "John",
"lastName": "Smith",
"taxId": "351762213",
"addressLine1": "123 Main Street",
"postalCode": "12345",
"city": "Schenectady",
"state": "NY",
"dateofBirth": "04/15/1975"
}
endpoint = "/marketplace/v1/merchant/identity/questions "
r = requests.post(url + endpoint, json=data, headers=headers)
print(r.text)
# Don't forget to add your HMAC Authorization Headers
ENDPOINT="$URL/marketplace/v1/merchant/identity/questions "
curl -X POST -H "date: $DATE" -H "Authorization: $HMAC_AUTH" -H "Content-Type:application/json" --data '{
"firstName": "John",
"lastName": "Smith",
"taxId": "351762213",
"addressLine1": "123 Main Street",
"postalCode": "12345",
"city": "Schenectady",
"state": "NY",
"dateofBirth": "04/15/1975"
}' $ENDPOINT
// Don't forget to add your HMAC Authorization Headers
var options = { method: 'POST',
url: url + '/marketplace/v1/merchant/identity/questions ',
headers: getAuthenticationHeaders(),
body:
{
"firstName": "John",
"lastName": "Smith",
"taxId": "351762213",
"addressLine1": "123 Main Street",
"postalCode": "12345",
"city": "Schenectady",
"state": "NY",
"dateofBirth": "04/15/1975"
},
json: true };
request(options, function (error, response, body) {
if (error) throw new Error(error);
console.log(body);
});
// Don't forget to add your HMAC Authorization Headers
try {
String jsonString = "{\n" +
" \"firstName\": \"John\",\n" +
" \"lastName\": \"Smith\",\n" +
" \"taxId\": \"351762213\",\n" +
" \"addressLine1\": \"123 Main Street\",\n" +
" \"postalCode\": \"12345\",\n" +
" \"city\": \"Schenectady\",\n" +
" \"state\": \"NY\",\n" +
" \"dateofBirth\": \"04/15/1975\"\n" +
"}";
StringEntity payload = new StringEntity(jsonString);
HttpResponse response = doPost("/marketplace/v1/merchant/identity/questions ", payload);
int statusCode = response.getStatusLine().getStatusCode();
String response_string = EntityUtils.toString(response.getEntity());
JSONObject json = new JSONObject(response_string);
System.out.println("json:" + json.toString());
} catch (Exception e) {
e.printStackTrace();
}
<?php
# Don't forget to add your HMAC Authorization Headers
$data = array (
'firstName' => 'John',
'lastName' => 'Smith',
'taxId' => '351762213',
'addressLine1' => '123 Main Street',
'postalCode' => '12345',
'city' => 'Schenectady',
'state' => 'NY',
'dateofBirth' => '04/15/1975',
);
$data_json = json_encode($data);
$headers = array(
'date: ' . $date,
'Authorization: ' . $hmacAuth,
'Content-Type: application/json',
'Content-Length: ' . strlen($data_json)
);
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url . "/marketplace/v1/merchant/identity/questions ");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data_json);
$res = curl_exec($ch);
echo($res);
?>
The above command returns JSON structured like this:
Success response
{
"idologyQuestionsResponse": {
"response": {
"idNumber": 1075647199,
"questions": {
"question": [{
"answer": [
"Less than 2 years",
"2 - 3 years",
"3 - 4 years",
"4 - 5 years",
"Over 5 years",
"None of the above",
"Skip Question"
],
"type": "time.at.current.address",
"prompt": "How long have you been associated with the property at 3210 TOTH RD?"
}, {
"answer": [
"ST MARY'S MEDICAL CENTER",
"CENTENNIAL PEAKS HOSPITAL",
"SAINT JOSEPH HOSPITAL",
"ADVOCATE GOOD SHEPHERD HOSP",
"TRINITY MEDICAL CENTER",
"SAINT NICHOLAS HOSPITAL",
"Skip Question"
],
"type": "geo.closest.hospital",
"prompt": "Which of these hospitals is closest to your address on TOTH RD?"
}, {
"answer": [
"Michigan",
"Virginia",
"Connecticut",
"Kansas",
"Nevada",
"None of the above",
"Skip Question"
],
"type": "ssn.issued.in",
"prompt": "Where was your social security number issued?"
}, {
"answer": [
"SAGINAW",
"COATSBURG",
"NORTH TARRYTOWN",
"WEST HAVEN",
"WORTHINGTON",
"None of the above",
"Skip Question"
],
"type": "city.of.residence",
"prompt": "In which city is JANES AVE?"
}]
},
"qualifiers": {
"qualifier": [{
"message": "Address Does Not Match",
"key": "resultcode.address.does.not.match"
}, {
"message": "Street Number Does Not Match",
"key": "resultcode.street.number.does.not.match"
}, {
"message": "Street Name Does Not Match",
"key": "resultcode.street.name.does.not.match"
}]
},
"summary-result": {
"message": "PASS",
"key": "id.success"
},
"results": {
"message": "ID Located",
"key": "result.match"
}
}
},
"message": "Success"
}
Example error response. This response indicated that the provided information (TIN information) could not be associated with a known record.
{
"code": 1030,
"additional message": "Error received from Idology Question service",
"message": "Error Retrieving Idology Questions"
}
This endpoint returns a list of multiple-choice questions and the list of possible answers for each of them. These can be presented to the user to verify their identity.
Request
POST /marketplace/v1/merchant/identity/questions
| Parameter | Required | Data Type | Description |
|---|---|---|---|
| firstName | ✔ | string | Owner’s first name. |
| lastName | ✔ | string | Owner’s last name. |
| taxId | ✔ | string | Owner’s Taxpayer Identification Number: SSN. |
| addressLine1 | ✔ | string | Street address. |
| postalCode | ✔ | string | ZIP/postal code. |
| city | ✔ | string | City. |
| state | ✔ | string | State in abbreviated format. i.e. for California send "CA". |
| dateofBirth | ✔ | string | Owner’s date of birth in “MM/DD/YYYY” format. |
Response
The endpoint returns an object containing the results of the record lookup, and if the record is successfully located (see message), a list of multiple-choice questions and the list of possible answers for each. The following parameters may be in each object returned.
| Parameter | Data Type | Description |
|---|---|---|
| message | string | Response message from the service. In case a record is found it is "Success." |
| idologyQuestionsResponse | object | Wrapper object containing the response. |
| response | object | Object containing the questions, possible answers and request identification. Contains idNumber, questions, qualifiers, summary-result and results. |
| idNumber | integer | Unique identification for the identity verification for this record. Used as input in the POST Identity/Answers endpoint. |
| questions | object | Collection of 4 objects, each representing a multiple choice question (question) to present to the user. |
| question | array | One question entry. Contains prompt, answer and type. |
| answer | array | An array of string each representing a possible answer to the multiple choice question. |
| type | string | String identifier of the question to use as input in the POST Identity/Answers endpoint. |
| prompt | string | The question label to show in the user interface or to ask to the user. |
| qualifiers | object | Wrapper object containing qualifying messages (qualifier arrays). This provides information on the record lookup based on verifying the data provided before, such as the address, TIN, name, etc. |
| qualifier | array | One qualifier message. Contains key and message. |
| message | string | Display message for the qualifier. |
| key | string | Message identifier for the qualifier. |
| summary-result | object | Wrapper object containing result of the record lookup. This provides information on the success or failure to locate the record to verify. Contains key and message. |
| message | string | Display message for summary-results: "PASS" or "FAIL". |
| key | string | Message identifier for summary-results. |
| results | object | Wrapper object containing result of the record lookup. This provides information on the success or failure to locate the record to verify. Contains key and message. |
| message | string | Display message for results. |
| key | string | Message identifier for results. |
Response in case of error:
| Parameter | Data Type | Description |
|---|---|---|
| message | string | Response message from the service. In case a record is found it is "Success." In case of error it provides details about the problem together with code and additional message. |
| code | integer | In case of error it is the error code. |
| additional message | string | In case of error it provides additional information on the problem. |
POST Merchantapplication/SingleOutlet-WithCreditDecision
data = {
"shippingAddress": {
"city": "Schenectady",
"productsToShip": [
{
"term": "P",
"productId": "87862"
}
],
"firstName": "John",
"country": "US",
"address2": "",
"email": "john.smith@emailaddress.com",
"phone": "1234567890",
"state": "NY",
"lastName": "Smith",
"postalCode": "12345",
"address1": "123 Main Street",
"company": "Jonhs Cafe"
},
"merchantInformation": {
"siteSurvey": {
"deliveryTimeFrame_8_To_14": "0",
"deliveryTimeFrame_0_To_7": "100",
"deliveryTimeFrame_Over_30": "0",
"deliveryTimeFrame_15_To_30": "0"
},
"stateOfIncorporation": "NY",
"foreignEntityOption": "N",
"taxId": "666321471",
"contactInformation": [
{
"city": "Schenectady",
"country": "US",
"address2": "",
"contactType": "CORPORATE",
"phone": "1234567890",
"state": "NY",
"address1": "123 Main Street",
"postalCode": "12345",
"email": "john.smith@emailaddress.com"
}
],
"bankInformation": [
{
"ordinal": 2,
"accountNumber": "788723721",
"abaNumber": "122100024",
"bankCity": "COLUMBUS",
"bankState": "OH",
"instName": "JPMORGAN CHASE BANK, NA",
"bankZip": "43240"
}
],
"taxFilingName": "MMISTEST0318201902",
"transactionInfo": {
"averageTicket": 10,
"category": "Restaurant",
"creditCardVolume": 100000,
"annualVolume": 100000,
"amexSENumber": "",
"mcc": "5812",
"methodofPayment": {
"faceToFace": "100",
"phoneOrEmail": "0",
"internet": "0"
},
"mccDescription": "Restaurants, Eating Places",
"highestTicket": 11
},
"legalName": "MMISTEST0318201902",
"dbaName": "MMISTEST0318201902",
"businessStartedOn": "2009-01-01",
"organizationType": "SOLE_PROPRIETORSHIP",
"tinType": "SSN"
},
"ownerInformation": [
{
"percentOwned": 100,
"firstName": "John",
"title": "Owner",
"lastName": "Smith",
"contactInformation": {
"city": "Schenectady",
"country": "US",
"address2": "",
"contactType": "OWNER",
"phone": "1234567890",
"state": "NY",
"address1": "123 Main Street",
"postalCode": "12345",
"email": "john.smith@emailaddress.com"
},
"dateofBirth": "1975-02-28",
"ssn": "666321471"
}
],
"compaign":
{
"orignatingoffer":"468209433250",
"keyWords":"",
"leadType":"Digital",
"offerCode":"khL4pD",
"source":"google",
"medium":"ppc",
"placement":"105411458562",
"compaignName":"Clover_PPC_450offer"
},
"pricingDetails": [
{
"feeDefault": 0,
"purchaseType": "P",
"defaultAmt": 1149,
"quantity": 1,
"rateDefault": 0,
"productId": "87862"
},
{
"feeDefault": 0,
"productId": "54562",
"defaultAmt": 0,
"rateDefault": 0,
"quantity": 1
},
{
"feeDefault": 0,
"productId": "59462",
"defaultAmt": 0,
"rateDefault": 0,
"quantity": 1
},
{
"feeDefault": 0,
"productId": "71762",
"defaultAmt": 19.95,
"rateDefault": 0,
"quantity": 1
},
{
"feeDefault": 0.1,
"productId": "80382",
"defaultAmt": 0,
"rateDefault": 2.7,
"quantity": 1
},
{
"feeDefault": 0.1,
"productId": "80402",
"defaultAmt": 0,
"rateDefault": 3.5,
"quantity": 1
},
{
"feeDefault": 0,
"productId": "49872",
"defaultAmt": 25,
"rateDefault": 0,
"quantity": 1
},
{
"feeDefault": 0,
"productId": "45608",
"defaultAmt": 0,
"rateDefault": 0,
"quantity": 1
},
{
"feeDefault": 0,
"productId": "46164",
"defaultAmt": 0,
"rateDefault": 0,
"quantity": 1
},
{
"feeDefault": 0,
"productId": "46657",
"defaultAmt": 25,
"rateDefault": 0,
"quantity": 1
},
{
"feeDefault": 0,
"productId": "15501",
"defaultAmt": 25,
"rateDefault": 0,
"quantity": 1
},
{
"feeDefault": 0,
"productId": "57462",
"defaultAmt": 0,
"rateDefault": 0,
"quantity": 1
},
{
"feeDefault": 0,
"productId": "55242",
"defaultAmt": 0,
"rateDefault": 0,
"quantity": 1
},
{
"feeDefault": 0,
"productId": "50732",
"defaultAmt": 0,
"rateDefault": 0,
"quantity": 1
}
],
"cartDetails": [
{
"category": "RETAIL",
"term": "P",
"price": 1149,
"qty": 1,
"productType": "Terminal",
"productId": "87862"
},
{
"category": "RETAIL",
"term": "P",
"price": 0,
"qty": 1,
"productType": "ACQUIRING",
"productId": "10041"
}
],
"idology": {
"iq-summary-result": "pass",
"summary-result": {
"message": "PASS",
"key": "id.success"
},
"results": {
"message": "ID Located",
"key": "result.match"
},
"idNumber": 2123412345,
"answers-received": 3,
"idliveq-result": {
"message": "One Incorrect Answer",
"key": "result.questions.1.incorrect"
}
},
"advancedPreferences": {
"form1099Electronically": true,
"statementType": "Detail",
"statementDeliveryType": "Online",
"form1099ToEmail": true
},
"threatMetrixGuid": "60fbfc01-3db9-2112-a954-93c889a752a4"
}
endpoint = "/marketplace/v1/merchantapplication/singleoutletwithcreditdecision/"
r = requests.post(url + endpoint, json=data, headers=headers)
print(r)
ENDPOINT="$URL/marketplace/v1/merchantapplication/singleoutletwithcreditdecision/"
curl -X POST -H "date: $DATE" -H "Authorization: $HMAC_AUTH" -H "Content-Type:application/json" --data '{
"shippingAddress": {
"city": "Schenectady",
"productsToShip": [
{
"term": "P",
"productId": "87862"
}
],
"firstName": "John",
"country": "US",
"address2": "",
"email": "john.smith@emailaddress.com",
"phone": "1234567890",
"state": "NY",
"lastName": "Smith",
"postalCode": "12345",
"address1": "123 Main Street",
"company": "Jonhs Cafe"
},
"merchantInformation": {
"siteSurvey": {
"deliveryTimeFrame_8_To_14": "0",
"deliveryTimeFrame_0_To_7": "100",
"deliveryTimeFrame_Over_30": "0",
"deliveryTimeFrame_15_To_30": "0"
},
"stateOfIncorporation": "NY",
"foreignEntityOption": "N",
"taxId": "666321471",
"contactInformation": [
{
"city": "Schenectady",
"country": "US",
"address2": "",
"contactType": "CORPORATE",
"phone": "1234567890",
"state": "NY",
"address1": "123 Main Street",
"postalCode": "12345",
"email": "john.smith@emailaddress.com"
}
],
"bankInformation": [
{
"ordinal": 2,
"accountNumber": "788723721",
"abaNumber": "122100024",
"bankCity": "COLUMBUS",
"bankState": "OH",
"instName": "JPMORGAN CHASE BANK, NA",
"bankZip": "43240"
}
],
"taxFilingName": "MMISTEST0318201902",
"transactionInfo": {
"averageTicket": 10,
"category": "Restaurant",
"creditCardVolume": 100000,
"annualVolume": 100000,
"amexSENumber": "",
"mcc": "5812",
"methodofPayment": {
"faceToFace": "100",
"phoneOrEmail": "0",
"internet": "0"
},
"mccDescription": "Restaurants, Eating Places",
"highestTicket": 11
},
"legalName": "MMISTEST0318201902",
"dbaName": "MMISTEST0318201902",
"businessStartedOn": "2009-01-01",
"organizationType": "SOLE_PROPRIETORSHIP",
"tinType": "SSN"
},
"ownerInformation": [
{
"percentOwned": 100,
"firstName": "John",
"title": "Owner",
"lastName": "Smith",
"contactInformation": {
"city": "Schenectady",
"country": "US",
"address2": "",
"contactType": "OWNER",
"phone": "1234567890",
"state": "NY",
"address1": "123 Main Street",
"postalCode": "12345",
"email": "john.smith@emailaddress.com"
},
"dateofBirth": "1975-02-28",
"ssn": "666321471"
}
],
"compaign":
{
"orignatingoffer":"468209433250",
"keyWords":"",
"leadType":"Digital",
"offerCode":"khL4pD",
"source":"google",
"medium":"ppc",
"placement":"105411458562",
"compaignName":"Clover_PPC_450offer"
},
"pricingDetails": [
{
"feeDefault": 0,
"purchaseType": "P",
"defaultAmt": 1149,
"quantity": 1,
"rateDefault": 0,
"productId": "87862"
},
{
"feeDefault": 0,
"productId": "54562",
"defaultAmt": 0,
"rateDefault": 0,
"quantity": 1
},
{
"feeDefault": 0,
"productId": "59462",
"defaultAmt": 0,
"rateDefault": 0,
"quantity": 1
},
{
"feeDefault": 0,
"productId": "71762",
"defaultAmt": 19.95,
"rateDefault": 0,
"quantity": 1
},
{
"feeDefault": 0.1,
"productId": "80382",
"defaultAmt": 0,
"rateDefault": 2.7,
"quantity": 1
},
{
"feeDefault": 0.1,
"productId": "80402",
"defaultAmt": 0,
"rateDefault": 3.5,
"quantity": 1
},
{
"feeDefault": 0,
"productId": "49872",
"defaultAmt": 25,
"rateDefault": 0,
"quantity": 1
},
{
"feeDefault": 0,
"productId": "45608",
"defaultAmt": 0,
"rateDefault": 0,
"quantity": 1
},
{
"feeDefault": 0,
"productId": "46164",
"defaultAmt": 0,
"rateDefault": 0,
"quantity": 1
},
{
"feeDefault": 0,
"productId": "46657",
"defaultAmt": 25,
"rateDefault": 0,
"quantity": 1
},
{
"feeDefault": 0,
"productId": "15501",
"defaultAmt": 25,
"rateDefault": 0,
"quantity": 1
},
{
"feeDefault": 0,
"productId": "57462",
"defaultAmt": 0,
"rateDefault": 0,
"quantity": 1
},
{
"feeDefault": 0,
"productId": "55242",
"defaultAmt": 0,
"rateDefault": 0,
"quantity": 1
},
{
"feeDefault": 0,
"productId": "50732",
"defaultAmt": 0,
"rateDefault": 0,
"quantity": 1
}
],
"cartDetails": [
{
"category": "RETAIL",
"term": "P",
"price": 1149,
"qty": 1,
"productType": "Terminal",
"productId": "87862"
},
{
"category": "RETAIL",
"term": "P",
"price": 0,
"qty": 1,
"productType": "ACQUIRING",
"productId": "10041"
}
],
"idology": {
"iq-summary-result": "pass",
"summary-result": {
"message": "PASS",
"key": "id.success"
},
"results": {
"message": "ID Located",
"key": "result.match"
},
"idNumber": 2123412345,
"answers-received": 3,
"idliveq-result": {
"message": "One Incorrect Answer",
"key": "result.questions.1.incorrect"
}
},
"advancedPreferences": {
"form1099Electronically": true,
"statementType": "Detail",
"statementDeliveryType": "Online",
"form1099ToEmail": true
},
"threatMetrixGuid": "60fbfc01-3db9-2112-a954-93c889a752a4"
}' $ENDPOINT
var options = {
method: 'POST',
url: url + '/marketplace/v1/merchantapplication/singleoutletwithcreditdecision/',
headers: getAuthenticationHeaders(),
body: {
"shippingAddress": {
"city": "Schenectady",
"productsToShip": [
{
"term": "P",
"productId": "87862"
}
],
"firstName": "John",
"country": "US",
"address2": "",
"email": "john.smith@emailaddress.com",
"phone": "1234567890",
"state": "NY",
"lastName": "Smith",
"postalCode": "12345",
"address1": "123 Main Street",
"company": "Jonhs Cafe"
},
"merchantInformation": {
"siteSurvey": {
"deliveryTimeFrame_8_To_14": "0",
"deliveryTimeFrame_0_To_7": "100",
"deliveryTimeFrame_Over_30": "0",
"deliveryTimeFrame_15_To_30": "0"
},
"stateOfIncorporation": "NY",
"foreignEntityOption": "N",
"taxId": "666321471",
"contactInformation": [
{
"city": "Schenectady",
"country": "US",
"address2": "",
"contactType": "CORPORATE",
"phone": "1234567890",
"state": "NY",
"address1": "123 Main Street",
"postalCode": "12345",
"email": "john.smith@emailaddress.com"
}
],
"bankInformation": [
{
"ordinal": 2,
"accountNumber": "788723721",
"abaNumber": "122100024",
"bankCity": "COLUMBUS",
"bankState": "OH",
"instName": "JPMORGAN CHASE BANK, NA",
"bankZip": "43240"
}
],
"taxFilingName": "MMISTEST0318201902",
"transactionInfo": {
"averageTicket": 10,
"category": "Restaurant",
"creditCardVolume": 100000,
"annualVolume": 100000,
"amexSENumber": "",
"mcc": "5812",
"methodofPayment": {
"faceToFace": "100",
"phoneOrEmail": "0",
"internet": "0"
},
"mccDescription": "Restaurants, Eating Places",
"highestTicket": 11
},
"legalName": "MMISTEST0318201902",
"dbaName": "MMISTEST0318201902",
"businessStartedOn": "2009-01-01",
"organizationType": "SOLE_PROPRIETORSHIP",
"tinType": "SSN"
},
"ownerInformation": [
{
"percentOwned": 100,
"firstName": "John",
"title": "Owner",
"lastName": "Smith",
"contactInformation": {
"city": "Schenectady",
"country": "US",
"address2": "",
"contactType": "OWNER",
"phone": "1234567890",
"state": "NY",
"address1": "123 Main Street",
"postalCode": "12345",
"email": "john.smith@emailaddress.com"
},
"dateofBirth": "1975-02-28",
"ssn": "666321471"
}
],
"compaign":
{
"orignatingoffer":"468209433250",
"keyWords":"",
"leadType":"Digital",
"offerCode":"khL4pD",
"source":"google",
"medium":"ppc",
"placement":"105411458562",
"compaignName":"Clover_PPC_450offer"
},
"pricingDetails": [
{
"feeDefault": 0,
"purchaseType": "P",
"defaultAmt": 1149,
"quantity": 1,
"rateDefault": 0,
"productId": "87862"
},
{
"feeDefault": 0,
"productId": "54562",
"defaultAmt": 0,
"rateDefault": 0,
"quantity": 1
},
{
"feeDefault": 0,
"productId": "59462",
"defaultAmt": 0,
"rateDefault": 0,
"quantity": 1
},
{
"feeDefault": 0,
"productId": "71762",
"defaultAmt": 19.95,
"rateDefault": 0,
"quantity": 1
},
{
"feeDefault": 0.1,
"productId": "80382",
"defaultAmt": 0,
"rateDefault": 2.7,
"quantity": 1
},
{
"feeDefault": 0.1,
"productId": "80402",
"defaultAmt": 0,
"rateDefault": 3.5,
"quantity": 1
},
{
"feeDefault": 0,
"productId": "49872",
"defaultAmt": 25,
"rateDefault": 0,
"quantity": 1
},
{
"feeDefault": 0,
"productId": "45608",
"defaultAmt": 0,
"rateDefault": 0,
"quantity": 1
},
{
"feeDefault": 0,
"productId": "46164",
"defaultAmt": 0,
"rateDefault": 0,
"quantity": 1
},
{
"feeDefault": 0,
"productId": "46657",
"defaultAmt": 25,
"rateDefault": 0,
"quantity": 1
},
{
"feeDefault": 0,
"productId": "15501",
"defaultAmt": 25,
"rateDefault": 0,
"quantity": 1
},
{
"feeDefault": 0,
"productId": "57462",
"defaultAmt": 0,
"rateDefault": 0,
"quantity": 1
},
{
"feeDefault": 0,
"productId": "55242",
"defaultAmt": 0,
"rateDefault": 0,
"quantity": 1
},
{
"feeDefault": 0,
"productId": "50732",
"defaultAmt": 0,
"rateDefault": 0,
"quantity": 1
}
],
"cartDetails": [
{
"category": "RETAIL",
"term": "P",
"price": 1149,
"qty": 1,
"productType": "Terminal",
"productId": "87862"
},
{
"category": "RETAIL",
"term": "P",
"price": 0,
"qty": 1,
"productType": "ACQUIRING",
"productId": "10041"
}
],
"idology": {
"iq-summary-result": "pass",
"summary-result": {
"message": "PASS",
"key": "id.success"
},
"results": {
"message": "ID Located",
"key": "result.match"
},
"idNumber": 2123412345,
"answers-received": 3,
"idliveq-result": {
"message": "One Incorrect Answer",
"key": "result.questions.1.incorrect"
}
},
"advancedPreferences": {
"form1099Electronically": true,
"statementType": "Detail",
"statementDeliveryType": "Online",
"form1099ToEmail": true
},
"threatMetrixGuid": "60fbfc01-3db9-2112-a954-93c889a752a4"
},
json: true
};
request(options, function (error, response, body) {
if (error) throw new Error(error);
console.log(response);
});
// Don't forget to add your HMAC Authorization Headers
try {
String jsonString = "{\n" +
var json = "{\n" +
"\"shippingAddress\": {\n" +
"\"city\": \"Schenectady\",\n" +
"\"productsToShip\": [\n" +
" {\n" +
" \"term\": \"P\",\n" +
" \"productId\": \"87862\"\n" +
" }\n" +
"],\n" +
"\"firstName\": \"John\",\n" +
"\"country\": \"US\",\n" +
"\"address2\": \"\",\n" +
"\"email\": \"john.smith@emailaddress.com\",\n" +
"\"phone\": \"1234567890\",\n" +
"\"state\": \"NY\",\n" +
"\"lastName\": \"Smith\",\n" +
"\"postalCode\": \"12345\",\n" +
"\"address1\": \"123 Main Street\",\n" +
"\"company\": \"Jonhs Cafe\"\r\n },\r\n \"merchantInformation\": {\n" +
"\"siteSurvey\": {\n" +
" \"deliveryTimeFrame_8_To_14\": \"0\",\n" +
" \"deliveryTimeFrame_0_To_7\": \"100\",\n" +
" \"deliveryTimeFrame_Over_30\": \"0\",\n" +
" \"deliveryTimeFrame_15_To_30\": \"0\"\n" +
"},\n" +
"\"stateOfIncorporation\": \"NY\",\n" +
"\"foreignEntityOption\": \"N\",\n" +
"\"taxId\": \"666321471\",\n" +
"\"contactInformation\": [\n" +
" {\n" +
" \"city\": \"Schenectady\",\n" +
" \"country\": \"US\",\n" +
" \"address2\": \"\",\n" +
" \"contactType\": \"CORPORATE\",\n" +
" \"phone\": \"1234567890\",\n" +
" \"state\": \"NY\",\n" +
" \"address1\": \"123 Main Street\",\n" +
" \"postalCode\": \"12345\",\n" +
" \"email\": \"john.smith@emailaddress.com\"\n" +
" }\n" +
"],\n" +
"\"bankInformation\": [\n" +
" {\n" +
" \"ordinal\": 2,\n" +
" \"accountNumber\": \"788723721\",\n" +
" \"abaNumber\": \"122100024\",\n" +
" \"bankCity\": \"COLUMBUS\",\n" +
" \"bankState\": \"OH\",\n" +
" \"instName\": \"JPMORGAN CHASE BANK, NA\",\n" +
" \"bankZip\": \"43240\"\n" +
" }\n" +
"],\n" +
"\"taxFilingName\": \"MMISTEST0318201902\",\n" +
"\"transactionInfo\": {\n" +
" \"averageTicket\": 10,\n" +
" \"category\": \"Restaurant\",\n" +
" \"creditCardVolume\": 100000,\n" +
" \"annualVolume\": 100000,\n" +
" \"amexSENumber\": \"\",\n" +
" \"mcc\": \"5812\",\n" +
" \"methodofPayment\": {\n" +
" \"faceToFace\": \"100\",\n" +
" \"phoneOrEmail\": \"0\",\n" +
" \"internet\": \"0\"\n" +
" },\n" +
" \"mccDescription\": \"Restaurants, Eating Places\",\n" +
" \"highestTicket\": 11\n" +
"},\n" +
"\"legalName\": \"MMISTEST0318201902\",\n" +
"\"dbaName\": \"MMISTEST0318201902\",\n" +
"\"businessStartedOn\": \"2009-01-01\",\n" +
"\"organizationType\": \"SOLE_PROPRIETORSHIP\",\n" +
"\"tinType\": \"SSN\",\n" +
"\"ownerInformation\": [\n" +
"{\n" +
" \"percentOwned\": 100,\n" +
" \"firstName\": \"John\",\n" +
" \"title\": \"Owner\",\n" +
" \"lastName\": \"Smith\",\n" +
" \"contactInformation\": {\n" +
" \"city\": \"Schenectady\",\n" +
" \"country\": \"US\",\n" +
" \"address2\": \"\",\n" +
" \"contactType\": \"OWNER\",\n" +
" \"phone\": \"1234567890\",\n" +
" \"state\": \"NY\",\n" +
" \"address1\": \"123 Main Street\",\n" +
" \"postalCode\": \"12345\",\n" +
" \"email\": \"john.smith@emailaddress.com\"\n" +
" },\n" +
" \"dateofBirth\": \"1975-02-28\",\n" +
" \"ssn\": \"666321471\"\n" +
"}\r\n ],\r\n \"pricingDetails\": [\n" +
"{\n" +
" \"feeDefault\": 0,\n" +
" \"purchaseType\": \"P\",\n" +
" \"defaultAmt\": 1149,\n" +
" \"quantity\": 1,\n" +
" \"rateDefault\": 0,\n" +
" \"productId\": \"87862\"\n" +
"},\n" +
"{\n" +
" \"feeDefault\": 0,\n" +
" \"productId\": \"54562\",\n" +
" \"defaultAmt\": 0,\n" +
" \"rateDefault\": 0,\n" +
" \"quantity\": 1\n" +
"},\n" +
"{\n" +
" \"feeDefault\": 0,\n" +
" \"productId\": \"59462\",\n" +
" \"defaultAmt\": 0,\n" +
" \"rateDefault\": 0,\n" +
" \"quantity\": 1\n" +
"},\n" +
"{\n" +
" \"feeDefault\": 0,\n" +
" \"productId\": \"71762\",\n" +
" \"defaultAmt\": 19.95,\n" +
" \"rateDefault\": 0,\n" +
" \"quantity\": 1\n" +
"},\n" +
"{\n" +
" \"feeDefault\": 0.1,\n" +
" \"productId\": \"80382\",\n" +
" \"defaultAmt\": 0,\n" +
" \"rateDefault\": 2.7,\n" +
" \"quantity\": 1\n" +
"},\n" +
"{\n" +
" \"feeDefault\": 0.1,\n" +
" \"productId\": \"80402\",\n" +
" \"defaultAmt\": 0,\n" +
" \"rateDefault\": 3.5,\n" +
" \"quantity\": 1\n" +
"},\n" +
"{\n" +
" \"feeDefault\": 0,\n" +
" \"productId\": \"49872\",\n" +
" \"defaultAmt\": 25,\n" +
" \"rateDefault\": 0,\n" +
" \"quantity\": 1\n" +
"},\n" +
"{\n" +
" \"feeDefault\": 0,\n" +
" \"productId\": \"45608\",\n" +
" \"defaultAmt\": 0,\n" +
" \"rateDefault\": 0,\n" +
" \"quantity\": 1\n" +
"},\n" +
"{\n" +
" \"feeDefault\": 0,\n" +
" \"productId\": \"46164\",\n" +
" \"defaultAmt\": 0,\n" +
" \"rateDefault\": 0,\n" +
" \"quantity\": 1\n" +
"},\n" +
"{\n" +
" \"feeDefault\": 0,\n" +
" \"productId\": \"46657\",\n" +
" \"defaultAmt\": 25,\n" +
" \"rateDefault\": 0,\n" +
" \"quantity\": 1\n" +
"},\n" +
"{\n" +
" \"feeDefault\": 0,\n" +
" \"productId\": \"15501\",\n" +
" \"defaultAmt\": 25,\n" +
" \"rateDefault\": 0,\n" +
" \"quantity\": 1\n" +
"},\n" +
"{\n" +
" \"feeDefault\": 0,\n" +
" \"productId\": \"57462\",\n" +
" \"defaultAmt\": 0,\n" +
" \"rateDefault\": 0,\n" +
" \"quantity\": 1\n" +
"},\n" +
"{\n" +
" \"feeDefault\": 0,\n" +
" \"productId\": \"55242\",\n" +
" \"defaultAmt\": 0,\n" +
" \"rateDefault\": 0,\n" +
" \"quantity\": 1\n" +
"},\n" +
"{\n" +
" \"feeDefault\": 0,\n" +
" \"productId\": \"50732\",\n" +
" \"defaultAmt\": 0,\n" +
" \"rateDefault\": 0,\n" +
" \"quantity\": 1\n" +
"}\r\n ],\r\n \"cartDetails\": [\n" +
"{\n" +
" \"category\": \"RETAIL\",\n" +
" \"term\": \"P\",\n" +
" \"price\": 1149,\n" +
" \"qty\": 1,\n" +
" \"productType\": \"Terminal\",\n" +
" \"productId\": \"87862\"\n" +
"},\n" +
"{\n" +
" \"category\": \"RETAIL\",\n" +
" \"term\": \"P\",\n" +
" \"price\": 0,\n" +
" \"qty\": 1,\n" +
" \"productType\": \"ACQUIRING\",\n" +
" \"productId\": \"10041\"\n" +
"}\r\n ],\r\n \"idology\": {\n" +
"\"iq-summary-result\": \"pass\",\n" +
"\"summary-result\": {\n" +
" \"message\": \"PASS\",\n" +
" \"key\": \"id.success\"\n" +
"},\n" +
"\"results\": {\n" +
" \"message\": \"ID Located\",\n" +
" \"key\": \"result.match\"\n" +
"},\n" +
"\"idNumber\": 2123412345,\n" +
"\"answers-received\": 3,\n" +
"\"idliveq-result\": {\n" +
" \"message\": \"One Incorrect Answer\",\n" +
" \"key\": \"result.questions.1.incorrect\"\n" +
"}\r\n },\r\n \"advancedPreferences\": {\n" +
"\"form1099Electronically\": true,\n" +
"\"statementType\": \"Detail\",\n" +
"\"statementDeliveryType\": \"Online\",\n" +
"\"form1099ToEmail\": true\n" +
"},\n" +
"\"threatMetrixGuid\": \"60fbfc01-3db9-2112-a954-93c889a752a4\"\n" +
"{\"campaign\":{\"orignatingoffer\":\"468209433250\",\"keyWords\":\"\",\"leadType\":\"Digital\",\"offerCode\":\"khL4pD\",\"source\":\"google\",\"medium\":\"ppc\",\"placement\":\"105411458562\",\"compaignName\":\"Clover_PPC_450offer\"}}"+
"}";
StringEntity payload = new StringEntity(jsonString);
HttpResponse response = doPost("/marketplace/v1/merchantapplication/singleoutletwithcreditdecision/", payload);
int statusCode = response.getStatusLine().getStatusCode();
String response_string = EntityUtils.toString(response.getEntity());
JSONArray json = new JSONArray(response_string);
System.out.println("json:" + json.toString());
} catch (Exception e) {
e.printStackTrace();
}
<?php
# Don't forget to add your HMAC Authorization Headers
$data = array (
'shippingAddress' =>
array (
'city' => 'Schenectady',
'productsToShip' =>
array (
0 =>
array (
'term' => 'P',
'productId' => '87862',
),
),
'firstName' => 'John',
'country' => 'US',
'address2' => '',
'email' => 'john.smith@emailaddress.com',
'phone' => '1234567890',
'state' => 'NY',
'lastName' => 'Smith',
'postalCode' => '12345',
'address1' => '123 Main Street',
'company' => 'Jonhs Cafe',
),
'merchantInformation' =>
array (
'siteSurvey' =>
array (
'deliveryTimeFrame_8_To_14' => '0',
'deliveryTimeFrame_0_To_7' => '100',
'deliveryTimeFrame_Over_30' => '0',
'deliveryTimeFrame_15_To_30' => '0',
),
'stateOfIncorporation' => 'NY',
'foreignEntityOption' => 'N',
'taxId' => '666321471',
'contactInformation' =>
array (
0 =>
array (
'city' => 'Schenectady',
'country' => 'US',
'address2' => '',
'contactType' => 'CORPORATE',
'phone' => '1234567890',
'state' => 'NY',
'address1' => '123 Main Street',
'postalCode' => '12345',
'email' => 'john.smith@emailaddress.com',
),
),
'bankInformation' =>
array (
0 =>
array (
'ordinal' => 2,
'accountNumber' => '788723721',
'abaNumber' => '122100024',
'bankCity' => 'COLUMBUS',
'bankState' => 'OH',
'instName' => 'JPMORGAN CHASE BANK, NA',
'bankZip' => '43240',
),
),
'taxFilingName' => 'MMISTEST0318201902',
'transactionInfo' =>
array (
'averageTicket' => 10,
'category' => 'Restaurant',
'creditCardVolume' => 100000,
'annualVolume' => 100000,
'amexSENumber' => '',
'mcc' => '5812',
'methodofPayment' =>
array (
'faceToFace' => '100',
'phoneOrEmail' => '0',
'internet' => '0',
),
'mccDescription' => 'Restaurants, Eating Places',
'highestTicket' => 11,
),
'legalName' => 'MMISTEST0318201902',
'dbaName' => 'MMISTEST0318201902',
'businessStartedOn' => '2009-01-01',
'organizationType' => 'SOLE_PROPRIETORSHIP',
'tinType' => 'SSN',
),
'ownerInformation' =>
array (
0 =>
array (
'percentOwned' => 100,
'firstName' => 'John',
'title' => 'Owner',
'lastName' => 'Smith',
'contactInformation' =>
array (
'city' => 'Schenectady',
'country' => 'US',
'address2' => '',
'contactType' => 'OWNER',
'phone' => '1234567890',
'state' => 'NY',
'address1' => '123 Main Street',
'postalCode' => '12345',
'email' => 'john.smith@emailaddress.com',
),
'dateofBirth' => '1975-02-28',
'ssn' => '666321471',
),
),
'campaign' =>
array (
'orignatingoffer' => '468209433250',
'keyWords' => '',
'leadType' => 'Digital',
'offerCode' => 'khL4pD',
'source' => 'google',
'medium' => 'ppc',
'placement' => '105411458562',
'compaignName' => 'Clover_PPC_450offer',
),
'pricingDetails' =>
array (
0 =>
array (
'feeDefault' => 0,
'purchaseType' => 'P',
'defaultAmt' => 1149,
'quantity' => 1,
'rateDefault' => 0,
'productId' => '87862',
),
1 =>
array (
'feeDefault' => 0,
'productId' => '54562',
'defaultAmt' => 0,
'rateDefault' => 0,
'quantity' => 1,
),
2 =>
array (
'feeDefault' => 0,
'productId' => '59462',
'defaultAmt' => 0,
'rateDefault' => 0,
'quantity' => 1,
),
3 =>
array (
'feeDefault' => 0,
'productId' => '71762',
'defaultAmt' => 19.949999999999999,
'rateDefault' => 0,
'quantity' => 1,
),
4 =>
array (
'feeDefault' => 0.10000000000000001,
'productId' => '80382',
'defaultAmt' => 0,
'rateDefault' => 2.7000000000000002,
'quantity' => 1,
),
5 =>
array (
'feeDefault' => 0.10000000000000001,
'productId' => '80402',
'defaultAmt' => 0,
'rateDefault' => 3.5,
'quantity' => 1,
),
6 =>
array (
'feeDefault' => 0,
'productId' => '49872',
'defaultAmt' => 25,
'rateDefault' => 0,
'quantity' => 1,
),
7 =>
array (
'feeDefault' => 0,
'productId' => '45608',
'defaultAmt' => 0,
'rateDefault' => 0,
'quantity' => 1,
),
8 =>
array (
'feeDefault' => 0,
'productId' => '46164',
'defaultAmt' => 0,
'rateDefault' => 0,
'quantity' => 1,
),
9 =>
array (
'feeDefault' => 0,
'productId' => '46657',
'defaultAmt' => 25,
'rateDefault' => 0,
'quantity' => 1,
),
10 =>
array (
'feeDefault' => 0,
'productId' => '15501',
'defaultAmt' => 25,
'rateDefault' => 0,
'quantity' => 1,
),
11 =>
array (
'feeDefault' => 0,
'productId' => '57462',
'defaultAmt' => 0,
'rateDefault' => 0,
'quantity' => 1,
),
12 =>
array (
'feeDefault' => 0,
'productId' => '55242',
'defaultAmt' => 0,
'rateDefault' => 0,
'quantity' => 1,
),
13 =>
array (
'feeDefault' => 0,
'productId' => '50732',
'defaultAmt' => 0,
'rateDefault' => 0,
'quantity' => 1,
),
),
'cartDetails' =>
array (
0 =>
array (
'category' => 'RETAIL',
'term' => 'P',
'price' => 1149,
'qty' => 1,
'productType' => 'Terminal',
'productId' => '87862',
),
1 =>
array (
'category' => 'RETAIL',
'term' => 'P',
'price' => 0,
'qty' => 1,
'productType' => 'ACQUIRING',
'productId' => '10041',
),
),
'idology' =>
array (
'iq-summary-result' => 'pass',
'summary-result' =>
array (
'message' => 'PASS',
'key' => 'id.success',
),
'results' =>
array (
'message' => 'ID Located',
'key' => 'result.match',
),
'idNumber' => 2123412345,
'answers-received' => 3,
'idliveq-result' =>
array (
'message' => 'One Incorrect Answer',
'key' => 'result.questions.1.incorrect',
),
),
'advancedPreferences' =>
array (
'form1099Electronically' => true,
'statementType' => 'Detail',
'statementDeliveryType' => 'Online',
'form1099ToEmail' => true,
),
'threatMetrixGuid' => '60fbfc01-3db9-2112-a954-93c889a752a4',
)
$data_json = json_encode($data);
$headers = array(
'date: ' . $date,
'Authorization: ' . $hmacAuth,
'Content-Type: application/json',
'Content-Length: ' . strlen($data_json)
);
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url . "/marketplace/v1/merchantapplication/singleoutletwithcreditdecision/");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data_json);
$res = curl_exec($ch);
echo($res);
?>
The above command returns JSON structured like this:
{
"orderId": "1GKbO"
}
The API allows the developer to submit merchant application & credit decision. This is an enhanced API to combine 2 APIs credit decision and single outlet.
For best results, Threatmatrix and Identity verification should be performed.
Request
POST /marketplace/v1/merchantapplication/singleoutletwithcreditdecision/
The endpoint takes a JSON object as input, which contains following information.
| Parameter | Required | Data Type | Short Description |
|---|---|---|---|
| merchantInformation | ✔ | object | Object containing the information about the business. |
| dbaName | ✔ | string | DBA name. |
| legalName | ✔ | string | Legal business name. |
| taxId | ✔ | string | A Taxpayer Identification Number (TIN) is an identification number used by the Internal Revenue Service (IRS). Can be validated against taxFilingName using the POST TIN/Validate service. |
| businessStartedOn | ✔ | string | Business started date in “YYYY-MM-DD” format. |
| organizationType | ✔ | string | Organization type represented by an abbreviated code. See possible values here. |
| stateOfIncorporation | ✔ | string | State of incorporation in abbreviated format. i.e. for California send "CA". |
| taxFilingName | ✔ | string | IRS tax filing name for the business. Can be validated against taxId using the POST TIN/Validate service. |
| foreignEntityOption | ✔ | string | Indicates if the business can claim foreign status according to IRS regulations. Possible values: "N" (None) or "A" (A foreign person/A business that can claim foreign entity status). |
| tinType | ✔ | integer | Type of Taxpayer Identification Number (TIN). Possible values: "EIN" or "SSN". |
| contactInformation | ✔ | array | Array of (minimum one) object(s), each of which represents a business location. contactType, address1, address2, address3, city, state, postalCode, country, phone, and email. |
| contactType | ✔ | string | Type of location. Possible values: "LOCATION", "CORPORATE", "OWNER". |
| address1 | ✔ | string | Street address. |
| address2 | string | Second line of street address, if applicable. i.e. Unit, Floor, Suite, etc. | |
| address3 | string | Third line of street address. | |
| city | ✔ | string | City. |
| state | ✔ | string | State in abbreviated format. i.e. for California send "CA". |
| country | ✔ | string | ISO Standard Country Code of the country. |
| postalCode | ✔ | string | ZIP/postal code. |
| phone | string | Phone number. | |
| transactionInfo | ✔ | object | Transactions information used to determine pricing. |
| mccDescription | string | “Merchant Category Code” MCC description (refer to: GET MCC/Category). | |
| mcc | ✔ | string | MCC Code (refer to: GET MCC/Category). |
| annualVolume | ✔ | double | Annual transaction volume in USD. |
| creditCardVolume | ✔ | double | Annual bank card transaction volume in USD. |
| highestTicket | ✔ | double | Highest ticket price in USD. |
| averageTicket | ✔ | double | Average ticket price in USD. |
| category | ✔ | string | Category eg: "RETAIL/MOTO" (refer to: GET Categories). |
| amexSENumber | long | In case Amex Volume greater than or equal to US$ 1 million, provide the Service Establishment Number. | |
| methodofPayment | object | Object containing information about how the business operates and accepts transactions. Sum of values of the three contained fields must equal 100. | |
| faceToFace | integer | Percentage of payments/transactions made face to face (can’t exceed 100%). | |
| phoneOrEmail | integer | Percentage of payments/transactions made by phone or email (can’t exceed 100%). | |
| internet | integer | Percentage of payments/transactions made on the internet (can’t exceed 100%). | |
| siteSurvey | ✔ | object | A visit in an official capacity to examine a site to determine its suitability for some enterprise. |
| siteVisitation | string | "Y" or "N". Indicates whether site visitation was performed or not. | |
| deliveryTimeFrame_0_To_7 | ✔ | string | Percentage of services delivered between 0-7 days after transaction. |
| deliveryTimeFrame_8_To_14 | ✔ | string | Percentage of services delivered between 8-14 days after transaction. |
| deliveryTimeFrame_15_To_30 | ✔ | string | Percentage of services delivered between 15-30 days after transaction. |
| deliveryTimeFrame_Over_30 | ✔ | string | Percentage of services delivered more than 30 days after transaction. |
| bankInformation | ✔ | array | Array of (minimum one) object(s) that collects the ACH information. |
| instName | ✔ | string | Financial institution name such as "JPMORGAN CHASE BANK", etc. |
| abaNumber | ✔ | string | ABA routing transit number. A nine digit code to identify a financial institution. Needs to be validated using the POST Banks/Validate service. |
| accountNumber | ✔ | string | Checking account number. Usually 10-12 digit number to identify the merchant’s account. |
| ordinal | ✔ | integer | Default to 2. |
| bankState | ✔ | string | Financial institution location state. |
| bankCity | ✔ | string | Financial institution location city. |
| bankZip | ✔ | integer | Financial institution ZIP code. |
| campaign | ✔ | Object | Object of Campaign details. |
| campaignName | ✔ | string | campaign name(Max 150 char) |
| source | ✔ | string | source(Max 50 char) |
| medium | ✔ | string | medium(Max 60 char) |
| originatingOffer | ✔ | string | originating Offer(Max 150 char) |
| placement | ✔ | string | placement(Max 60 char) |
| leadType | ✔ | string | leadType. |
| keywords | ✔ | string | keywords(Max 50 char)“ |
| offerCode | ✔ | string | offer code(MAx 225 char)” |
| ownerInformation | ✔ | array | Array of (minimum one) objects, each containing the information of the owner(s) of the business. |
| firstName | ✔ | string | Owner’s first name. |
| lastName | ✔ | string | Owner’s last name. |
| ssn | ✔ | string | Owner’s Social Security Number. |
| dateofBirth | ✔ | string | Owner’s date of birth in “YYYY-MM-DD” format. |
| title | ✔ | string | Title of the listed contact within the organization. See Merchant organizationType and title combinations for detail. |
| percentOwned | ✔ | integer | Percentage of the company owned by this owner. All owners must equal 100%. |
| contactInformation | ✔ | array | Array of (minimum one) object(s), each of which represents the contact information of the owner. Each can contain contactType, address1, address2, address3, city, state, postalCode, country, phone, and email. |
| contactType | ✔ | string | Type of location. Possible values: "OWNER", "PRINCIPAL", "LANDLORD", "BENEFICIARY". |
| address1 | ✔ | string | Street address. |
| address2 | string | Second line of street address, if applicable. i.e. Unit, Floor, Suite, etc. | |
| address3 | string | Third line of street address. | |
| city | ✔ | string | City. |
| state | ✔ | string | State in abbreviated format. i.e. for California send "CA". |
| country | ✔ | string | ISO Standard Country Code of the country. |
| postalCode | ✔ | string | ZIP/postal code. |
| phone | ✔ | string | Phone number. |
| ✔ | string | Email address. | |
| cartDetails | ✔ | array | Array of objects, each containing the details of unique products (by productId) in the Order. |
| category | ✔ | string | Category eg: "RETAIL/MOTO" (refer to: GET Categories). |
| productId | ✔ | string | productId as string. Numeric value that uniquely identifies each product (canonical identifier). |
| productType | ✔ | string | Indicates the behavior of the product, or when the merchant is charged a fee in case of “Processing/Pricing” products. See list of possible values here. |
| price | ✔ | double | Unit price for a product. |
| term | ✔ | string | purchaseType eg: Purchase, Rent, Lease etc. See list of possible values here. |
| qty | ✔ | integer | Quantity selected. |
| pricingDetails | ✔ | array | Array of object each containing the detailed pricing information of a product (hardware, software, acquiring, fees, etc.) in the order. |
| productId | ✔ | integer | Numeric value that uniquely identifies a product (canonical identifier). |
| quantity | ✔ | integer | Quantity of the Pricing Product to be added to the Order. (Generally 1.) |
| defaultAmt | ✔ | integer | Price/amount to be collected (usually as a one-time payment) in USD. |
| feeDefault | ✔ | double | Fee charged per occurrence in USD. |
| rateDefault | ✔ | double | Percentage of transaction amount charged per occurrence. |
| rateDefault | string | Purchase type. | |
| shippingAddress | ✔ | object | Object containing shipping information. |
| company | string | Company name. | |
| firstName | ✔ | string | First name. |
| lastName | ✔ | string | Last name. |
| address1 | ✔ | string | Street address. |
| address2 | string | Second line of street address, if applicable. i.e. Unit, Floor, Suite, etc. | |
| city | ✔ | string | City. |
| state | ✔ | string | State in abbreviated format. i.e. for California send "CA". |
| country | ✔ | string | ISO Standard Country Code of the country. |
| postalCode | ✔ | string | ZIP/postal code. |
| phone | string | Phone number. | |
| ✔ | string | Email address. | |
| productstoShip | ✔ | array | Array of objects, each representing a product which will be shipped to the merchant. Each object contains productId and term. |
| productId | ✔ | long | Numeric value that uniquely identifies a product (canonical identifier). |
| term | ✔ | string | purchaseType eg: Purchase, Rent, Lease etc. See list of possible values here. |
| advancedPreferences | ✔ | object | |
| statementDeliveryType | ✔ | string | Way in which the merchant wants to receive statements. *Possible value(s): "EMAIL", "ONLINE". |
| statementType | ✔ | string | Type of statement. *Possible values: "DETAIL", "SUMMARY". |
| statementEmailAddress | string | Email address for statement delivery. | |
| form1099Electronically | ✔ | boolean | Does the merchant want to receive Form 1099 electronically? |
| form1099ToEmail | ✔ | boolean | Does the merchant want to receive Form 1099 in email? |
| threatMetrixGuid | string | The GUID to be used to invoke the ThreatMetrix webservice call. | |
| idology | object | Object containing the identity verification results. Contains idNumber, answers-received, idequiv-result, iq-summary-result, summary-result and results. | |
| iq-summary-result | string | The result of identity verification. | |
| idNumber | integer | Unique identification for the Identity Verification for this record. | |
| answers-received | integer | Number of answers received. Note: You must send 3 answers in order to get a successful response. | |
| idequiv-result | object | Wrapper object containing result of the overall submission. Contains key and message. | |
| ↳ message | string | Display message for idequiv-result. | |
| ↳ key | string | Message identifier for idequiv-result. | |
| summary-result | object | Wrapper object containing result of the record lookup. This provides information on the success or failure to locate the record to verify. Contains key and message. | |
| ↳ message | string | Display message for summary message: "PASS" or "FAIL". | |
| ↳ key | string | Message identifier for summary-results. | |
| results | object | Wrapper object containing result of the record lookup. This provides information on the success or failure to locate the record to verify. Contains key and message. | |
| ↳ message | string | Display message for results. | |
| ↳ key | string | Message identifier for results. |
Response
The endpoint returns an object containing information about the credit decision.
| Parameter | Data Type | Description |
|---|---|---|
| orderId | string | Order Id. The numeric identifier to be used in the merchant boarding process as input to reference the order. |
POST Merchantapplication/Creditdecision
data = {
"transactionInfo": {
"mccTypes": "Clothing and Shoes",
"mcc": "5611",
"annualVolume": 100000,
"averageTicket": 80,
"highestTicket": 400,
"category": "RETAIL"
},
"ownerInformation": [
{
"lastName": "Smith",
"firstName": "John",
"dateOfBirth": 225936000000,
"title": "Owner",
"percentOwned": 100,
"contactInformation": {
"contactType": "OWNER",
"address1": "17 S St",
"city": "Omaha",
"state": "NE",
"zip": "68135",
"country": "US",
"phone": "8899999991",
"email": "john.smith@email.com"
}
}
],
"merchantInformation": [
{
"category": "RESTAURANT",
"dbaName": "Sample Business Name",
"legalName": "Sample Business Name",
"yearsInBusiness": 1314835200000,
"organizationType": "Sole Proprietorship",
"stateOfIncorporation": "KS",
"taxFilingName": "Sample Business Tax Filing Name",
"foreignEntityOption": "N",
"tinRequestedGuid": "",
"tinType": 1,
"contactInformation": [
{
"contactType": "SHIP_TO",
"state": "NE",
"postalCode": "68135",
"address1": "18 S St",
"email": "john.smith@email.com",
"phone": "1231231234",
"city": "Omaha"
},
{
"contactType": "CORPORATE",
"state": "NE",
"postalCode": "68135",
"address1": "18 S St",
"email": "john.smith@email.com",
"phone": "1231231234",
"city": "Omaha",
"country": "US"
},
{
"contactType": "LOCATION",
"state": "NE",
"postalCode": "68135",
"address1": "18 S St",
"city": "Omaha",
"country": "USA"
}
],
"emvEnabled": false,
"debitEnabled": false,
"amexEnabled": false,
"discoverEnabled": false
}
],
"locationInformation": [
{
"merchantId": 31702,
"dbaName": "Sample Business Name",
"mccDescription": "Restaurant Beverage and Food",
"mcc": "5812",
"annualVolume": 425000,
"averageTicket": 25,
"highestTicket": 45,
"category": "RESTAURANT",
"faceToFace": "100",
"phoneOrEmail": "0",
"internet": "0",
"address1": "18 S St",
"city": "Omaha",
"zip": "68135",
"state": "NE",
"bankInformation": [
{
"abaNumber": "",
"accountNumber": "",
"instName": "JPMORGAN CHASE BANK, NA",
"chargebacks": 1,
"chargebackReversals": 1,
"discountServices": 1
}
],
"siteSurvey": {
"createdDate": "2017-08-03T22:40:39Z",
"siteVisitation": "Not Required",
"returnPolicy": "Exchange Only",
"separateRefundPolicy": "No",
"deliveryTimeFrame_0_To_7": "100",
"deliveryTimeFrame_8_To_14": "0",
"deliveryTimeFrame_15_To_30": "0",
"deliveryTimeFrame_Over_30": "0"
},
"rollupIndicator": "2",
"isPrimaryLocation": true
}
]
}
endpoint = "/marketplace/v1/merchantapplication/creditdecision"
r = requests.post(url + endpoint, json=data, headers=headers)
print(r)
ENDPOINT="$URL/marketplace/v1/merchantapplication/creditdecision"
curl -X POST -H "date: $DATE" -H "Authorization: $HMAC_AUTH" -H "Content-Type:application/json" --data '{
"transactionInfo": {
"mccTypes": "Clothing and Shoes",
"mcc": "5611",
"annualVolume": 100000,
"averageTicket": 80,
"highestTicket": 400,
"category": "RETAIL"
},
"ownerInformation": [
{
"lastName": "Smith",
"firstName": "John",
"dateOfBirth": 225936000000,
"title": "Owner",
"percentOwned": 100,
"contactInformation": {
"contactType": "OWNER",
"address1": "17 S St",
"city": "Omaha",
"state": "NE",
"zip": "68135",
"country": "US",
"phone": "8899999991",
"email": "john.smith@email.com"
}
}
],
"merchantInformation": [
{
"category": "RESTAURANT",
"dbaName": "Sample Business Name",
"legalName": "Sample Business Name",
"yearsInBusiness": 1314835200000,
"organizationType": "Sole Proprietorship",
"stateOfIncorporation": "KS",
"taxFilingName": "Sample Business Tax Filing Name",
"foreignEntityOption": "N",
"tinRequestedGuid": "",
"tinType": 1,
"contactInformation": [
{
"contactType": "SHIP_TO",
"state": "NE",
"postalCode": "68135",
"address1": "18 S St",
"email": "john.smith@email.com",
"phone": "1231231234",
"city": "Omaha"
},
{
"contactType": "CORPORATE",
"state": "NE",
"postalCode": "68135",
"address1": "18 S St",
"email": "john.smith@email.com",
"phone": "1231231234",
"city": "Omaha",
"country": "US"
},
{
"contactType": "LOCATION",
"state": "NE",
"postalCode": "68135",
"address1": "18 S St",
"city": "Omaha",
"country": "USA"
}
],
"emvEnabled": false,
"debitEnabled": false,
"amexEnabled": false,
"discoverEnabled": false
}
],
"locationInformation": [
{
"merchantId": 31702,
"dbaName": "Sample Business Name",
"mccDescription": "Restaurant Beverage and Food",
"mcc": "5812",
"annualVolume": 425000,
"averageTicket": 25,
"highestTicket": 45,
"category": "RESTAURANT",
"faceToFace": "100",
"phoneOrEmail": "0",
"internet": "0",
"address1": "18 S St",
"city": "Omaha",
"zip": "68135",
"state": "NE",
"bankInformation": [
{
"abaNumber": "",
"accountNumber": "",
"instName": "JPMORGAN CHASE BANK, NA",
"chargebacks": 1,
"chargebackReversals": 1,
"discountServices": 1
}
],
"siteSurvey": {
"createdDate": "2017-08-03T22:40:39Z",
"siteVisitation": "Not Required",
"returnPolicy": "Exchange Only",
"separateRefundPolicy": "No",
"deliveryTimeFrame_0_To_7": "100",
"deliveryTimeFrame_8_To_14": "0",
"deliveryTimeFrame_15_To_30": "0",
"deliveryTimeFrame_Over_30": "0"
},
"rollupIndicator": "2",
"isPrimaryLocation": true
}
]
}' $ENDPOINT
var options = {
method: 'POST',
url: url + '/marketplace/v1/merchantapplication/creditdecision',
headers: getAuthenticationHeaders(),
body: {
"transactionInfo": {
"mccTypes": "Clothing and Shoes",
"mcc": "5611",
"annualVolume": 100000,
"averageTicket": 80,
"highestTicket": 400,
"category": "RETAIL"
},
"ownerInformation": [
{
"lastName": "Smith",
"firstName": "John",
"dateOfBirth": 225936000000,
"title": "Owner",
"percentOwned": 100,
"contactInformation": {
"contactType": "OWNER",
"address1": "17 S St",
"city": "Omaha",
"state": "NE",
"zip": "68135",
"country": "US",
"phone": "8899999991",
"email": "john.smith@email.com"
}
}
],
"merchantInformation": [
{
"category": "RESTAURANT",
"dbaName": "Sample Business Name",
"legalName": "Sample Business Name",
"yearsInBusiness": 1314835200000,
"organizationType": "Sole Proprietorship",
"stateOfIncorporation": "KS",
"taxFilingName": "Sample Business Tax Filing Name",
"foreignEntityOption": "N",
"tinRequestedGuid": "",
"tinType": 1,
"contactInformation": [
{
"contactType": "SHIP_TO",
"state": "NE",
"postalCode": "68135",
"address1": "18 S St",
"email": "john.smith@email.com",
"phone": "1231231234",
"city": "Omaha"
},
{
"contactType": "CORPORATE",
"state": "NE",
"postalCode": "68135",
"address1": "18 S St",
"email": "john.smith@email.com",
"phone": "1231231234",
"city": "Omaha",
"country": "US"
},
{
"contactType": "LOCATION",
"state": "NE",
"postalCode": "68135",
"address1": "18 S St",
"city": "Omaha",
"country": "USA"
}
],
"emvEnabled": false,
"debitEnabled": false,
"amexEnabled": false,
"discoverEnabled": false
}
],
"locationInformation": [
{
"merchantId": 31702,
"dbaName": "Sample Business Name",
"mccDescription": "Restaurant Beverage and Food",
"mcc": "5812",
"annualVolume": 425000,
"averageTicket": 25,
"highestTicket": 45,
"category": "RESTAURANT",
"faceToFace": "100",
"phoneOrEmail": "0",
"internet": "0",
"address1": "18 S St",
"city": "Omaha",
"zip": "68135",
"state": "NE",
"bankInformation": [
{
"abaNumber": "",
"accountNumber": "",
"instName": "JPMORGAN CHASE BANK, NA",
"chargebacks": 1,
"chargebackReversals": 1,
"discountServices": 1
}
],
"siteSurvey": {
"createdDate": "2017-08-03T22:40:39Z",
"siteVisitation": "Not Required",
"returnPolicy": "Exchange Only",
"separateRefundPolicy": "No",
"deliveryTimeFrame_0_To_7": "100",
"deliveryTimeFrame_8_To_14": "0",
"deliveryTimeFrame_15_To_30": "0",
"deliveryTimeFrame_Over_30": "0"
},
"rollupIndicator": "2",
"isPrimaryLocation": true
}
],
}
json: true
};
request(options, function (error, response, body) {
if (error) throw new Error(error);
console.log(response);
});
// Don't forget to add your HMAC Authorization Headers
try {
String jsonString = "{\n" +
var json = "{\n" +
" \"transactionInfo\": {\n" +
" \"mccTypes\": \"Clothing and Shoes\",\n" +
" \"mcc\": \"5611\",\n" +
" \"annualVolume\": 100000,\n" +
" \"averageTicket\": 80,\n" +
" \"highestTicket\": 400,\n" +
" \"category\": \"RETAIL\"\n" +
" },\n" +
" \"ownerInformation\": [\n" +
" {\n" +
" \"lastName\": \"Smith\",\n" +
" \"firstName\": \"John\",\n" +
" \"dateOfBirth\": 225936000000,\n" +
" \"title\": \"Owner\",\n" +
" \"percentOwned\": 100,\n" +
" \"contactInformation\": [\n" +
" {\n" +
" \"contactType\": \"OWNER\",\n" +
" \"address1\": \"17 S St\",\n" +
" \"city\": \"Omaha\",\n" +
" \"state\": \"NE\",\n" +
" \"zip\": \"68135\",\n" +
" \"country\": \"US\",\n" +
" \"phone\": \"8899999991\",\n" +
" \"email\": \"john.smith@email.com\"\n" +
" }\n" +
" }\n" +
" ],\n" +
" \"merchantInformation\": [\n" +
" {\n" +
" \"category\": \"RESTAURANT\",\n" +
" \"dbaName\": \"Sample Business Name\",\n" +
" \"legalName\": \"Sample Business Name\",\n" +
" \"yearsInBusiness\": 1314835200000,\n" +
" \"organizationType\": \"Sole Proprietorship\",\n" +
" \"stateOfIncorporation\": \"KS\",\n" +
" \"taxFilingName\": \"Sample Business Tax Filing Name\",\n" +
" \"foreignEntityOption\": \"N\",\n" +
" \"tinRequestedGuid\": \"\",\n" +
" \"tinType\": 1,\n" +
" \"contactInformation\": [\n" +
" {\n" +
" \"contactType\": \"SHIP_TO\",\n" +
" \"state\": \"NE\",\n" +
" \"postalCode\": \"68135\",\n" +
" \"address1\": \"18 S St\",\n" +
" \"email\": \"john.smith@email.com\",\n" +
" \"phone\": \"1231231234\",\n" +
" \"city\": \"Omaha\"\n" +
" },\n" +
" {\n" +
" \"contactType\": \"CORPORATE\",\n" +
" \"state\": \"NE\",\n" +
" \"postalCode\": \"68135\",\n" +
" \"address1\": \"18 S St\",\n" +
" \"email\": \"john.smith@email.com\",\n" +
" \"phone\": \"1231231234\",\n" +
" \"city\": \"Omaha\",\n" +
" \"country\": \"US\"\n" +
" },\n" +
" {\n" +
" \"contactType\": \"LOCATION\",\n" +
" \"state\": \"NE\",\n" +
" \"postalCode\": \"68135\",\n" +
" \"address1\": \"18 S St\",\n" +
" \"city\": \"Omaha\",\n" +
" \"country\": \"USA\"\n" +
" }\n" +
" ],\n" +
" \"emvEnabled\": false,\n" +
" \"debitEnabled\": false,\n" +
" \"amexEnabled\": false,\n" +
" \"discoverEnabled\": false\n" +
" }\n" +
" ],\n" +
" \"locationInformation\": [\n" +
" {\n" +
" \"merchantId\": 31702,\n" +
" \"dbaName\": \"Sample Business Name\",\n" +
" \"mccDescription\": \"Restaurant Beverage and Food\",\n" +
" \"mcc\": \"5812\",\n" +
" \"annualVolume\": 425000,\n" +
" \"averageTicket\": 25,\n" +
" \"highestTicket\": 45,\n" +
" \"category\": \"RESTAURANT\",\n" +
" \"faceToFace\": \"100\",\n" +
" \"phoneOrEmail\": \"0\",\n" +
" \"internet\": \"0\",\n" +
" \"address1\": \"18 S St\",\n" +
" \"city\": \"Omaha\",\n" +
" \"zip\": \"68135\",\n" +
" \"state\": \"NE\",\n" +
" \"bankInformation\": [\n" +
" {\n" +
" \"abaNumber\": \"\",\n" +
" \"accountNumber\": \"\",\n" +
" \"instName\": \"JPMORGAN CHASE BANK, NA\",\n" +
" \"chargebacks\": 1,\n" +
" \"chargebackReversals\": 1,\n" +
" \"discountServices\": 1\n" +
" }\n" +
" ],\n" +
" \"siteSurvey\": {\n" +
" \"createdDate\": \"2017-08-03T22:40:39Z\",\n" +
" \"siteVisitation\": \"Not Required\",\n" +
" \"returnPolicy\": \"Exchange Only\",\n" +
" \"separateRefundPolicy\": \"No\",\n" +
" \"deliveryTimeFrame_0_To_7\": \"100\",\n" +
" \"deliveryTimeFrame_8_To_14\": \"0\",\n" +
" \"deliveryTimeFrame_15_To_30\": \"0\",\n" +
" \"deliveryTimeFrame_Over_30\": \"0\"\n" +
" },\n" +
" \"rollupIndicator\": \"2\",\n" +
" \"isPrimaryLocation\": true\n" +
" }\n" +
" ]\n" +
"}";
StringEntity payload = new StringEntity(jsonString);
HttpResponse response = doPost("/marketplace/v1/merchantapplication/creditdecision", payload);
int statusCode = response.getStatusLine().getStatusCode();
String response_string = EntityUtils.toString(response.getEntity());
JSONArray json = new JSONArray(response_string);
System.out.println("json:" + json.toString());
} catch (Exception e) {
e.printStackTrace();
}
<?php
# Don't forget to add your HMAC Authorization Headers
$data = array (
'transactionInfo' =>
array (
'mccTypes' => 'Clothing and Shoes',
'mcc' => '5611',
'annualVolume' => 100000,
'averageTicket' => 80,
'highestTicket' => 400,
'category' => 'RETAIL',
),
'ownerInformation' =>
array (
0 =>
array (
'lastName' => 'Smith',
'firstName' => 'John',
'dateOfBirth' => 225936000000,
'title' => 'Owner',
'percentOwned' => 100,
'contactInformation' =>
array (
0 =>
array (
'contactType' => 'OWNER',
'address1' => '17 S St',
'city' => 'Omaha',
'state' => 'NE',
'zip' => '68135',
'country' => 'US',
'phone' => '8899999991',
'email' => 'john.smith@email.com',
),
),
),
),
'merchantInformation' =>
array (
0 =>
array (
'category' => 'RESTAURANT',
'dbaName' => 'Sample Business Name',
'legalName' => 'Sample Business Name',
'yearsInBusiness' => 1314835200000,
'organizationType' => 'Sole Proprietorship',
'stateOfIncorporation' => 'KS',
'taxFilingName' => 'Sample Business Tax Filing Name',
'foreignEntityOption' => 'N',
'tinRequestedGuid' => '',
'tinType' => 1,
'contactInformation' =>
array (
0 =>
array (
'contactType' => 'SHIP_TO',
'state' => 'NE',
'postalCode' => '68135',
'address1' => '18 S St',
'email' => 'john.smith@email.com',
'phone' => '1231231234',
'city' => 'Omaha',
),
1 =>
array (
'contactType' => 'CORPORATE',
'state' => 'NE',
'postalCode' => '68135',
'address1' => '18 S St',
'email' => 'john.smith@email.com',
'phone' => '1231231234',
'city' => 'Omaha',
'country' => 'US',
),
2 =>
array (
'contactType' => 'LOCATION',
'state' => 'NE',
'postalCode' => '68135',
'address1' => '18 S St',
'city' => 'Omaha',
'country' => 'USA',
),
),
'emvEnabled' => false,
'debitEnabled' => false,
'amexEnabled' => false,
'discoverEnabled' => false,
),
),
'locationInformation' =>
array (
0 =>
array (
'merchantId' => 31702,
'dbaName' => 'Sample Business Name',
'mccDescription' => 'Restaurant Beverage and Food',
'mcc' => '5812',
'annualVolume' => 425000,
'averageTicket' => 25,
'highestTicket' => 45,
'category' => 'RESTAURANT',
'faceToFace' => '100',
'phoneOrEmail' => '0',
'internet' => '0',
'address1' => '18 S St',
'city' => 'Omaha',
'zip' => '68135',
'state' => 'NE',
'bankInformation' =>
array (
0 =>
array (
'abaNumber' => '',
'accountNumber' => '',
'instName' => 'JPMORGAN CHASE BANK, NA',
'chargebacks' => 1,
'chargebackReversals' => 1,
'discountServices' => 1,
),
),
'siteSurvey' =>
array (
'createdDate' => '2017-08-03T22:40:39Z',
'siteVisitation' => 'Not Required',
'returnPolicy' => 'Exchange Only',
'separateRefundPolicy' => 'No',
'deliveryTimeFrame_0_To_7' => '100',
'deliveryTimeFrame_8_To_14' => '0',
'deliveryTimeFrame_15_To_30' => '0',
'deliveryTimeFrame_Over_30' => '0',
),
'rollupIndicator' => '2',
'isPrimaryLocation' => true,
),
),
)
$data_json = json_encode($data);
$headers = array(
'date: ' . $date,
'Authorization: ' . $hmacAuth,
'Content-Type: application/json',
'Content-Length: ' . strlen($data_json)
);
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url . "/marketplace/v1/merchantapplication/creditdecision");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data_json);
$res = curl_exec($ch);
echo($res);
?>
The above command returns JSON structured like this:
{
"orderId": "6VD7D",
"status": "pending",
"merchantId": ""
}
This endpoint allows developers to create a request for credit decision without submitting the complete order details.
The service is set up to request the minimum required information a credit decision. For best results, Threatmatrix and Identity verification should be performed.
Request
POST /marketplace/v1/merchantapplication/creditdecision
The endpoint takes a JSON object as input, which contains following information.
| Parameter | Required | Data Type | Short Description |
|---|---|---|---|
| transactionInfo | ✔ | object | Transactions information used to determine pricing. |
| annualVolume | ✔ | double | Annual transaction volume in USD. |
| mccTypes | ✔ | string | “Merchant Category Code” MCC description (refer to: GET MCC/Category). |
| mcc | ✔ | string | MCC Code (refer to: GET MCC/Category). |
| creditCardVolume | ✔ | double | Annual credit card transaction volume in USD. |
| averageTicket | ✔ | double | Average ticket price in USD. |
| highestTicket | ✔ | double | Highest ticket price in USD. |
| category | ✔ | string | Category eg: "RETAIL/MOTO" (refer to: GET Categories). |
| ownerInformation | ✔ | array | Array of (minimum one) objects, each containing the information of the owner(s) of the business. |
| firstName | ✔ | string | Owner’s first name. |
| lastName | ✔ | string | Owner’s last name. |
| ssn | ✔ | string | Owner’s Social Security Number in “#########” format. |
| dateofBirth | ✔ | string | Owner’s date of birth in “YYYY-MM-DD” format. |
| title | ✔ | string | Title of the listed owner. Possible values: "Owner", "Partner", "President", etc. |
| percentOwned | ✔ | integer | Percentage of the company owned by this owner. All owners must equal 100%. |
| address1 | ✔ | string | Street address. |
| address2 | string | Second line of street address, if applicable. i.e. Unit, Floor, Suite, etc. | |
| city | ✔ | string | City. |
| state | ✔ | string | State in abbreviated format. i.e. for California send "CA". |
| country | ✔ | string | ISO Standard Country Code of the country. |
| zip | ✔ | string | ZIP/postal code. |
| phone | string | Phone number. | |
string | Email address. | ||
| merchantInformation | ✔ | array | Array of (minimum one) objects, each containing the information about a location of the business. |
| category | ✔ | string | Category eg: "RETAIL" (refer to: GET Categories). |
| dbaName | ✔ | string | DBA name. |
| legalName | ✔ | string | Legal business name. |
| taxFilingName | ✔ | string | IRS tax filing name for the business. Can be validated against taxId using the POST TIN/Validate service. |
| yearsInBusiness | ✔ | string | Business started date. |
| organizationType | ✔ | string | Organization type represented by an abbreviated code. See possible values here. |
| stateOfIncorporation | ✔ | string | State of incorporation in abbreviated format. i.e. for California send "CA". |
| taxId | ✔ | string | A Taxpayer Identification Number (TIN) is an identification number used by the Internal Revenue Service (IRS). Can be validated against taxFilingName using the POST TIN/Validate service. |
| foreignEntityOption | ✔ | string | Indicates if the business can claim foreign status according to IRS regulations. Possible values: "Y" or "N". |
| tinType | ✔ | integer | Type of Taxpayer Identification Number (TIN). |
| tinRequestedGuid | ✔ | string | Universal ID for the request of the POST TIN/Validate service. |
| url | string | URL of business website. | |
| contactInformation | ✔ | array | Array of (minimum one) object(s), each of which represents a business location. contactType, address1, address2, address3, city, state, postalCode, country, phone, and email. |
| contactType | ✔ | string | Type of location. Possible values: "LOCATION", "CORPORATE", "SHIPPING", "SHIP_TO", "TRADING", "BILLING", "PRIMARY", "DISPUTE", "TRAIN_BY", "STANDARD". |
| address1 | ✔ | string | Street address. |
| address2 | string | Second line of street address, if applicable. i.e. Unit, Floor, Suite, etc. | |
| city | ✔ | string | City. |
| state | ✔ | string | State in abbreviated format. i.e. for California send "CA". |
| country | ✔ | string | ISO Standard Country Code of the country. |
| postalCode | ✔ | string | ZIP/postal code. |
| contactTime | string | Preference on contact time. | |
| phone | ✔ | string | Phone number. |
string | Email address. | ||
| locationInformation | ✔ | array | Array of (minimum one) objects, each containing the information about each business location, including e-commerce locations. |
| dbaName | ✔ | string | DBA name. |
| merchantId | string | Merchant identifier. | |
| mccDescription | ✔ | string | “Merchant Category Code” MCC description (refer to: GET MCC/Category). |
| mcc | ✔ | string | MCC Code (refer to: GET MCC/Category). |
| averageTicket | ✔ | double | Average ticket price in USD. |
| highestTicket | ✔ | double | Actual or estimated highest ticket price in USD. |
| isPrimaryLocation | ✔ | boolean | Indicates whether this object represents the primary business location. |
| faceToFace | ✔ | string | Percentage (converted to string) of payments/transactions made face to face (can’t exceed 100%). |
| phoneOrEmail | ✔ | string | Percentage (converted to string) of payments/transactions made by phone or email (can’t exceed 100%). |
| internet | ✔ | string | Percentage (converted to string) of payments/transactions made on the internet (can’t exceed 100%). |
| rollupIndicator | ✔ | string | |
| category | string | Category eg: "RETAIL" (refer to: GET Categories). | |
| siteSurvey | ✔ | object | A visit in an official capacity to examine a site to determine its suitability for some enterprise. |
| siteVisitation | ✔ | string | Indicates whether site visitation was performed/is required or not. |
| deliveryTimeFrame_0_To_7 | ✔ | string | Percentage of services delivered between 0-7 days after transaction. |
| deliveryTimeFrame_8_To_14 | ✔ | string | Percentage of services delivered between 8-14 days after transaction. |
| deliveryTimeFrame_15_To_30 | ✔ | string | Percentage of services delivered between 15-30 days after transaction. |
| deliveryTimeFrame_Over_30 | ✔ | string | Percentage of services delivered more than 30 days after transaction. |
| bankInformation | ✔ | array | Array of (minimum one) object(s) that collects the ACH information. |
| instName | ✔ | string | Financial institution name such as "JPMORGAN CHASE BANK", etc. |
| abaNumber | ✔ | string | ABA routing transit number. A nine digit code to identify a financial institution. Needs to be validated using the POST Banks/Validate service. |
| accountNumber | ✔ | string | Checking account number. Usually 10-12 digit number to identify the merchant’s account. |
| ordinal | integer | Default to 2 | |
| isPrimary | ✔ | boolean | Indicates whether this object represents the primary bank. |
| equipmentLocation | array | ||
| lineItemId | long | ||
| configurableLineItemId | long | ||
| attributes | array | ||
| attributeName | string | ||
| attributeValue | string | ||
| attributeDomain | string | ||
| threatMetrixGuid | string | The GUID to be used to invoke the ThreatMetrix webservice call. | |
| identityAnswers | object | Object containing the identity verification results. Contains idNumber, answers-received, idequiv-result, qualifiers, summary-result and results. | |
| idNumber | integer | Unique identification for the Identity Verification for this record. | |
| answers-received | integer | Number of answers received. Note: You must send 3 answers in order to get a successful response. | |
| idequiv-result | object | Wrapper object containing result of the overall submission. Contains key and message. | |
| ↳ message | string | Display message for idequiv-result. | |
| ↳ key | string | Message identifier for idequiv-result. | |
| qualifiers | object | Wrapper object containing qualifying messages (qualifier arrays). This provides information on the record lookup based on verifying the data provided before, such as the address, TIN, name, etc. | |
| qualifier | array | One qualifier message. Contains key and message. | |
| ↳ message | string | Display message for the qualifier. | |
| ↳ key | string | Message identifier for the qualifier. | |
| summary-result | object | Wrapper object containing result of the record lookup. This provides information on the success or failure to locate the record to verify. Contains key and message. | |
| ↳ message | string | Display message for summary message: "PASS" or "FAIL". | |
| ↳ key | string | Message identifier for summary-results. | |
| results | object | Wrapper object containing result of the record lookup. This provides information on the success or failure to locate the record to verify. Contains key and message. | |
| ↳ message | string | Display message for results. | |
| ↳ key | string | Message identifier for results. |
Response
The endpoint returns an object containing information about the credit decision.
| Parameter | Data Type | Description |
|---|---|---|
| orderId | string | Order Id. The numeric identifier to be used in the merchant boarding process as input to reference the order. |
| status | string | Status of credit decision. Possible Values: "Approved", "Pending". |
| merchantIdentifier | string | merchant MIDis provided in case of an approved merchant. |
POST Merchantapplication/SingleOutlet
data = {
"merchantInformation": {
"dbaName": "John's Business Supplies",
"legalName": "John's Business Supplies, Inc.",
"taxId": "989898989",
"businessStartedOn": "1991-09-01",
"organizationType": "Partnership",
"stateOfIncorporation": "CA",
"taxFilingName": "John's Business Supplies",
"foreignEntityOption": "N",
"tinRequestedGuid": "",
"tinType": "EIN",
"contactInformation": [
{
"contactType": "LOCATION",
"address1": "123 Main Street",
"address2": "Suite 123",
"city": "SCHENECTADY",
"state": "NY",
"postalCode": "12345",
"country": "US",
"phone": "1234567890"
},
{
"contactType": "CORPORATE",
"address1": "123 Main Street",
"address2": "Suite 123",
"city": "SCHENECTADY",
"state": "NY",
"postalCode": "12345",
"country": "US",
"phone": "1234567890"
}
],
"transactionInfo": {
"mccDescription": "Appliances, Electronics, Computers",
"mcc": "5734",
"annualVolume": 450000,
"creditCardVolume": 350000,
"averageTicket": 10,
"highestTicket": 25,
"category": "RETAIL",
"amexSENumber": "",
"methodofPayment": {
"faceToFace": "100",
"phoneOrEmail": "0",
"internet": "0"
}
},
"siteSurvey": {
"siteVisitation": "Not Required",
"deliveryTimeFrame_0_To_7": "100",
"deliveryTimeFrame_8_To_14": "0",
"deliveryTimeFrame_15_To_30": "0",
"deliveryTimeFrame_Over_30": "0",
"returnPolicy": "Exchange Only",
"separateRefundPolicy": "No"
},
"bankInformation": [
{
"instName": "JPMORGAN CHASE BANK, NA",
"abaNumber": "021202337",
"accountNumber": "123456789",
"deposits": 1,
"nonBankAdjustments": 1,
"depositAdjustments": 1,
"chargebackReversals": 1,
"interchangeAssessments": 1,
"discountServices": 1,
"fees": 1,
"financialAdjustments": 1,
"chargebacks": 1
}
]
},
"ownerInformation": [
{
"firstName": "William",
"lastName": "Smith",
"ssn": "989898989",
"dateofBirth": "1988-03-14",
"title": "Owner",
"percentOwned": 40,
"contactInformation": {
"contactType": "OWNER",
"address1": "123 Market Street",
"city": "SCHENECTADY",
"state": "NY",
"postalCode": "12345",
"country": "US",
"phone": "1234567890",
"email": "williamsmith@email.com"
}
},
{
"firstName": "John",
"lastName": "Smith",
"ssn": "989898989",
"dateofBirth": "1988-03-14",
"title": "Owner",
"percentOwned": 60,
"contactInformation": {
"contactType": "OWNER",
"address1": "12 Peninsula Avenue",
"address2": "Apt 1",
"city": "SCHENECTADY",
"state": "NY",
"postalCode": "12345",
"country": "US",
"phone": "1234567890",
"email": "johnsmith@emai.com"
}
}
],
"pricingDetails": [
{
"productId": "73843",
"feeDefault": 0,
"defaultAmt": 0,
"rateDefault": 0,
"quantity": 1,
"productConfigurations": [
{
"type": "PROD_ATTR",
"name": "FRONT_END",
"value": "NASHVILLE"
},
{
"type": "TERM_ATTR",
"name": "AUTO_SETTLE",
"value": "YES"
}
]
},
{
"productId": "2",
"feeDefault": 0,
"defaultAmt": 0,
"rateDefault": 0,
"quantity": 1
},
{
"productId": "3",
"feeDefault": 0,
"defaultAmt": 0,
"rateDefault": 0,
"quantity": 1
}
],
"cartDetails": [
{
"productId": "74043",
"price": 799,
"term": "P",
"qty": 1
},
{
"productId": "50712",
"price": 19.95,
"term": "P",
"qty": 1
}
],
"shippingAddress": {
"company": "John's Business Supplies",
"firstName": "John",
"lastName": "Smith",
"address1": "123 Main Street",
"address2": "Suite 123",
"city": "SCHENECTADY",
"postalCode": "12345",
"email": "johnsmith@emai.com",
"phone": "1234567890",
"state": "NY",
"country": "USA"
},
"advancedPreferences": {
"statementDeliveryType": "Email",
"statementType": "Detail",
"statementEmailAddress": "johnsmith@emai.com",
"form1099Electronically": true,
"form1099ToEmail": true
}
}
endpoint = "/marketplace/v1/merchantapplication/12345/singleoutlet"
r = requests.post(url + endpoint, json=data, headers=headers)
print(r)
ENDPOINT="$URL/marketplace/v1/merchantapplication/12345/singleoutlet"
curl -X POST -H "date: $DATE" -H "Authorization: $HMAC_AUTH" -H "Content-Type:application/json" --data '{
"merchantInformation": {
"dbaName": "John's Business Supplies",
"legalName": "John's Business Supplies, Inc.",
"taxId": "989898989",
"businessStartedOn": "1991-09-01",
"organizationType": "Partnership",
"stateOfIncorporation": "CA",
"taxFilingName": "John's Business Supplies",
"foreignEntityOption": "N",
"tinRequestedGuid": "",
"tinType": "EIN",
"contactInformation": [
{
"contactType": "LOCATION",
"address1": "123 Main Street",
"address2": "Suite 123",
"city": "SCHENECTADY",
"state": "NY",
"postalCode": "12345",
"country": "US",
"phone": "1234567890"
},
{
"contactType": "CORPORATE",
"address1": "123 Main Street",
"address2": "Suite 123",
"city": "SCHENECTADY",
"state": "NY",
"postalCode": "12345",
"country": "US",
"phone": "1234567890"
}
],
"transactionInfo": {
"mccDescription": "Appliances, Electronics, Computers",
"mcc": "5734",
"annualVolume": 450000,
"creditCardVolume": 350000,
"averageTicket": 10,
"highestTicket": 25,
"category": "RETAIL",
"amexSENumber": "",
"methodofPayment": {
"faceToFace": "100",
"phoneOrEmail": "0",
"internet": "0"
}
},
"siteSurvey": {
"siteVisitation": "Not Required",
"deliveryTimeFrame_0_To_7": "100",
"deliveryTimeFrame_8_To_14": "0",
"deliveryTimeFrame_15_To_30": "0",
"deliveryTimeFrame_Over_30": "0",
"returnPolicy": "Exchange Only",
"separateRefundPolicy": "No"
},
"bankInformation": [
{
"instName": "JPMORGAN CHASE BANK, NA",
"abaNumber": "021202337",
"accountNumber": "123456789",
"deposits": 1,
"nonBankAdjustments": 1,
"depositAdjustments": 1,
"chargebackReversals": 1,
"interchangeAssessments": 1,
"discountServices": 1,
"fees": 1,
"financialAdjustments": 1,
"chargebacks": 1
}
]
},
"ownerInformation": [
{
"firstName": "William",
"lastName": "Smith",
"ssn": "989898989",
"dateofBirth": "1988-03-14",
"title": "Owner",
"percentOwned": 40,
"contactInformation": {
"contactType": "OWNER",
"address1": "123 Market Street",
"city": "SCHENECTADY",
"state": "NY",
"postalCode": "12345",
"country": "US",
"phone": "1234567890",
"email": "williamsmith@email.com"
}
},
{
"firstName": "John",
"lastName": "Smith",
"ssn": "989898989",
"dateofBirth": "1988-03-14",
"title": "Owner",
"percentOwned": 60,
"contactInformation": {
"contactType": "OWNER",
"address1": "12 Peninsula Avenue",
"address2": "Apt 1",
"city": "SCHENECTADY",
"state": "NY",
"postalCode": "12345",
"country": "US",
"phone": "1234567890",
"email": "johnsmith@emai.com"
}
}
],
"pricingDetails": [
{
"productId": "73843",
"feeDefault": 0,
"defaultAmt": 0,
"rateDefault": 0,
"quantity": 1,
"productConfigurations": [
{
"type": "PROD_ATTR",
"name": "FRONT_END",
"value": "NASHVILLE"
},
{
"type": "TERM_ATTR",
"name": "AUTO_SETTLE",
"value": "YES"
}
]
},
{
"productId": "2",
"feeDefault": 0,
"defaultAmt": 0,
"rateDefault": 0,
"quantity": 1
},
{
"productId": "3",
"feeDefault": 0,
"defaultAmt": 0,
"rateDefault": 0,
"quantity": 1
}
],
"cartDetails": [
{
"productId": "74043",
"price": 799,
"term": "P",
"qty": 1
},
{
"productId": "50712",
"price": 19.95,
"term": "P",
"qty": 1
}
],
"shippingAddress": {
"company": "John's Business Supplies",
"firstName": "John",
"lastName": "Smith",
"address1": "123 Main Street",
"address2": "Suite 123",
"city": "SCHENECTADY",
"postalCode": "12345",
"email": "johnsmith@emai.com",
"phone": "1234567890",
"state": "NY",
"country": "USA"
},
"advancedPreferences": {
"statementDeliveryType": "Email",
"statementType": "Detail",
"statementEmailAddress": "johnsmith@emai.com",
"form1099Electronically": true,
"form1099ToEmail": true
}
}' $ENDPOINT
var options = {
method: 'POST',
url: url + '/marketplace/v1/merchantapplication/12345/singleoutlet',
headers: getAuthenticationHeaders(),
body: {
"merchantInformation": {
"dbaName": "John's Business Supplies",
"legalName": "John's Business Supplies, Inc.",
"taxId": "989898989",
"businessStartedOn": "1991-09-01",
"organizationType": "Partnership",
"stateOfIncorporation": "CA",
"taxFilingName": "John's Business Supplies",
"foreignEntityOption": "N",
"tinRequestedGuid": "",
"tinType": "EIN",
"contactInformation": [
{
"contactType": "LOCATION",
"address1": "123 Main Street",
"address2": "Suite 123",
"city": "SCHENECTADY",
"state": "NY",
"postalCode": "12345",
"country": "US",
"phone": "1234567890"
},
{
"contactType": "CORPORATE",
"address1": "123 Main Street",
"address2": "Suite 123",
"city": "SCHENECTADY",
"state": "NY",
"postalCode": "12345",
"country": "US",
"phone": "1234567890"
}
],
"transactionInfo": {
"mccDescription": "Appliances, Electronics, Computers",
"mcc": "5734",
"annualVolume": 450000,
"creditCardVolume": 350000,
"averageTicket": 10,
"highestTicket": 25,
"category": "RETAIL",
"amexSENumber": "",
"methodofPayment": {
"faceToFace": "100",
"phoneOrEmail": "0",
"internet": "0"
}
},
"siteSurvey": {
"siteVisitation": "Not Required",
"deliveryTimeFrame_0_To_7": "100",
"deliveryTimeFrame_8_To_14": "0",
"deliveryTimeFrame_15_To_30": "0",
"deliveryTimeFrame_Over_30": "0",
"returnPolicy": "Exchange Only",
"separateRefundPolicy": "No"
},
"bankInformation": [
{
"instName": "JPMORGAN CHASE BANK, NA",
"abaNumber": "021202337",
"accountNumber": "123456789",
"deposits": 1,
"nonBankAdjustments": 1,
"depositAdjustments": 1,
"chargebackReversals": 1,
"interchangeAssessments": 1,
"discountServices": 1,
"fees": 1,
"financialAdjustments": 1,
"chargebacks": 1
}
]
},
"ownerInformation": [
{
"firstName": "William",
"lastName": "Smith",
"ssn": "989898989",
"dateofBirth": "1988-03-14",
"title": "Owner",
"percentOwned": 40,
"contactInformation": {
"contactType": "OWNER",
"address1": "123 Market Street",
"city": "SCHENECTADY",
"state": "NY",
"postalCode": "12345",
"country": "US",
"phone": "1234567890",
"email": "williamsmith@email.com"
}
},
{
"firstName": "John",
"lastName": "Smith",
"ssn": "989898989",
"dateofBirth": "1988-03-14",
"title": "Owner",
"percentOwned": 60,
"contactInformation": {
"contactType": "OWNER",
"address1": "12 Peninsula Avenue",
"address2": "Apt 1",
"city": "SCHENECTADY",
"state": "NY",
"postalCode": "12345",
"country": "US",
"phone": "1234567890",
"email": "johnsmith@emai.com"
}
}
],
"pricingDetails": [
{
"productId": "73843",
"feeDefault": 0,
"defaultAmt": 0,
"rateDefault": 0,
"quantity": 1,
"productConfigurations": [
{
"type": "PROD_ATTR",
"name": "FRONT_END",
"value": "NASHVILLE"
},
{
"type": "TERM_ATTR",
"name": "AUTO_SETTLE",
"value": "YES"
}
]
},
{
"productId": "2",
"feeDefault": 0,
"defaultAmt": 0,
"rateDefault": 0,
"quantity": 1
},
{
"productId": "3",
"feeDefault": 0,
"defaultAmt": 0,
"rateDefault": 0,
"quantity": 1
}
],
"cartDetails": [
{
"productId": "74043",
"price": 799,
"term": "P",
"qty": 1
},
{
"productId": "50712",
"price": 19.95,
"term": "P",
"qty": 1
}
],
"shippingAddress": {
"company": "John's Business Supplies",
"firstName": "John",
"lastName": "Smith",
"address1": "123 Main Street",
"address2": "Suite 123",
"city": "SCHENECTADY",
"postalCode": "12345",
"email": "johnsmith@emai.com",
"phone": "1234567890",
"state": "NY",
"country": "USA"
},
"advancedPreferences": {
"statementDeliveryType": "Email",
"statementType": "Detail",
"statementEmailAddress": "johnsmith@emai.com",
"form1099Electronically": true,
"form1099ToEmail": true
}
},
json: true
};
request(options, function (error, response, body) {
if (error) throw new Error(error);
console.log(response);
});
// Don't forget to add your HMAC Authorization Headers
try {
String jsonString = "{\n" +
" \"merchantInformation\": {
\n" + " \"dbaName\": \"John's Business Supplies\",
\n" + " \"legalName\": \"John's Business Supplies, Inc.\",
\n" + " \"taxId\": \"989898989\",
\n" + " \"businessStartedOn\": \"1991-09-01\",
\n" + " \"organizationType\": \"Partnership\",
\n" + " \"stateOfIncorporation\": \"CA\",
\n" + " \"taxFilingName\": \"John's Business Supplies\",
\n" + " \"foreignEntityOption\": \"N\",
\n" + " \"tinRequestedGuid\": \"\",
\n" + " \"tinType\": \"EIN\",
\n" + " \"contactInformation\": [
\n" + " {
\n" + " \"contactType\": \"LOCATION\",
\n" + " \"address1\": \"123 Main Street\",
\n" + " \"address2\": \"Suite 123\",
\n" + " \"city\": \"SCHENECTADY\",
\n" + " \"state\": \"NY\",
\n" + " \"postalCode\": \"12345\",
\n" + " \"country\": \"US\",
\n" + " \"phone\": \"1234567890\"
\n" + " },
\n" + " {
\n" + " \"contactType\": \"CORPORATE\",
\n" + " \"address1\": \"123 Main Street\",
\n" + " \"address2\": \"Suite 123\",
\n" + " \"city\": \"SCHENECTADY\",
\n" + " \"state\": \"NY\",
\n" + " \"postalCode\": \"12345\",
\n" + " \"country\": \"US\",
\n" + " \"phone\": \"1234567890\"
\n" + " }
\n" + " ],
\n" + " \"transactionInfo\": {
\n" + " \"mccDescription\": \"Appliances, Electronics, Computers\",
\n" + " \"mcc\": \"5734\",
\n" + " \"annualVolume\": 450000,
\n" + " \"creditCardVolume\": 350000,
\n" + " \"averageTicket\": 10,
\n" + " \"highestTicket\": 25,
\n" + " \"category\": \"RETAIL\",
\n" + " \"amexSENumber\": \"\",
\n" + " \"methodofPayment\": {
\n" + " \"faceToFace\": \"100\",
\n" + " \"phoneOrEmail\": \"0\",
\n" + " \"internet\": \"0\"
\n" + " }
\n" + " },
\n" + " \"siteSurvey\": {
\n" + " \"siteVisitation\": \"Not Required\",
\n" + " \"deliveryTimeFrame_0_To_7\": \"100\",
\n" + " \"deliveryTimeFrame_8_To_14\": \"0\",
\n" + " \"deliveryTimeFrame_15_To_30\": \"0\",
\n" + " \"deliveryTimeFrame_Over_30\": \"0\",
\n" + " \"returnPolicy\": \"Exchange Only\",
\n" + " \"separateRefundPolicy\": \"No\"
\n" + " },
\n" + " \"bankInformation\": [
\n" + " {
\n" + " \"instName\": \"JPMORGAN CHASE BANK, NA\",
\n" + " \"abaNumber\": \"021202337\",
\n" + " \"accountNumber\": \"123456789\",
\n" + " \"deposits\": 1,
\n" + " \"nonBankAdjustments\": 1,
\n" + " \"depositAdjustments\": 1,
\n" + " \"chargebackReversals\": 1,
\n" + " \"interchangeAssessments\": 1,
\n" + " \"discountServices\": 1,
\n" + " \"fees\": 1,
\n" + " \"financialAdjustments\": 1,
\n" + " \"chargebacks\": 1
\n" + " }
\n" + " ]
\n" + " },
\n" + " \"ownerInformation\": [
\n" + " {
\n" + " \"firstName\": \"William\",
\n" + " \"lastName\": \"Smith\",
\n" + " \"ssn\": \"989898989\",
\n" + " \"dateofBirth\": \"1988-03-14\",
\n" + " \"title\": \"Owner\",
\n" + " \"percentOwned\": 40,
\n" + " \"contactInformation\": {
\n" + " \"contactType\": \"OWNER\",
\n" + " \"address1\": \"123 Market Street\",
\n" + " \"city\": \"SCHENECTADY\",
\n" + " \"state\": \"NY\",
\n" + " \"postalCode\": \"12345\",
\n" + " \"country\": \"US\",
\n" + " \"phone\": \"1234567890\",
\n" + " \"email\": \"williamsmith@email.com\"
\n" + " }
\n" + " },
\n" + " {
\n" + " \"firstName\": \"John\",
\n" + " \"lastName\": \"Smith\",
\n" + " \"ssn\": \"989898989\",
\n" + " \"dateofBirth\": \"1988-03-14\",
\n" + " \"title\": \"Owner\",
\n" + " \"percentOwned\": 60,
\n" + " \"contactInformation\": {
\n" + " \"contactType\": \"OWNER\",
\n" + " \"address1\": \"12 Peninsula Avenue\",
\n" + " \"address2\": \"Apt 1\",
\n" + " \"city\": \"SCHENECTADY\",
\n" + " \"state\": \"NY\",
\n" + " \"postalCode\": \"12345\",
\n" + " \"country\": \"US\",
\n" + " \"phone\": \"1234567890\",
\n" + " \"email\": \"johnsmith@emai.com\"
\n" + " }
\n" + " }
\n" + " ],
\n" + " \"pricingDetails\": [
\n" + " {
\n" + " \"productId\": \"73843\",
\n" + " \"feeDefault\": 0,
\n" + " \"defaultAmt\": 0,
\n" + " \"rateDefault\": 0,
\n" + " \"quantity\": 1,
\n" + " \"productConfigurations\": [
\n" + " {
\n" + " \"type\": \"PROD_ATTR\",
\n" + " \"name\": \"FRONT_END\",
\n" + " \"value\": \"NASHVILLE\"
\n" + " },
\n" + " {
\n" + " \"type\": \"TERM_ATTR\",
\n" + " \"name\": \"AUTO_SETTLE\",
\n" + " \"value\": \"YES\"
\n" + " }
\n" + " ]
\n" + " },
\n" + " {
\n" + " \"productId\": \"2\",
\n" + " \"feeDefault\": 0,
\n" + " \"defaultAmt\": 0,
\n" + " \"rateDefault\": 0,
\n" + " \"quantity\": 1
\n" + " },
\n" + " {
\n" + " \"productId\": \"3\",
\n" + " \"feeDefault\": 0,
\n" + " \"defaultAmt\": 0,
\n" + " \"rateDefault\": 0,
\n" + " \"quantity\": 1
\n" + " }
\n" + " ],
\n" + " \"cartDetails\": [
\n" + " {
\n" + " \"productId\": \"74043\",
\n" + " \"price\": 799,
\n" + " \"term\": \"P\",
\n" + " \"qty\": 1
\n" + " },
\n" + " {
\n" + " \"productId\": \"50712\",
\n" + " \"price\": 19.95,
\n" + " \"term\": \"P\",
\n" + " \"qty\": 1
\n" + " }
\n" + " ],
\n" + " \"shippingAddress\": {
\n" + " \"company\": \"John's Business Supplies\",
\n" + " \"firstName\": \"John\",
\n" + " \"lastName\": \"Smith\",
\n" + " \"address1\": \"123 Main Street\",
\n" + " \"address2\": \"Suite 123\",
\n" + " \"city\": \"SCHENECTADY\",
\n" + " \"postalCode\": \"12345\",
\n" + " \"email\": \"johnsmith@emai.com\",
\n" + " \"phone\": \"1234567890\",
\n" + " \"state\": \"NY\",
\n" + " \"country\": \"USA\"
\n" + " },
\n" + " \"advancedPreferences\": {
\n" + " \"statementDeliveryType\": \"Email\",
\n" + " \"statementType\": \"Detail\",
\n" + " \"statementEmailAddress\": \"johnsmith@emai.com\",
\n" + " \"form1099Electronically\": true,
\n" + " \"form1099ToEmail\": true
\n" + " }
\n" + " }";
StringEntity payload = new StringEntity(jsonString);
HttpResponse response = doPost("/marketplace/v1/merchantapplication/12345/singleoutlet", payload);
int statusCode = response.getStatusLine().getStatusCode();
String response_string = EntityUtils.toString(response.getEntity());
JSONArray json = new JSONArray(response_string);
System.out.println("json:" + json.toString());
} catch (Exception e) {
e.printStackTrace();
}
<?php
# Don't forget to add your HMAC Authorization Headers
$data = array (
'merchantInformation' =>
array (
'dbaName' => 'John\'s Business Supplies',
'legalName' => 'John\'s Business Supplies, Inc.',
'taxId' => '989898989',
'businessStartedOn' => '1991-09-01',
'organizationType' => 'Partnership',
'stateOfIncorporation' => 'CA',
'taxFilingName' => 'John\'s Business Supplies',
'foreignEntityOption' => 'N',
'tinRequestedGuid' => '',
'tinType' => 'EIN',
'contactInformation' =>
array (
0 =>
array (
'contactType' => 'LOCATION',
'address1' => '123 Main Street',
'address2' => 'Suite 123',
'city' => 'SCHENECTADY',
'state' => 'NY',
'postalCode' => '12345',
'country' => 'US',
'phone' => '1234567890',
),
1 =>
array (
'contactType' => 'CORPORATE',
'address1' => '123 Main Street',
'address2' => 'Suite 123',
'city' => 'SCHENECTADY',
'state' => 'NY',
'postalCode' => '12345',
'country' => 'US',
'phone' => '1234567890',
),
),
'transactionInfo' =>
array (
'mccDescription' => 'Appliances, Electronics, Computers',
'mcc' => '5734',
'annualVolume' => 450000,
'creditCardVolume' => 350000,
'averageTicket' => 10,
'highestTicket' => 25,
'category' => 'RETAIL',
'amexSENumber' => '',
'methodofPayment' =>
array (
'faceToFace' => '100',
'phoneOrEmail' => '0',
'internet' => '0',
),
),
'siteSurvey' =>
array (
'siteVisitation' => 'Not Required',
'deliveryTimeFrame_0_To_7' => '100',
'deliveryTimeFrame_8_To_14' => '0',
'deliveryTimeFrame_15_To_30' => '0',
'deliveryTimeFrame_Over_30' => '0',
'returnPolicy' => 'Exchange Only',
'separateRefundPolicy' => 'No',
),
'bankInformation' =>
array (
0 =>
array (
'instName' => 'JPMORGAN CHASE BANK, NA',
'abaNumber' => '021202337',
'accountNumber' => '123456789',
'deposits' => 1,
'nonBankAdjustments' => 1,
'depositAdjustments' => 1,
'chargebackReversals' => 1,
'interchangeAssessments' => 1,
'discountServices' => 1,
'fees' => 1,
'financialAdjustments' => 1,
'chargebacks' => 1,
),
),
),
'ownerInformation' =>
array (
0 =>
array (
'firstName' => 'William',
'lastName' => 'Smith',
'ssn' => '989898989',
'dateofBirth' => '1988-03-14',
'title' => 'Owner',
'percentOwned' => 40,
'contactInformation' =>
array (
'contactType' => 'OWNER',
'address1' => '123 Market Street',
'city' => 'SCHENECTADY',
'state' => 'NY',
'postalCode' => '12345',
'country' => 'US',
'phone' => '1234567890',
'email' => 'williamsmith@email.com',
),
),
1 =>
array (
'firstName' => 'John',
'lastName' => 'Smith',
'ssn' => '989898989',
'dateofBirth' => '1988-03-14',
'title' => 'Owner',
'percentOwned' => 60,
'contactInformation' =>
array (
'contactType' => 'OWNER',
'address1' => '12 Peninsula Avenue',
'address2' => 'Apt 1',
'city' => 'SCHENECTADY',
'state' => 'NY',
'postalCode' => '12345',
'country' => 'US',
'phone' => '1234567890',
'email' => 'johnsmith@emai.com',
),
),
),
'pricingDetails' =>
array (
0 =>
array (
'productId' => '73843',
'feeDefault' => 0,
'defaultAmt' => 0,
'rateDefault' => 0,
'quantity' => 1,
'productConfigurations' =>
array (
0 =>
array (
'type' => 'PROD_ATTR',
'name' => 'FRONT_END',
'value' => 'NASHVILLE',
),
1 =>
array (
'type' => 'TERM_ATTR',
'name' => 'AUTO_SETTLE',
'value' => 'YES',
),
),
),
1 =>
array (
'productId' => '2',
'feeDefault' => 0,
'defaultAmt' => 0,
'rateDefault' => 0,
'quantity' => 1,
),
2 =>
array (
'productId' => '3',
'feeDefault' => 0,
'defaultAmt' => 0,
'rateDefault' => 0,
'quantity' => 1,
),
),
'cartDetails' =>
array (
0 =>
array (
'productId' => '74043',
'price' => 799,
'term' => 'P',
'qty' => 1,
),
1 =>
array (
'productId' => '50712',
'price' => 19.949999999999999,
'term' => 'P',
'qty' => 1,
),
),
'shippingAddress' =>
array (
'company' => 'John\'s Business Supplies',
'firstName' => 'John',
'lastName' => 'Smith',
'address1' => '123 Main Street',
'address2' => 'Suite 123',
'city' => 'SCHENECTADY',
'postalCode' => '12345',
'email' => 'johnsmith@emai.com',
'phone' => '1234567890',
'state' => 'NY',
'country' => 'USA',
),
'advancedPreferences' =>
array (
'statementDeliveryType' => 'Email',
'statementType' => 'Detail',
'statementEmailAddress' => 'johnsmith@emai.com',
'form1099Electronically' => true,
'form1099ToEmail' => true,
),
)
$data_json = json_encode($data);
$headers = array(
'date: ' . $date,
'Authorization: ' . $hmacAuth,
'Content-Type: application/json',
'Content-Length: ' . strlen($data_json)
);
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url . "/marketplace/v1/merchantapplication/12345/singleoutlet");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data_json);
$res = curl_exec($ch);
echo($res);
?>
The above command returns JSON structured like this:
{
"orderId": "df444"
}
Request
POST /marketplace/v1/merchantapplication/12345/singleoutlet
In the request URL, use the orderId as it was returned in the response of the POST Merchantorders API.
The endpoint takes a JSON object as input, which contains following information.
| Parameter | Required | Data Type | Short Description |
|---|---|---|---|
| merchantInformation | ✔ | array | Array of (minimum one) objects, each containing the information about a location of the business. |
| dbaName | ✔ | string | DBA name. |
| legalName | ✔ | string | Legal business name. |
| taxId | ✔ | string | A Taxpayer Identification Number (TIN) is an identification number used by the Internal Revenue Service (IRS). Can be validated against taxFilingName using the POST TIN/Validate service. |
| businessStartedOn | ✔ | string | Business started date in “YYYY-MM-DD” format. |
| organizationType | ✔ | string | Organization type represented by an abbreviated code. See possible values here. |
| stateOfIncorporation | ✔ | string | State of incorporation in abbreviated format. i.e. for California send "CA". |
| taxFilingName | ✔ | string | IRS tax filing name for the business. Can be validated against taxId using the POST TIN/Validate service. |
| foreignEntityOption | ✔ | string | Indicates if the business can claim foreign status according to IRS regulations. Possible values: "N" (None) or "A" (A foreign person/A business that can claim foreign entity status). |
| tinType | ✔ | integer | Type of Taxpayer Identification Number (TIN). Possible values: "EIN" or "SSN". |
| tinRequestedGuid | string | Universal ID for the request of the POST TIN/Validate service. | |
| contactInformation | ✔ | array | Array of (minimum one) object(s), each of which represents a business location. contactType, address1, address2, address3, city, state, postalCode, country, phone, and email. |
| contactType | ✔ | string | Type of location. Possible values: "LOCATION", "CORPORATE", "OWNER". |
| address1 | ✔ | string | Street address. |
| address2 | string | Second line of street address, if applicable. i.e. Unit, Floor, Suite, etc. | |
| address3 | string | Third line of street address. | |
| city | ✔ | string | City. |
| state | ✔ | string | State in abbreviated format. i.e. for California send "CA". |
| country | ✔ | string | ISO Standard Country Code of the country. |
| postalCode | ✔ | string | ZIP/postal code. |
| phone | string | Phone number. | |
| transactionInfo | ✔ | object | Transactions information used to determine pricing. |
| mccDescription | string | “Merchant Category Code” MCC description (refer to: GET MCC/Category). | |
| mcc | ✔ | string | MCC Code (refer to: GET MCC/Category). |
| annualVolume | ✔ | double | Annual transaction volume in USD. |
| averageTicket | ✔ | double | Average ticket price in USD. |
| highestTicket | ✔ | double | Highest ticket price in USD. |
| category | ✔ | string | Category eg: "RETAIL/MOTO" (refer to: GET Categories). |
| amexSENumber | long | In case Amex Volume greater than or equal to US$ 1 million, provide the Service Establishment Number. | |
| methodofPayment | object | Object containing information about how the business operates and accepts transactions. Sum of values of the three contained fields must equal 100. | |
| faceToFace | integer | Percentage of payments/transactions made face to face (can’t exceed 100%). | |
| phoneOrEmail | integer | Percentage of payments/transactions made by phone or email (can’t exceed 100%). | |
| internet | integer | Percentage of payments/transactions made on the internet (can’t exceed 100%). | |
| siteSurvey | ✔ | object | A visit in an official capacity to examine a site to determine its suitability for some enterprise. |
| siteVisitation | ✔ | string | "Y" or "N". Indicates whether site visitation was performed or not. |
| deliveryTimeFrame_0_To_7 | ✔ | string | Percentage of services delivered between 0-7 days after transaction. |
| deliveryTimeFrame_8_To_14 | ✔ | string | Percentage of services delivered between 8-14 days after transaction. |
| deliveryTimeFrame_15_To_30 | ✔ | string | Percentage of services delivered between 15-30 days after transaction. |
| deliveryTimeFrame_Over_30 | ✔ | string | Percentage of services delivered more than 30 days after transaction. |
| bankInformation | ✔ | array | Array of (minimum one) object(s) that collects the ACH information. |
| instName | ✔ | string | Financial institution name such as "JPMORGAN CHASE BANK", etc. |
| abaNumber | ✔ | string | ABA routing transit number. A nine digit code to identify a financial institution. Needs to be validated using the POST Banks/Validate service. |
| accountNumber | ✔ | string | Checking account number. Usually 10-12 digit number to identify the merchant’s account. |
| ordinal | ✔ | integer | Default to 2. |
| deposits | long | Default to 1. | |
| nonBankAdjustments | long | Default to 1. | |
| depositAdjustments | long | Default to 1. | |
| chargebackReversals | long | Default to 1. | |
| interchangeAssessments | long | Default to 1. | |
| discountServices | long | Default to 1. | |
| fees | long | Default to 1. | |
| financialAdjustments | long | Default to 1. | |
| chargebacks | long | Default to 1. | |
| ownerInformation | ✔ | array | Array of (minimum one) objects, each containing the information of the owner(s) of the business. |
| firstName | ✔ | string | Owner’s first name. |
| lastName | ✔ | string | Owner’s last name. |
| ssn | ✔ | string | Owner’s Social Security Number. |
| dateofBirth | ✔ | string | Owner’s date of birth in “YYYY-MM-DD” format. |
| title | ✔ | string | Title of the listed contact within the organization. See Merchant organizationType and title combinations for detail. |
| percentOwned | ✔ | integer | Percentage of the company owned by this owner. All owners must equal 100%. |
| contactInformation | ✔ | array | Array of (minimum one) object(s), each of which represents the contact information of the owner. Each can contain contactType, address1, address2, address3, city, state, postalCode, country, phone, and email. |
| contactType | ✔ | string | Type of location. Possible values: "OWNER", "PRINCIPAL", "LANDLORD", "BENEFICIARY". |
| address1 | ✔ | string | Street address. |
| address2 | string | Second line of street address, if applicable. i.e. Unit, Floor, Suite, etc. | |
| address3 | string | Third line of street address. | |
| city | ✔ | string | City. |
| state | ✔ | string | State in abbreviated format. i.e. for California send "CA". |
| country | ✔ | string | ISO Standard Country Code of the country. |
| postalCode | ✔ | string | ZIP/postal code. |
| phone | ✔ | string | Phone number. |
| ✔ | string | Email address. | |
| merchantInformation | ✔ | array | Array of (minimum one) objects, each containing t |
| pricingDetails | ✔ | array | Array of object each containing the detailed pricing information of a product (hardware, software, acquiring, fees, etc.) in the order. |
| productId | ✔ | integer | Numeric value that uniquely identifies a product (canonical identifier). |
| quantity | ✔ | integer | Quantity of the Pricing Product to be added to the Order. (Generally 1.) |
| defaultAmt | ✔ | integer | Price/amount to be collected (usually as a one-time payment) in USD. |
| feeDefault | ✔ | double | Fee charged per occurrence in USD. |
| rateDefault | ✔ | double | Percentage of transaction amount charged per occurrence. |
| productConfigurations | object | Contains name, value and domain. | |
| name | string | Product attribute name. | |
| value | string | Product attribute value. | |
| domain | string | Domain like pricing. | |
| cartDetails | ✔ | object | Object containing the details of the Order Summary. |
| data | ✔ | array | Array of objects containing products in the cart. |
| productId | ✔ | string | productId as string. Numeric value that uniquely identifies each product (canonical identifier). |
| price | ✔ | double | Unit price for a product. |
| term | ✔ | string | purchaseType eg: Purchase, Rent, Lease etc. See list of possible values here. |
| qty | ✔ | integer | Quantity selected. |
| shippingAddress | ✔ | array | Array of one object containing shipping information. |
| company | ✔ | string | Company name. |
| firstName | ✔ | string | First name. |
| lastName | ✔ | string | Last name. |
| address1 | ✔ | string | Street address. |
| address2 | string | Second line of street address, if applicable. i.e. Unit, Floor, Suite, etc. | |
| city | ✔ | string | City. |
| state | ✔ | string | State in abbreviated format. i.e. for California send "CA". |
| country | ✔ | string | ISO Standard Country Code of the country. |
| postalCode | ✔ | string | ZIP/postal code. |
| phone | string | Phone number. | |
| ✔ | string | Email address. | |
| advancedPreferences | ✔ | string | |
| statementDeliveryType | ✔ | string | Way in which the merchant wants to receive statements. *Possible value(s): "EMAIL". |
| statementType | ✔ | string | Type of statement. *Possible values: "DETAIL", "SUMMARY". |
| statementEmailAddress | string | Email address for statement delivery. | |
| form1099Electronically | ✔ | boolean | Does the merchant want to receive Form 1099 electronically? |
| form1099ToEmail | ✔ | boolean | Does the merchant want to receive Form 1099 in email? |
Response
The endpoint returns an object containing one string which represents the orderId.
| Parameter | Data Type | Description |
|---|---|---|
| orderId | string | The unique identifier of an order returned after successful submission. Used in following processes as input data. |
Merchant organizationType and title combinations
The possible values of the title of each owner (in ownerInformation array) depend on the value of organizationType (in merchantInformation array). The combinations are as follows:
organizationType | Possible values of owner title |
|---|---|
"PARTNERSHIPS" | "PARTNER" |
"GOVERNMENT" | "OWNER" "Partner" "President" "Vice President" "Member LLC" "Secretary" "Treasurer" "CEO" "CFO" "COO" |
"Public Corporation" | "President" "Vice President" "Secretary" "Treasurer" "CEO" "CFO" "COO" |
"Limited Liability Company (LLC)" | "President" "Vice President" "Secretary" "Treasurer" "CEO" "CFO" "COO" "Member LLC" |
"Private Corporation" | "President" "Vice President" "Secretary" "Treasurer" "CEO" "CFO" "COO" |
"Tax Exempt" | "OWNER,Partner" "President" "Vice President" "Member LLC" "Secretary" "Treasurer" "CEO" "CFO" "COO" |
"Sole Proprietorship" | "OWNER" |
GET Contracts/Agreement
# Don't forget to add your HMAC Authorization Headers
endpoint = url + "marketplace/v1/contracts/14567/agreement"
r = requests.get(url + endpoint, headers=headers)
print(r)
# Don't forget to add your HMAC Authorization Headers
ENDPOINT="$URL/marketplace/v1/contracts/14567/agreement"
curl -X GET -H "date: $DATE" -H "Authorization: $HMAC_AUTH" $ENDPOINT
// Don't forget to add your HMAC Authorization Headers
var options = { method: 'GET',
url: url + '/marketplace/v1/contracts/14567/agreement',
headers: getAuthenticationHeaders() };
request(options, function (error, response, body) {
if (error) throw new Error(error);
console.log(response);
});
// Don't forget to add your HMAC Authorization Headers
HttpResponse response = null;
try {
response = doGet("/marketplace/v1/contracts/14567/agreement");
int statusCode = response.getStatusLine().getStatusCode();
String response_string = EntityUtils.toString(response.getEntity());
JSONObject json = new JSONObject(response_string);
System.out.println("json:" + json.toString());
} catch (Exception e) {
e.printStackTrace();
}
<?php
# Don't forget to add your HMAC Authorization Headers
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url . "/marketplace/v1/contracts/14567/agreement");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
$res = curl_exec($ch);
echo($res);
?>
The above command returns JSON structured like this:
{
"legalName":"TEST MERCHANT",
"dbaName":"TEST MERCHANT",
"taxIdMask":"XXXXX8989",
"mcc":"5946",
"yearsInBusiness":1451606400000,
"organizationTypeReferenceCode":"I",
"productDescription":"Appliances, Electronics, Computers",
"createdByCoId":"477",
"phoneNo":"2222222222",
"createdDate":1478041631000,
"emvEnabled":true,
"debitEnabled":true,
"amexEnabled":false,
"discoverEnabled":true,
"amexAnnualVolume":0.0,
"averageTicket":15.0,
"industryType":"RETAIL",
"orderStatus":"Application Submitted",
"employeeInformation":[
{
"firstName":"JON",
"lastName":"DOE",
"dateOfBirth":"1998-01-01",
"title":"OWNER",
"ssn":"HzqcqIYuo6tlzR/opyz6k0dmuTvbG0p5xEhS2IiF0n18+TIsNJBfil9zInxVqlL+UlwWlmkfWSjPCLu2xXDgky8iQ5neXsksug4G0hB3Ay0O716M8taQVpbxRFifmI358rVRUv7Qp0ztHu1BxZSWLaHiZtk0HczUv2krtlXovXmI+Y4LmzlW2evDHyCyIXBY0iJHObMBkw2C3Mfr6c/vvtdBD6jg36eb8nwjKsudd6P+adoCxcK0VXatJOuwnXykAK79sWgVZx1wh48mp9dNVPOiiynP7ms8HmUwzomzNhCtc/ipDhdmAqbyyq7+r5ho8+btkK3lTtV/QO8Amk8F+Q==",
"ssnMasked":"XXXXX8989",
"yearsAtBusiness":null
}
],
"contactsInformation":[
{
"abaNumber":"DgW+xP09HqUvSL9RIZT0qeRqwWaqVh+8w0taYT7PF28HK6YYncgJMSSSJJxk8thk2SKAJIrzdvE8DQP+4Wi9M/a9ZUkV6BPpJL+OL35chf0/UjnBeB54niAX8V6Uk06TA4qD+luWo0egQ1R4/X2FzmSvHajcj5aD9XahgbSl8GW8Xt5j6/Y/UwjgCdUv8kHjADcszbVPUfYvIN58ukU9ujb9CMLJgf9Al9hzAC/icR6/gRNC7zCpYPN2Y/wpWOXlAx+AySovuNfqqphOLMz78V9w7moS1GPpcwnhZfNCeSODpa089fLOFYhe7JLxaRPKG+nDAe4XFVie4IT2+4oIyQ==",
"abaMasked":"XXXXX0021",
"accountNumber":"DvWhcGv+kzPfHknYW2RQfFW4qByXlSQ6ygNlXUoAfxOD4Ua4h3jbWqTljQ8eZHjEEC7p1Jpuz74CygleCDWsr6m/H9ZyyDFenADpvMLQRPffxH2N+/+YWLR5vKltda9yMD7TtsF4ORxTZwMVpULJrD3pBdYzIfYMGwwDtJHkAEKgY9nY/ZlguhfdCSYsJe8/fQ7w5SI2YoDZ4WoQGvYER1r11OW7WH/KXp3hLrldQudF33CQi4TaBZ+r8z0he12WQlZD9BIHXiOXR7X38SoppcnZPzRrgXosSzwN03Ngfb/oqtmDSpG5IpK01mpH1VBs5vbuOqAGXCglbFVLJUDW9Q==",
"accountNumberMasked":"9898",
"instName":null
}
],
"merchantContactInformation":[
{
"contactType":"SHIP_TO",
"state":"NY",
"postalCode":"12345",
"address1":"123 bus addr",
"address2":"",
"email":"test@gmail.com",
"url":null,
"mobile":"2222222222",
"country":"USA",
"voice":"2222222222",
"name":"jon consumer",
"companyName":"mmis test dev134",
"city":"Schenectady"
}, {
"contactType":"LOCATION",
"state":"NE",
"postalCode":"68116",
"address1":"123 OWNER",
"address2":null,
"email":"test@gmail.com",
"url":"website.com",
"mobile":"1111111111",
"country":"USA",
"voice":"2222222222",
"name":"MMIS TEST DEV134",
"companyName":null,
"city":"OMAHA"
}, {
"contactType":"CORPORATE",
"state":"NY",
"postalCode":"12345",
"address1":"123 BUS ADDR",
"address2":"",
"email":"test@gmail.com",
"url":"website.com",
"mobile":"1111111111",
"country":"USA",
"voice":"2222222222",
"name":"MMIS TEST DEV134",
"companyName":null,
"city":"SCHENECTADY"
}
],
"merchantAttributesInformation":[
{
"attrValue":"AL",
"attrName":"INC_STATE",
"attrDomain":"CORP INFO"
}, {
"attrValue":"MMIS TEST DEV134",
"attrName":"IRS_FIL_NM",
"attrDomain":"CORPORATE"
}, {
"attrValue":"A",
"attrName":"IRS_FRGN_IND",
"attrDomain":"CORPORATE"
}, {
"attrValue":"R",
"attrName":"NORTH_IND_TYPE",
"attrDomain":"CUSTOMER SETUP"
}, {
"attrValue":"001",
"attrName":"PRICE_TYPE",
"attrDomain":"CUSTOMER SETUP"
}, {
"attrValue":"SITE.COM",
"attrName":"URL_TEXT",
"attrDomain":"ENCLOSURES"
}, {
"attrValue":"",
"attrName":"REQUEST_GUID",
"attrDomain":"IRS_INFO"
}, {
"attrValue":"123456.0",
"attrName":"ANNUAL_SALE",
"attrDomain":"SALES INFORMATION"
}, {
"attrValue":"75",
"attrName":"HI_TKT",
"attrDomain":"SALES INFORMATION"
}, {
"attrValue":"70",
"attrName":"INTERNET",
"attrDomain":"SALES INFORMATION"
}, {
"attrValue":"20",
"attrName":"PHONE",
"attrDomain":"SALES INFORMATION"
}, {
"attrValue":"10",
"attrName":"SWIPED",
"attrDomain":"SALES INFORMATION"
}
],
"productList":[
{
"mpaProductKey":"mcLicenseFee",
"value":0.0217
}, {
"mpaProductKey":"mcCrossBorderFee",
"value":0.85
}, {
"mpaProductKey":"visaIntlUSD",
"value":1.05
}, {
"mpaProductKey":"visaIntlNonUSD",
"value":1.45
}, {
"mpaProductKey":"visaCreditRateTier2",
"value":2.55
}, {
"mpaProductKey":"visaDebitRateTier2",
"value":2.55
}, {
"mpaProductKey":"visaCreditNonQualRateTier2",
"value":4.01
}, {
"mpaProductKey":"visaDebitNonQualRateTier2",
"value":4.01
}, {
"mpaProductKey":"unbundledDebitFee",
"value":0.39
}, {
"mpaProductKey":"voiceAuthFee",
"value":0.75
}, {
"mpaProductKey":"mcNetworkAccessFee",
"value":0.034
}, {
"mpaProductKey":"visaCreditFeeTier",
"value":0.29
}, {
"mpaProductKey":"visaDebitNonQualFeeTier",
"value":0.29
}, {
"mpaProductKey":"transarmorDataProtection",
"value":0
}, {
"mpaProductKey":"visaCreditNonQualFeeTier",
"value":0.29
}, {
"mpaProductKey":"visaDebitFeeTier",
"value":0.29
}, {
"mpaProductKey":"cloverServiceFee",
"value":29.95
}, {
"mpaProductKey":"applicationFee",
"value":149
}, {
"mpaProductKey":"debitStartUp",
"value":5E+1
}, {
"mpaProductKey":"minimumProcessingFee",
"value":25
}, {
"mpaProductKey":"chargebackFee",
"value":25
}, {
"mpaProductKey":"achRejectFee",
"value":25
}, {
"mpaProductKey":"batchSettlementFee",
"value":0.39
}, {
"mpaProductKey":"avsFee",
"value":0.1
}, {
"mpaProductKey":"busAdvPkg",
"value":9.95
}, {
"mpaProductKey":"transarmorSolution",
"value":19.95
}
],
"equipmentList":[
{
"term":"LT36",
"fullNameTerm":"36 Month Lease",
"quantity":"1",
"equipmentType":"IBUNDLE",
"industryType":"RETAIL",
"modelName":"Clover Mini 3G/WiFi",
"unitPrice":"22.93000",
"leaseSum":45.86,
"totalCostToLease":1650.96,
"leaseTerm":36
}, {
"term":"P",
"fullNameTerm":"Purchased",
"quantity":"1",
"equipmentType":"IBUNDLE",
"industryType":"RETAIL",
"modelName":"Clover Mobile 3G/WiFi Package",
"unitPrice":"749.00000",
"leaseSum":0,
"totalCostToLease":0,
"leaseTerm":null
}
],
"equipmentListLease":[
{
"term":"LT36",
"fullNameTerm":"36 Month Lease",
"quantity":"1",
"equipmentType":"IBUNDLE",
"industryType":"RETAIL",
"modelName":"Clover Mini 3G/WiFi",
"unitPrice":"22.93000",
"leaseSum":45.86,
"totalCostToLease":1650.96,
"leaseTerm":36
}
]
}
This endpoint retrieves all information for the Merchant Agreement that you can display to the applicant for their final “signature.”
Request
GET /marketplace/v1/contracts/{orderId}/agreement
In the URL, use the orderId as it was returned in the response of the POST Application/Checkout API.
| Parameter | Required | Data Type | Description |
|---|---|---|---|
| no input |
Response
The endpoint returns an object containing values entered and validated in previous endpoints such as POST Application/Update and POST Application/Checkout.
| Parameter | Data Type | Description |
|---|---|---|
| legalName | string | Legal business name. |
| dbaName | string | DBA name. |
| taxIdMask | string | Masked value of taxId entered in POST Application/Update with last 4 digits visible. |
| mcc | string | MCC Code. |
| yearsInBusiness | long | The year the business started (represented by January 1 YYYY 00:00:00 GMT). Unix Timestamp in milliseconds in GMT. |
| organizationTypeReferenceCode | string | Organization type represented by an abbreviated code. See possible values here. |
| productDescription | string | Label/description for the MCC code. |
| createdByCoId | string | Created-by company ID. |
| phoneNo | string | Business phone number. |
| createdDate | long | Creation date of the merchant account record. Unix Timestamp in milliseconds in GMT. |
| emvEnabled | boolean | EMV option for processing enabled flag. true: enabled, false: not enabled. |
| debitEnabled | boolean | Debit option for processing enabled flag. true: enabled, false: not enabled. |
| amexEnabled | boolean | American Express option for processing enabled flag. true: enabled, false: not enabled. |
| discoverEnabled | boolean | Discover option for processing enabled flag. true: enabled, false: not enabled. |
| amexAnnualVolume | double | Actual or estimated annual American Express credit card transaction volume in USD. |
| averageTicket | double | Actual or estimated average ticket price in USD. |
| industryType | string | Industry Category used to determine the MCC code: name attribute of the Business Category. |
| orderStatus | string | Status of the order and/or merchant application. |
| employeeInformation | array | Array of object(s) containing information about the owner(s) of the business. |
| firstName | string | Owner’s first name. |
| lastName | string | Owner’s last name. |
| dateOfBirth | string | Owner’s date of birth in “YYYY-MM-DD” format. |
| title | string | Owner’s title in the business. |
| ssn | string | Base64 encoded value of Social Security Number. |
| ssnMasked | string | Masked value of Social Security Number with last 4 digits visible. |
| yearsAtBusiness | long | Year since the business has been operating at the current location (represented by January 1 YYYY 00:00:00 GMT). Unix Timestamp in milliseconds in GMT. |
| contactsInformation | array | Array of object(s) containing the ACH information abaNumber and accountNumber. |
| abaNumber | string | Base64 encoded value of the ABA routing transit number. |
| abaMasked | string | Masked value of the ABA routing transit number with last 4 digits visible. |
| accountNumber | string | Base64 encoded value of the checking account number. |
| accountNumberMasked | string | Masked value of the checking account number with last 4 digits visible. |
| instName | string | Bank name as returned by the validation service of the abaNumber. |
| merchantContactInformation | array | Array of object(s) containing business information. |
| contactType | string | The type of contact for the set of data for this contact object. Possible values are "CORPORATE": business info, "LOCATION": merchant/personal info, "SHIP-TO": shipping info. |
| state | string | State the business is located in, in abbreviated format. i.e. for California send "CA". |
| postalCode | string | Business ZIP code. |
| address1 | string | Street address of the business. |
| address2 | string | Second line of street address, if applicable. i.e. Unit, Floor, Suite etc. |
string | Primary contact email address. | |
| url | string | URL of business website, can be populated from same input as businessWebsite. |
| mobile | string | Primary contact cell phone number. |
| country | string | Country the business is located in. |
| voice | string | Primary contact phone number OR business primary phone number. |
| name | string | Contact information First and Last name. |
| companyName | string | Business name, same as name entered in POST Application/Update. |
| city | string | City the business is located in. |
| merchantAttributesInformation | array | An array of all merchant attributes based on a given orderId. |
| attrValue | string | Numeric value belonging to a specific domain/name combination in merchant attributes. |
| attrName | string | Name for merchant attributes. See possible values here. |
| attrDomain | string | Domain for merchant attributes. Possible values: "SALES INFORMATION", "IRS_INFO", "ENCLOSURES", "CUSTOMER SETUP", "CORPORATE", "CORP INFO". |
| productList | array | Array of object(s) each representing a processing product by key-value pairs. |
| mpaProductKey | string | Key description of processing product. |
| value | string | Numeric value, identifier of the processing product. |
| equipmentList | array | Array of object(s) each representing an equipment product. |
| term | string | purchaseType eg: L48, P, etc. See list of possible values here. |
| fullNameTerm | string | purchaseTypeLabel eg: Purchase, Rent, Lease etc. See list of possible values here. |
| quantity | string | Quantity selected. |
| equipmentType | string | productType See list of possible values here. |
| industryType | string | Same as industryType above. Industry Category used to determine the MCC code: name attribute of the Business Category. |
| modelName | string | productName: Product name. |
| unitPrice | string | Unit price for a product to be collected (usually as a one-time payment) in USD. |
| leaseSum | float | if term is “L##”: Amount to be collected on a recurring basis for leasing the product. |
| totalCostToLease | float | if term is “L##”: the sum of all (leaseSum) payments to lease over the leaseTerm. |
| leaseTerm | integer | if term is “L##”: number of payments to be made. |
| equipmentListLease | array | Array of object(s) each representing an equipment product that is to be leased. |
| term | string | purchaseType eg: "L48", P, etc. See list of possible values here. |
| fullNameTerm | string | purchaseTypeLabel eg: Purchase, Rent, Lease etc. See list of possible values here. |
| quantity | string | Quantity selected |
| equipmentType | string | productType See list of possible values here. |
| industryType | string | Same as industryType above. Industry Category used to determine the MCC code: name attribute of the Business Category. |
| unitPrice | string | Unit price for a product to be collected (usually as a one-time payment) in USD. |
| leaseSum | float | Amount to be collected on a recurring basis for leasing the product. |
| totalCostToLease | float | The sum of all (leaseSum) payments to lease over the leaseTerm. |
| leaseTerm | integer | Number of payments to be made. |
Possible values for attrName
All possible values that are used in the Merchant Agreement are listed below.
| Value | Meaning |
|---|---|
"SWIPED" | Percentage of payments/transactions made face to face. |
"PHONE" | Percentage of payments/transactions made by phone or email. |
"INTERNET" | Percentage of payments/transactions made on the internet. |
"HI_TKT" | Actual or estimated high ticket price in USD. |
"ANNUAL_SALE" | Actual or estimated annual credit card transaction volume in USD. |
"URL_TEXT" | URL of business website. |
"IRS_FRGN_IND" | Indicates if the business can claim foreign status according to IRS regulations. |
"IRS_FIL_NM" | IRS tax filing name for the business. |
"INC_STATE" | State of incorporation in abbreviated format. i.e. for California send "CA". |
POST Application/Contractdocument
# Don't forget to add your HMAC Authorization Headers
# Note: the "document" string below is an incomplete example
data = {
"orderId":"00000",
"document":"JVBERi0xLjQKJeHp69MKMSAwIG9iago8PC9DcmVhdG9yIChNb3ppbGxhLzUuMCBcK . . . "
}
endpoint = "/marketplace/v1/application/contractdocument"
r = requests.post(url + endpoint, json=data, headers=headers)
print(r)
# Don't forget to add your HMAC Authorization Headers
# Note: the "document" string below is an incomplete example
ENDPOINT="$URL/marketplace/v1/application/contractdocument"
curl -X POST -H "date: $DATE" -H "Authorization: $HMAC_AUTH" -H "Content-Type:application/json" --data '{
"orderId":"00000",
"document":"JVBERi0xLjQKJeHp69MKMSAwIG9iago8PC9DcmVhdG9yIChNb3ppbGxhLzUuMCBcK . . . "
}' $ENDPOINT
// Don't forget to add your HMAC Authorization Headers
// Note: the "document" string below is an incomplete example
var options = { method: 'POST',
url: url + '/marketplace/v1/application/contractdocument',
headers: getAuthenticationHeaders(),
body: {
"orderId":"00000",
"document":"JVBERi0xLjQKJeHp69MKMSAwIG9iago8PC9DcmVhdG9yIChNb3ppbGxhLzUuMCBcK . . . "
},
json: true
};
request(options, function (error, response, body) {
if (error) throw new Error(error);
console.log(body);
});
// Don't forget to add your HMAC Authorization Headers
// Note: the value for the "document" parameter in the string below is an incomplete example
try {
String jsonString = "{\n" +
" \"orderId\":\"00000\"\n" +
" \"document\": \"JVBERi0xLjQKJeHp69MKMSAwIG9iago8PC9DcmVhdG9yIChNb3ppbGxhLzUuMCBcK . . . \"\n" +
"}";
StringEntity payload = new StringEntity(jsonString);
HttpResponse response = doPost("/marketplace/v1/application/contractdocument", payload);
int statusCode = response.getStatusLine().getStatusCode();
String response_string = EntityUtils.toString(response.getEntity());
JSONObject json = new JSONObject(response_string);
System.out.println("json:" + json.toString());
} catch (Exception e) {
e.printStackTrace();
}
<?php
# Don't forget to add your HMAC Authorization Headers
# Note: the "document" string below is an incomplete example
$data = array (
'orderId' => '00000',
'document' => 'JVBERi0xLjQKJeHp69MKMSAwIG9iago8PC9DcmVhdG9yIChNb3ppbGxhLzUuMCBcK . . . '
);
$data_json = json_encode($data);
$headers = array(
'date: ' . $date,
'Authorization: ' . $hmacAuth,
'Content-Type: application/json',
'Content-Length: ' . strlen($data_json)
);
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url . "/marketplace/v1/application/contractdocument");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data_json);
$res = curl_exec($ch);
curl_close($ch);
?>
See a complete example payload (
contractdocument.json) on Github.
The above command returns JSON structured like this:
{
"message": "document uploaded"
}
This endpoint submits the Merchant Application. It takes a document in Base64 format and uploads it to First Data as the “Merchant Agreement” for a specific orderId. This is the last step in the Merchant Application process as it submits all order data necessary for First Data to determine the merchant’s eligibility for payment processing.
Request
POST /marketplace/v1/application/contractdocument
The endpoint takes a JSON object as input containing the orderId and an image of the contract document containing user(s) signature(s).
| Parameter | Required | Data Type | Description |
|---|---|---|---|
| orderId | ✔ | string | orderId as string as it was returned in the response of the POST Application/Checkout API. |
| document | ✔ | string | Base64 encoded PDF of the contract document. |
Response
The endpoint returns an object containing a string which is the confirmation for the submission.
| Parameter | Data Type | Description |
|---|---|---|
| message | string | Confirmation that the document was successfully uploaded. |
This is the final step in the Merchant Application process.
After the contract document is submitted, the merchant can be directed to a page which confirms that the Application has been submitted.
POST Application/Signup
# Don't forget to add your HMAC Authorization Headers
# Note: the "document" string below is an incomplete example
data = {
"transactionInfo": {
"mccTypes": "Business to Business (Supplies)",
"mcc": "5978",
"annualVolume": 300000,
"averageTicket": 10,
"highestTicket": 100,
"category": "RETAIL"
},
"cartDetails": {
"data": [{
"id": 74042,
"name": "Clover Mini 3G/WiFi",
"price": 649,
"term": "P",
"qty": 1,
"productType": "Terminal"
}, {
"id": 10013,
"name": "Visa/MasterCard",
"price": 0,
"term": "P",
"qty": 1,
"productType": "ACQUIRING"
}, {
"id": 10022,
"name": "Debit",
"price": 0,
"term": "P",
"qty": 1,
"productType": "ACQUIRING"
}],
"amount": 649,
"shipping_amount": 19.99,
"tax": 0,
"taxPercent": -2,
"total": 668.99,
"shipping_option_id": 1,
"purchaseEnabled": true,
"total_qty": 1
},
"contactInformation": [{
"contactType": "LOCATION",
"address1": "123 Main Street",
"city": "Beverly Hills",
"state": "CA",
"postalCode": "90210",
"country": "USA",
"email": "johndoe@email.com",
"phone": "1234567890",
"url": "jonhnsbusinesssupplies.com"
}, {
"contactType": "CORPORATE",
"address1": "123 Main Street",
"city": "Beverly Hills",
"state": "CA",
"postalCode": "90210",
"country": "USA",
"email": "johndoe@email.com",
"phone": "1234567890",
"url": "jonhnsbusinesssupplies.com"
}],
"merchantAttributes": [{
"highestTicket": 100,
"faceToFace": "90",
"phoneOrEmail": "5",
"internet": "5",
"stateOfIncorporation": "CA",
"taxFilingName": "John Business Supplies, Inc.",
"foreignEntityOption": "N",
"tinRequestedGuid": "17487900F244257DA",
"dbaName": "John's Business Supplies",
"legalName": "John's Business Supplies",
"employeeIdentificationNumber": "989898989",
"yearsInBusiness": "2006-06-01",
"yearsAtLocation":" 2006-06-01",
"organizationType": "Private corporation"
}],
"bankInformation": [{
"instName": "JPMORGAN CHASE BANK, NA",
"abaNumber": "122100024",
"accountNumber": "123567890",
"ordinal": 2
}],
"ownerInformation":[{
"lastName": "Smith",
"firstName": "John",
"ssn": "989898989",
"dateOfBirth": "1983-03-16",
"title": "PARTNER",
"homeContactId": "111",
"taxId": "989898989"
}]
}
endpoint = "/marketplace/v1/application/signup"
r = requests.post(url + endpoint, json=data, headers=headers)
print(r)
# Don't forget to add your HMAC Authorization Headers
# Note: the "document" string below is an incomplete example
ENDPOINT="$URL/marketplace/v1/application/signup"
curl -X POST -H "date: $DATE" -H "Authorization: $HMAC_AUTH" -H "Content-Type:application/json" --data '{
"transactionInfo": {
"mccTypes": "Business to Business (Supplies)",
"mcc": "5978",
"annualVolume": 300000,
"averageTicket": 10,
"highestTicket": 100,
"category": "RETAIL"
},
"cartDetails": {
"data": [{
"id": 74042,
"name": "Clover Mini 3G/WiFi",
"price": 649,
"term": "P",
"qty": 1,
"productType": "Terminal"
}, {
"id": 10013,
"name": "Visa/MasterCard",
"price": 0,
"term": "P",
"qty": 1,
"productType": "ACQUIRING"
}, {
"id": 10022,
"name": "Debit",
"price": 0,
"term": "P",
"qty": 1,
"productType": "ACQUIRING"
}],
"amount": 649,
"shipping_amount": 19.99,
"tax": 0,
"taxPercent": -2,
"total": 668.99,
"shipping_option_id": 1,
"purchaseEnabled": true,
"total_qty": 1
},
"contactInformation": [{
"contactType": "LOCATION",
"address1": "123 Main Street",
"city": "Beverly Hills",
"state": "CA",
"postalCode": "90210",
"country": "USA",
"email": "johndoe@email.com",
"phone": "1234567890",
"url": "jonhnsbusinesssupplies.com"
}, {
"contactType": "CORPORATE",
"address1": "123 Main Street",
"city": "Beverly Hills",
"state": "CA",
"postalCode": "90210",
"country": "USA",
"email": "johndoe@email.com",
"phone": "1234567890",
"url": "jonhnsbusinesssupplies.com"
}],
"merchantAttributes": [{
"highestTicket": 100,
"faceToFace": "90",
"phoneOrEmail": "5",
"internet": "5",
"stateOfIncorporation": "CA",
"taxFilingName": "John Business Supplies, Inc.",
"foreignEntityOption": "N",
"tinRequestedGuid": "17487900F244257DA",
"dbaName": "John's Business Supplies",
"legalName": "John's Business Supplies",
"employeeIdentificationNumber": "989898989",
"yearsInBusiness": "2006-06-01",
"yearsAtLocation":" 2006-06-01",
"organizationType": "Private corporation"
}],
"bankInformation": [{
"instName": "JPMORGAN CHASE BANK, NA",
"abaNumber": "122100024",
"accountNumber": "123567890",
"ordinal": 2
}],
"ownerInformation":[{
"lastName": "Smith",
"firstName": "John",
"ssn": "989898989",
"dateOfBirth": "1983-03-16",
"title": "PARTNER",
"homeContactId": "111",
"taxId": "989898989"
}]
}' $ENDPOINT
// Don't forget to add your HMAC Authorization Headers
// Note: the "document" string below is an incomplete example
var options = { method: 'POST',
url: url + '/marketplace/v1/application/signup',
headers: getAuthenticationHeaders(),
body: {
"transactionInfo": {
"mccTypes": "Business to Business (Supplies)",
"mcc": "5978",
"annualVolume": 300000,
"averageTicket": 10,
"highestTicket": 100,
"category": "RETAIL"
},
"cartDetails": {
"data": [{
"id": 74042,
"name": "Clover Mini 3G/WiFi",
"price": 649,
"term": "P",
"qty": 1,
"productType": "Terminal"
}, {
"id": 10013,
"name": "Visa/MasterCard",
"price": 0,
"term": "P",
"qty": 1,
"productType": "ACQUIRING"
}, {
"id": 10022,
"name": "Debit",
"price": 0,
"term": "P",
"qty": 1,
"productType": "ACQUIRING"
}],
"amount": 649,
"shipping_amount": 19.99,
"tax": 0,
"taxPercent": -2,
"total": 668.99,
"shipping_option_id": 1,
"purchaseEnabled": true,
"total_qty": 1
},
"contactInformation": [{
"contactType": "LOCATION",
"address1": "123 Main Street",
"city": "Beverly Hills",
"state": "CA",
"postalCode": "90210",
"country": "USA",
"email": "johndoe@email.com",
"phone": "1234567890",
"url": "jonhnsbusinesssupplies.com"
}, {
"contactType": "CORPORATE",
"address1": "123 Main Street",
"city": "Beverly Hills",
"state": "CA",
"postalCode": "90210",
"country": "USA",
"email": "johndoe@email.com",
"phone": "1234567890",
"url": "jonhnsbusinesssupplies.com"
}],
"merchantAttributes": [{
"highestTicket": 100,
"faceToFace": "90",
"phoneOrEmail": "5",
"internet": "5",
"stateOfIncorporation": "CA",
"taxFilingName": "John Business Supplies, Inc.",
"foreignEntityOption": "N",
"tinRequestedGuid": "17487900F244257DA",
"dbaName": "John's Business Supplies",
"legalName": "John's Business Supplies",
"employeeIdentificationNumber": "989898989",
"yearsInBusiness": "2006-06-01",
"yearsAtLocation":" 2006-06-01",
"organizationType": "Private corporation"
}],
"bankInformation": [{
"instName": "JPMORGAN CHASE BANK, NA",
"abaNumber": "122100024",
"accountNumber": "123567890",
"ordinal": 2
}],
"ownerInformation":[{
"lastName": "Smith",
"firstName": "John",
"ssn": "989898989",
"dateOfBirth": "1983-03-16",
"title": "PARTNER",
"homeContactId": "111",
"taxId": "989898989"
}]
},
json: true
};
request(options, function (error, response, body) {
if (error) throw new Error(error);
console.log(body);
});
// Don't forget to add your HMAC Authorization Headers
// Note: the value for the "document" parameter in the string below is an incomplete example
try {
String jsonString = "{\n" +
" \"transactionInfo\": { \n" +
" \"mccTypes\": \"Business to Business (Supplies)\",\n" +
" \"mcc\": \"5978\",\n" +
" \"annualVolume\": 300000,\n" +
" \"averageTicket\": 10,\n" +
" \"highestTicket\": 100,\n" +
" \"category\": \"RETAIL\"\n" +
" },\n" +
" \"cartDetails\": { \n" +
" \"data\": [{ \n" +
" \"id\": 74042,\n" +
" \"name\": \"Clover Mini 3G/WiFi\",\n" +
" \"price\": 649,\n" +
" \"term\": \"P\",\n" +
" \"qty\": 1,\n" +
" \"productType\": \"Terminal\"\n" +
" }, { \n" +
" \"id\": 10013,\n" +
" \"name\": \"Visa/MasterCard\",\n" +
" \"price\": 0,\n" +
" \"term\": \"P\",\n" +
" \"qty\": 1,\n" +
" \"productType\": \"ACQUIRING\"\n" +
" }, { \n" +
" \"id\": 10022,\n" +
" \"name\": \"Debit\",\n" +
" \"price\": 0,\n" +
" \"term\": \"P\",\n" +
" \"qty\": 1,\n" +
" \"productType\": \"ACQUIRING\"\n" +
" }],\n" +
" \"amount\": 649,\n" +
" \"shipping_amount\": 19.99,\n" +
" \"tax\": 0,\n" +
" \"taxPercent\": -2,\n" +
" \"total\": 668.99,\n" +
" \"shipping_option_id\": 1,\n" +
" \"purchaseEnabled\": true,\n" +
" \"total_qty\": 1\n" +
" },\n" +
" \"contactInformation\": [{ \n" +
" \"contactType\": \"LOCATION\",\n" +
" \"address1\": \"123 Main Street\",\n" +
" \"city\": \"Beverly Hills\",\n" +
" \"state\": \"CA\",\n" +
" \"postalCode\": \"90210\",\n" +
" \"country\": \"USA\",\n" +
" \"email\": \"johndoe@email.com\",\n" +
" \"phone\": \"1234567890\",\n" +
" \"url\": \"jonhnsbusinesssupplies.com\"\n" +
" }, { \n" +
" \"contactType\": \"CORPORATE\",\n" +
" \"address1\": \"123 Main Street\",\n" +
" \"city\": \"Beverly Hills\",\n" +
" \"state\": \"CA\",\n" +
" \"postalCode\": \"90210\",\n" +
" \"country\": \"USA\",\n" +
" \"email\": \"johndoe@email.com\",\n" +
" \"phone\": \"1234567890\",\n" +
" \"url\": \"jonhnsbusinesssupplies.com\"\n" +
" }],\n" +
" \"merchantAttributes\": [{ \n" +
" \"highestTicket\": 100,\n" +
" \"faceToFace\": \"90\",\n" +
" \"phoneOrEmail\": \"5\",\n" +
" \"internet\": \"5\",\n" +
" \"stateOfIncorporation\": \"CA\",\n" +
" \"taxFilingName\": \"John Business Supplies, Inc.\",\n" +
" \"foreignEntityOption\": \"N\",\n" +
" \"tinRequestedGuid\": \"17487900F244257DA\",\n" +
" \"dbaName\": \"John's Business Supplies\",\n" +
" \"legalName\": \"John's Business Supplies\",\n" +
" \"employeeIdentificationNumber\": \"989898989\",\n" +
" \"yearsInBusiness\": \"2006-06-01\",\n" +
" \"yearsAtLocation\":\" 2006-06-01\",\n" +
" \"organizationType\": \"Private corporation\"\n" +
" }],\n" +
" \"bankInformation\": [{ \n" +
" \"instName\": \"JPMORGAN CHASE BANK, NA\",\n" +
" \"abaNumber\": \"122100024\",\n" +
" \"accountNumber\": \"123567890\",\n" +
" \"ordinal\": 2\n" +
" }],\n" +
" \"ownerInformation\":[{ \n" +
" \"lastName\": \"Smith\",\n" +
" \"firstName\": \"John\",\n" +
" \"ssn\": \"989898989\",\n" +
" \"dateOfBirth\": \"1983-03-16\",\n" +
" \"title\": \"PARTNER\",\n" +
" \"homeContactId\": \"111\",\n" +
" \"taxId\": \"989898989\"\n" +
" }]\n" +
"}";
StringEntity payload = new StringEntity(jsonString);
HttpResponse response = doPost("/marketplace/v1/application/signup", payload);
int statusCode = response.getStatusLine().getStatusCode();
String response_string = EntityUtils.toString(response.getEntity());
JSONObject json = new JSONObject(response_string);
System.out.println("json:" + json.toString());
} catch (Exception e) {
e.printStackTrace();
}
<?php
# Don't forget to add your HMAC Authorization Headers
# Note: the "document" string below is an incomplete example
$data = (
'transactionInfo' =>
array (
'mccTypes' => 'Business to Business (Supplies)',
'mcc' => '5978',
'annualVolume' => 300000,
'averageTicket' => 10,
'highestTicket' => 100,
'category' => 'RETAIL',
),
'cartDetails' =>
array (
'data' =>
array (
0 =>
array (
'id' => 74042,
'name' => 'Clover Mini 3G/WiFi',
'price' => 649,
'term' => 'P',
'qty' => 1,
'productType' => 'Terminal',
),
1 =>
array (
'id' => 10013,
'name' => 'Visa/MasterCard',
'price' => 0,
'term' => 'P',
'qty' => 1,
'productType' => 'ACQUIRING',
),
2 =>
array (
'id' => 10022,
'name' => 'Debit',
'price' => 0,
'term' => 'P',
'qty' => 1,
'productType' => 'ACQUIRING',
),
),
'amount' => 649,
'shipping_amount' => 19.989999999999998,
'tax' => 0,
'taxPercent' => -2,
'total' => 668.99000000000001,
'shipping_option_id' => 1,
'purchaseEnabled' => true,
'total_qty' => 1,
),
'contactInformation' =>
array (
0 =>
array (
'contactType' => 'LOCATION',
'address1' => '123 Main Street',
'city' => 'Beverly Hills',
'state' => 'CA',
'postalCode' => '90210',
'country' => 'USA',
'email' => 'johndoe@email.com',
'phone' => '1234567890',
'url' => 'jonhnsbusinesssupplies.com',
),
1 =>
array (
'contactType' => 'CORPORATE',
'address1' => '123 Main Street',
'city' => 'Beverly Hills',
'state' => 'CA',
'postalCode' => '90210',
'country' => 'USA',
'email' => 'johndoe@email.com',
'phone' => '1234567890',
'url' => 'jonhnsbusinesssupplies.com',
),
),
'merchantAttributes' =>
array (
0 =>
array (
'highestTicket' => 100,
'faceToFace' => '90',
'phoneOrEmail' => '5',
'internet' => '5',
'stateOfIncorporation' => 'CA',
'taxFilingName' => 'John Business Supplies, Inc.',
'foreignEntityOption' => 'N',
'tinRequestedGuid' => '17487900F244257DA',
'dbaName' => 'John\'s Business Supplies',
'legalName' => 'John\'s Business Supplies',
'employeeIdentificationNumber' => '989898989',
'yearsInBusiness' => '2006-06-01',
'yearsAtLocation' => ' 2006-06-01',
'organizationType' => 'Private corporation',
),
),
'bankInformation' =>
array (
0 =>
array (
'instName' => 'JPMORGAN CHASE BANK, NA',
'abaNumber' => '122100024',
'accountNumber' => '123567890',
'ordinal' => 2,
),
),
'ownerInformation' =>
array (
0 =>
array (
'lastName' => 'Smith',
'firstName' => 'John',
'ssn' => '989898989',
'dateOfBirth' => '1983-03-16',
'title' => 'PARTNER',
'homeContactId' => '111',
'taxId' => '989898989',
),
),
);
$data_json = json_encode($data);
$headers = array(
'date: ' . $date,
'Authorization: ' . $hmacAuth,
'Content-Type: application/json',
'Content-Length: ' . strlen($data_json)
);
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url . "/marketplace/v1/application/signup");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data_json);
$res = curl_exec($ch);
curl_close($ch);
?>
The above command returns JSON structured like this:
{
"orderId": 18262
}
This endpoint allows us to validate merchant information and product data and submit an order at the same time. It serves as a combination of POST Application/Checkout and POST Application/Update, intended to be used in certain cases.
Request
POST /marketplace/v1/application/signup
The endpoint takes a JSON object as input containing merchant and transaction information and product data.
| Parameter | Required | Data Type | Description |
|---|---|---|---|
| transactionInfo | ✔ | object | Transactions information used to determine pricing. Contains mccTypes, mcc, annualVolume, averageTicket, highestTicket and category. |
| mccTypes | ✔ | string | “Merchant Category Code” MCC description (refer to: GET MCC/Category). |
| mcc | ✔ | string | MCC Code (refer to: GET MCC/Category). |
| annualVolume | ✔ | long | Actual or estimated annual credit card transaction volume in USD. |
| averageTicket | ✔ | long | Actual or estimated average ticket price in USD. |
| highestTicket | ✔ | long | Actual or estimated highest ticket price in USD. |
| category | ✔ | string | Category name eg: "RETAIL/MOTO" (refer to: GET Categories). |
| cartDetails | ✔ | object | Object containing the details of the Order Summary. Contains data, amount, shipping_amount, tax taxPercent, total, status, shipping_option_id, purchaseEnabled and total_qty. |
| data | ✔ | array | Array of objects containing products in the cart. Contains id, name, price, term, qty and productType. |
| id | ✔ | integer | productId: Numeric value that uniquely identifies each product (canonical identifier). |
| name | ✔ | string | productName: Product name. |
| price | ✔ | float | Unit price for a product. |
| term | ✔ | string | purchaseType eg: Purchase, Rent, Lease etc. See list of possible values here. |
| qty | ✔ | integer | Quantity selected. |
| productType | ✔ | string | Indicates the behavior of the product, or when the merchant is charged a fee in case of “Processing/Pricing” products. |
| amount | ✔ | double | Sum of prices of products in cart in USD. |
| shipping_amount | ✔ | double | Amount to be charged for shipping and handling in USD. |
| tax | ✔ | double | Amount of tax to be collected (based on taxPercent) in USD. |
| taxPercent | ✔ | double | Tax rate in %. You may use any external service to calculate taxes based on location. |
| total | ✔ | double | Total amount to be charged in USD. Sum of amount, shipping_amount and tax. |
| shipping_option_id | ✔ | integer | Numeric identifier for shipping method. Default to 1. Currently only “Ground Shipping” is available, which corresponds to the value 1. |
| purchaseEnabled | ✔ | boolean | Default to true. |
| total_qty | ✔ | integer | Total quantity of products in the Shopping Cart. |
| contactInformation | ✔ | array | Array of (minimum one) object(s), each of which represent business information for a location. Each contains contactType, address1, address2, city, state, postalCode, country, email, phone and url. |
| contactType | ✔ | string | Type of location, i.e "LOCATION", "CORPORATE". |
| address1 | ✔ | string | Street address. |
| address2 | string | Second line of street address, if applicable. i.e. Unit, Floor, Suite, etc. | |
| city | ✔ | string | City the business is located in. |
| state | ✔ | string | State the business is located in, abbreviated format. i.e. for California send "CA". |
| postalCode | ✔ | string | Business ZIP code. |
| country | ✔ | string | Country the business is located in. |
| ✔ | string | Contact email address for location. | |
| phone | ✔ | string | Primary contact phone number OR business primary phone number. |
| url | ✔ | string | URL of business website, can be populated from same input as businessWebsite. |
| merchantAttributes | ✔ | array | Array of (minimum one) object(s) that is required to submit the application form containing transaction and legal information. |
| highestTicket | ✔ | long | Actual or estimated highest ticket price in USD. |
| faceToFace | ✔ | string | Percentage of payments/transactions made face to face (can’t exceed 100%). |
| phoneOrEmail | ✔ | string | Percentage of payments/transactions made by phone or email (can’t exceed 100%). |
| internet | ✔ | string | Percentage of payments/transactions made on the internet (can’t exceed 100%). |
| stateOfIncorporation | ✔ | string | State of incorporation in abbreviated format. i.e. for California send "CA". |
| taxFilingName | ✔ | string | IRS tax filing name for the business. Needs to be validated against employeeIdentificationNumber using the POST TIN/Validate service. |
| foreignEntityOption | ✔ | string | Indicates if the business can claim foreign status according to IRS regulations. Possible values: "Y" or "N". |
| tinRequestedGuid | ✔ | string | Universal ID for the request of the POST TIN/Validate service. |
| dbaName | ✔ | string | DBA name. |
| legalName | ✔ | string | Legal business name. |
| employeeIdentificationNumber | ✔ | string | A Taxpayer Identification Number (TIN) is an identification number used by the Internal Revenue Service (IRS). Needs to be validated against taxFilingName using the POST TIN/Validate service. |
| yearsInBusiness | ✔ | string | Number of years in business. |
| yearsAtLocation | ✔ | string | Number of years the business has been operating at the current location. |
| organizationType | ✔ | string | Organization type represented by an abbreviated code. See possible values here. |
| bankInformation | ✔ | array | Array of (minimum one) object(s) that collects the ACH information. |
| instName | ✔ | string | Financial institution name such as JPMORGAN CHASE BANK, etc. |
| abaNumber | ✔ | string | ABA routing transit number. A nine digit code to identify a financial institution. Needs to be validated using the POST Banks/Validate service. |
| accountNumber | ✔ | string | Checking account number. Usually 10-12 digit number to identify the merchant’s account. |
| ordinal | ✔ | long | default to 2 |
| ownerInformation | ✔ | array | Array of (minimum one) object(s) to collect information about the owner(s) of the business. Contains firstName, lastName, ssn, dateOfBirth, title, homeContactId and taxId. |
| lastName | ✔ | string | Owner’s last name. |
| firstName | ✔ | string | Owner’s first name. |
| ssn | ✔ | string | Owner’s Social Security Number in “#########” format. |
| dateOfBirth | ✔ | string | Owner’s date of birth in “YYYY-MM-DD” format. |
| title | ✔ | string | Owner’s title in the organization. |
| homeContactId | ✔ | string | Default to "111". |
| taxId | ✔ | string | Use value for ssn. |
Response
The endpoint returns an object containing an integer which serves as the confirmation for the submission.
| Parameter | Data Type | Description |
|---|---|---|
| orderId | string | Order Id. The numeric identifier to be used in the onboarding process as input to reference the order. |
GET Order Status
# Don't forget to add your HMAC Authorization Headers
endpoint = "/marketplace/v1/merchantorders/12345/status"
r = requests.get(url + endpoint, headers=headers)
print(r)
# Don't forget to add your HMAC Authorization Headers
ENDPOINT="$URL/marketplace/v1/merchantorders/12345/status"
curl -X GET -H "date: $DATE" -H "Authorization: $HMAC_AUTH" $ENDPOINT
// Don't forget to add your HMAC Authorization Headers
var options = {
method: 'GET',
url: url + '/marketplace/v1/products/74042/specs',
headers: getAuthenticationHeaders()
};
request(options, function (error, response, body) {
if (error) throw new Error(error);
console.log(response);
});
// Don't forget to add your HMAC Authorization Headers
HttpResponse response = null;
try {
response = doGet("/marketplace/v1/merchantorders/12345/status");
int statusCode = response.getStatusLine().getStatusCode();
String response_string = EntityUtils.toString(response.getEntity());
JSONObject json = new JSONObject(response_string);
System.out.println("json:" + json.toString());
} catch (Exception e) {
e.printStackTrace();
}
<?php
# Don't forget to add your HMAC Authorization Headers
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url . "/marketplace/v1/merchantorders/12345/status");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
$res = curl_exec($ch);
echo($res);
?>
The above command returns JSON structured like this:
{
"orderId": "nmwDl",
"orderstatus": "Account Approved"
}
This endpoint retrieves information about the status of the order based on its unique identifier. Depending on the status it also provides additional details, such as shipment tracking and merchant identifiers.
Request
GET /marketplace/v1/merchantorders/{orderId}/status
In the request URL, use the orderId as it was returned in the response of the POST Merchantorders API.
| Parameter | Required | Data Type | Default | Description |
|---|---|---|---|---|
| no input |
Response
The endpoint returns an object containing information about the status of the order based on the unique identifier.
| Parameter | Data Type | Description |
|---|---|---|
| orderId | string | The unique identifier of an order returned after successful submission. |
| orderstatus | string | Status of the order. See list of possible values here. |
| merchantIdentifier | string | Primary merchant identifier. Only returned with certain statuses. |
| trackingnumber | string | Primary merchant identifier. Only returned with certain statuses. |
Possible values for orderstatus
| Value | Meaning and Behavior |
|---|---|
"Order Pending" | |
"Application Submitted" | |
"Application Signed" | |
"Approval in progress" | Credit underwiting is in progress. |
"Account Pending" | The account was not auto approved, and the underwriting team will perform manual diligence. |
"Account Approved" | Account is approved. This response will include the merchantIdentifier value. |
"Account set up in progress" | Entitlement set up is complete. |
"Hardware is being shipped" | Equipment is being shipped to the merchant. This response will include the trackingnumber value. |
"Account Ready for processing" |
POST Merchantorders/Status v3
# Don't forget to add your HMAC Authorization Headers
# Note: the "document" string below is an incomplete example
data = {
"orderIds": [
"6bdM7"
]
}
endpoint = "marketplace/v3/merchantorders/status"
r = requests.post(url + endpoint, json=data, headers=headers)
print(r)
# Don't forget to add your HMAC Authorization Headers
# Note: the "document" string below is an incomplete example
ENDPOINT="$URL/marketplace/v3/merchantorders/status"
curl -X POST -H "date: $DATE" -H "Authorization: $HMAC_AUTH" -H "Content-Type:application/json" --data '
{
"orderIds": [
"6bdM7"
]
}' $ENDPOINT
// Don't forget to add your HMAC Authorization Headers
// Note: the "document" string below is an incomplete example
var options = { method: 'POST',
url: url + 'marketplace/v3/merchantorders/status',
headers: getAuthenticationHeaders(),
body: {
"orderIds": [
"6bdM7"
]
},
json: true
};
request(options, function (error, response, body) {
if (error) throw new Error(error);
console.log(body);
});
// Don't forget to add your HMAC Authorization Headers
// Note: the value for the "document" parameter in the string below is an incomplete example
try {
String jsonString = "{\n \"orderIds\": [\n \"6bdM7\"\n ]\n}";
StringEntity payload = new StringEntity(jsonString);
HttpResponse response = doPost("marketplace/v3/merchantorders/status", payload);
int statusCode = response.getStatusLine().getStatusCode();
String response_string = EntityUtils.toString(response.getEntity());
JSONObject json = new JSONObject(response_string);
System.out.println("json:" + json.toString());
} catch (Exception e) {
e.printStackTrace();
}
<?php
# Don't forget to add your HMAC Authorization Headers
# Note: the "document" string below is an incomplete example
$data = array (
'orderIds' =>
array (
0 => '6bdM7',
),
);
$data_json = json_encode($data);
$headers = array(
'date: ' . $date,
'Authorization: ' . $hmacAuth,
'Content-Type: application/json',
'Content-Length: ' . strlen($data_json)
);
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url . "marketplace/v3/merchantorders/status");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data_json);
$res = curl_exec($ch);
curl_close($ch);
?>
The above command returns JSON structured like this:
{
"orders": [
{
"orderId": "6bdM7",
"lastUpdatedDate": "2020-01-27 22:03:04",
"merchants": [
{
"merchantId": "6bLd1",
"lastUpdatedDate": "2020-01-28 03:35:41",
"status": "Shipping label created",
"merchantIdentifier": "958236683844",
"terminals": [
{
"productId": "65823",
"productName": "Clover Register Software",
"terminalId": "6076144",
"shipment": {
"shipper": "Federal Express",
"shippedDate": "2020-01-27 00:00:00.0",
"shippingAddressLine1": "123 DONT SHIP",
"shippingAddressCity": "FOLSOM",
"shippingAddressState": "PA",
"shippingAddressZip": "19033",
"trackingNumbers": [
"1496658763"
]
}
}
]
}
],
"orderHistory": [
{
"orderStatus": "Shipping label created",
"orderStatusTimestamp": "2020-01-28 03:35:41",
"statusComments": null
},
{
"orderStatus": "Terminal - Waiting TASQ Order",
"orderStatusTimestamp": "2020-01-27 22:59:06",
"statusComments": null
},
{
"orderStatus": "Terminal - Waiting TASQ Order",
"orderStatusTimestamp": "2020-01-27 22:12:56",
"statusComments": null
},
{
"orderStatus": "Terminal - Waiting TASQ Order",
"orderStatusTimestamp": "2020-01-27 22:11:51",
"statusComments": null
},
{
"orderStatus": "Account Approved",
"orderStatusTimestamp": "2020-01-27 22:03:04",
"statusComments": null
},
{
"orderStatus": "Terminal Id created",
"orderStatusTimestamp": "2020-01-27 22:01:45",
"statusComments": null
},
{
"orderStatus": "Terminal - Initial Review",
"orderStatusTimestamp": "2020-01-27 22:00:49",
"statusComments": null
},
{
"orderStatus": "Account Pending",
"orderStatusTimestamp": "2020-01-27 21:49:38",
"statusComments": null
},
{
"orderStatus": "Approval in progress",
"orderStatusTimestamp": "2020-01-27 18:59:44",
"statusComments": null
},
{
"orderStatus": "Application Signed",
"orderStatusTimestamp": "2020-01-27 18:56:53",
"statusComments": null
},
{
"orderStatus": "Order Pending",
"orderStatusTimestamp": "2020-01-27 18:50:47",
"statusComments": null
},
{
"orderStatus": "Order Pending",
"orderStatusTimestamp": "2020-01-27 18:50:41",
"statusComments": null
},
{
"orderStatus": "Order Pending",
"orderStatusTimestamp": "2020-01-27 18:49:43",
"statusComments": null
},
{
"orderStatus": "Order Pending",
"orderStatusTimestamp": "2020-01-27 18:46:29",
"statusComments": null
},
{
"orderStatus": "Order Pending",
"orderStatusTimestamp": "2020-01-27 18:46:22",
"statusComments": null
},
{
"orderStatus": "Order Pending",
"orderStatusTimestamp": "2020-01-27 18:45:21",
"statusComments": null
},
{
"orderStatus": "Review Order",
"orderStatusTimestamp": "2020-01-27 18:43:50",
"statusComments": null
},
{
"orderStatus": "Order Pending",
"orderStatusTimestamp": "2020-01-27 18:39:21",
"statusComments": null
},
{
"orderStatus": "Order Pending",
"orderStatusTimestamp": "2020-01-27 18:38:28",
"statusComments": null
},
{
"orderStatus": "Order Pending",
"orderStatusTimestamp": "2020-01-27 18:37:04",
"statusComments": null
},
{
"orderStatus": "Review Order",
"orderStatusTimestamp": "2020-01-27 18:31:26",
"statusComments": null
}
]
}
]
}
Request
POST /marketplace/v3/merchantorders/status
The endpoint takes a JSON object as input, which contains following information.
| Parameter | Required | Data Type | Description |
|---|---|---|---|
| orderIds | ✔ | array | Array of order id. |
Response
| Parameter | Data Type | Short Description |
|---|---|---|
| orderId | string | Order identifier. |
| lastUpdatedDate | string | Last status update time. |
| merchants | array | List of Merchants for an order. |
| merchantId | string | First Data Marketplace merchant ID. |
| lastUpdatedDate | string | Last status update time. |
| status | string | Latest Status of Merchant. |
| merchantIdentifier | string | North Merchant Identifier (MID). |
| terminals | Terminals Objects in Contract. (refer to: terminals Values). | |
| orderHistory | string | List of Order Status. This Array has the complete History of the Contract from the Step one. |
| orderStatus | string | Status of the Contract. (refer to: orderStatus Values). |
| orderStatusTimestamp | string | Time Stamp details of the Status. |
| statusComments | string | Comments, if any, for the Status. |
terminals values
| Parameter | Data Type | Short Description |
|---|---|---|
| productId | string | Product ID. |
| productName | string | Name of the Product. |
| terminalId | string | Terminal Id Information from FDPOS. |
| shipment | Shipment Object. | |
| shipper | string | Shipper Details. |
| shippedDate | string | Shipped Date. |
| shippingAddressLine1 | string | Shipping Address Line. |
| shippingAddressLine2 | string | Shipping Address Line 2. |
| shippingAddressCity | string | City. |
| shippingAddressState | string | State. |
| shippingAddressZip | string | Zip Code. |
| trackingNumbers | array | Shipment Tracking Numbers. |
orderStatus values
| Status Name | Description |
|---|---|
| Review Order | Initial Contract Details Submitted. |
| Order Pending | Location, Business, Advance Preferences Infromation Submitted. |
| Document Uploaded | Document Uploaded for the contract. |
| Application Signed | Application Submitted with Signatures. |
| Shipping label created | Shipment is Progress. |
| Account Approved | Account is approved and Merchant Identifier (MID) will be sent. |
| Terminal Id created | Terminal Id is Created. |
| Pending Data Validation | If any BRS Error in MAMA, MAMA Sends Notification as “BRS_ERROR”. |
| Approval in progress | Credit Underwriting is in progress. |
| Account Pending | The account was not auto approved, and the underwriting team will perform manual diligence. |
| Account Credit Declined | Contract is Declined. |
| Account Credit Rejected | Contract is Rejected in MAI. Credit Team requires more Documents/ Information from BC. |
Status Specific to Diligence Workflow
| Status Name | Description |
|---|---|
| Workflow Initiated | Marketplace workflow has started. |
| North Mid Generated | North MID Assigned. |
| North Migration Initiated | Transfer of merchant details to North Merchant Master. |
| Diligence Credit Input Sent | Merchant information submitted to Diligence for credit decisioning. |
| Equipment fulfillment in progress | FDPOS Request sent. |
| Credit Pending | Received Credit Pending from Diligence/Sent to Diligence. |
| Credit Declined | Received Credit Decline from Diligence. |
| Credit Approved | Received Credit Approval from Diligence. |
| Credit Processing Error | Technical Error in Diligence. |
| North MID Failed | North MID Generation Failed. |
| North migration steps completed | Transfer of merchant details to North Merchant Master completed. |
| North Migration Step Failed - BoardMerchant | North migration error. |
| Pricing Override | Order has Pricing Override. |
| Pricing Rejected | Pricing rejected and sent back to BC for extra document. |
| Pricing Rejected and Closed | Pricing rejected and order closed. |
| Rejected to Sales | Application rejected and sent back to sales for extra documents to upload. |
| Updated Price & Approved | Pricing Overrides Updated and request approved. |
Status Specific to South
| Status Name | Description |
|---|---|
| Sent to VAPP | Appllication Submitted to VAPP. |
| Sent to VAPP Failed | Appilcation Submission Failed. |
| South Funding Setup Complete | Merchant is ready for Funding. |
| South Migration Pending | Credit Approved, Waiting for Merchant Master Boarding. |
POST Cloverplans
# Don't forget to add your HMAC Authorization Headers
data = {
"mcc": "5812",
"productIds": [
"88526", "88527"
]
}
endpoint = "marketplace/v1/cloverplans"
r = requests.post(url + endpoint, json=data, headers=headers)
print(r)
# Don't forget to add your HMAC Authorization Headers
ENDPOINT="$URL/marketplace/v1/cloverplans"
curl -X POST -H "date: $DATE" -H "Authorization: $HMAC_AUTH" -H "Content-Type:application/json" --data '
"{
"mcc": "5812",
"productIds": [
"88526", "88527"
]
}' $ENDPOINT
// Don't forget to add your HMAC Authorization Headers
var options = { method: 'POST',
url: url + 'marketplace/v1/cloverplans',
headers: getAuthenticationHeaders(),
body: {
"mcc": "5812",
"productIds": [
"88526", "88527"
]
},
json: true
};
request(options, function (error, response, body) {
if (error) throw new Error(error);
console.log(body);
});
// Don't forget to add your HMAC Authorization Headers
try {
String jsonString = "{\n \"mcc\": \"5812\",\n \"productIds\": [\n \"88526\", \"88527\"\n ]\n }";
StringEntity payload = new StringEntity(jsonString);
HttpResponse response = doPost("marketplace/v1/cloverplans", payload);
int statusCode = response.getStatusLine().getStatusCode();
String response_string = EntityUtils.toString(response.getEntity());
JSONObject json = new JSONObject(response_string);
System.out.println("json:" + json.toString());
} catch (Exception e) {
e.printStackTrace();
}
<?php
# Don't forget to add your HMAC Authorization Headers
$data = array (
'mcc' => '5812',
'productIds' =>
array (
0 => '88526',
1 => '88527',
),
);
$data_json = json_encode($data);
$headers = array(
'date: ' . $date,
'Authorization: ' . $hmacAuth,
'Content-Type: application/json',
'Content-Length: ' . strlen($data_json)
);
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url . "marketplace/v1/cloverplans");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data_json);
$res = curl_exec($ch);
curl_close($ch);
?>
The above command returns JSON structured like this:
{
"response": [
{
"productId": "7PG6PX3N09NC6",
"planId": "7PG6PX3N09NC6",
"price": 39.95,
"pricePerDevice": 9.95,
"productName": "Counter Service Restaurant",
"productShortDescription": "Counter Service Restaurant",
"productLongDescription": "Basic payment acceptance, Restaurant features w/advanced loyalty functionality, Advanced inventory management, 24/7 support, Employee managemen, Advanced reporting capabilities",
"imageURLS": [
"https://s3-us-west-2.amazonaws.com/cdn-fd/resources/images/product/dev/large/CLOVER_PLANS_IMAGE/CloverImage.jpg",
"https://s3-us-west-2.amazonaws.com/cdn-fd/resources/images/product/dev/thumb/CLOVER_PLANS_IMAGE/CloverImage.jpg"
]
},
{
"productId": "4XSSZ26CDRG64",
"planId": "4XSSZ26CDRG64",
"price": 39.95,
"pricePerDevice": 9.95,
"productName": "Register ",
"productShortDescription": "Register ",
"productLongDescription": "Basic payment acceptance, Advanced inventory management, 24/7 support, Employee management, Advanced reporting capabilities, Customer rewards, Promos and feedback features",
"imageURLS": [
"https://s3-us-west-2.amazonaws.com/cdn-fd/resources/images/product/dev/large/CLOVER_PLANS_IMAGE/CloverImage.jpg",
"https://s3-us-west-2.amazonaws.com/cdn-fd/resources/images/product/dev/thumb/CLOVER_PLANS_IMAGE/CloverImage.jpg"
]
},
{
"productId": "T822C0SA8G3ZR",
"planId": "T822C0SA8G3ZR",
"price": 69.95,
"pricePerDevice": 9.95,
"productName": "Table Service Restaurant ",
"productShortDescription": "Table Service Restaurant ",
"productLongDescription": "Basic payment acceptance, Restaurant features w/advanced loyalty functionality, Advanced inventory management, 24/7 support, Table mapping and layouts, Advanced reporting capabilities",
"imageURLS": [
"https://s3-us-west-2.amazonaws.com/cdn-fd/resources/images/product/dev/large/CLOVER_PLANS_IMAGE/CloverImage.jpg",
"https://s3-us-west-2.amazonaws.com/cdn-fd/resources/images/product/dev/thumb/CLOVER_PLANS_IMAGE/CloverImage.jpg"
]
}
]
}
This endpoint allows us to fetch clover plans for a given criteria.
Request
POST marketplace/v1/cloverplans
The endpoint takes a JSON object as input.
| Parameter | Required | Data Type |
|---|---|---|
| mcc | ✔ | string |
| productIds | ✔ | Array |
| orderId | string |
Response
The endpoint returns an object containing clover plans for a given criteria.
| Parameter | Data Type | Description |
|---|---|---|
| productId | string | |
| planId | string | |
| price | double | |
| pricePerDevice | double | |
| productName | String | |
| productShortDescription | string | |
| productLongDescription | string | |
| imageURLS | Array |
POST Shipping Options
# Don't forget to add your HMAC Authorization Headers
data = {
"contact": {
"address1": "STREETS",
"address2": "",
"city": "Omaha",
"state": "NE",
"postalCode": "68106",
"country": "USA"
},
"productsToShips": [
{
"productId": "90622",
"quantity": 1
},
{
"productId": "89262",
"quantity": 1
}
],
"orderId": "E0xgE"
}
endpoint = "/marketplace/v1/shippingoptions"
r = requests.post(url + endpoint, json=data, headers=headers)
print(r)
# Don't forget to add your HMAC Authorization Headers
ENDPOINT="$URL/marketplace/v1/shippingoptions"
curl -X GET -H "date: $DATE" -H "Authorization: $HMAC_AUTH" $ENDPOINT
"Content-Type:application/json" --data ' {
"contact": {
"address1": "STREETS",
"address2": "",
"city": "Omaha",
"state": "NE",
"postalCode": "68106",
"country": "USA"
},
"productsToShips": [
{
"productId": "90622",
"quantity": 1
},
{
"productId": "89262",
"quantity": 1
}
],
"orderId": "E0xgE"
}' $ENDPOINT
// Don't forget to add your HMAC Authorization Headers
var options = {
method: 'POST',
url: url + '/marketplace/v1/shippingoptions',
headers: getAuthenticationHeaders(),
body: {
"contact": {
"address1": "STREETS",
"address2": "",
"city": "Omaha",
"state": "NE",
"postalCode": "68106",
"country": "USA"
},
"productsToShips": [
{
"productId": "90622",
"quantity": 1
},
{
"productId": "89262",
"quantity": 1
}
],
"orderId": "E0xgE"
},
json: true
};
request(options, function (error, response, body) {
if (error) throw new Error(error);
console.log(response);
});
// Don't forget to add your HMAC Authorization Headers
try {
String jsonString = "{\"contact\":{
\"address1\":\"STREETS\",
\"address2\":\"\",
\"city\":\"Omaha\",
\"state\":\"NE\",
\"postalCode\":\"68106\",
\"country\":\"USA\"},
\"productsToShips\":
[{\"productId\":\"90622\",
\"quantity\":1},
{\"productId\":\"89262\",\"quantity\":1}],
\"orderId\":\"E0xgE\"}";
StringEntity payload = new StringEntity(jsonString);
HttpResponse response = doPost("/marketplace/v1/shippingoptions", payload);
int statusCode = response.getStatusLine().getStatusCode();
String response_string = EntityUtils.toString(response.getEntity());
JSONArray json = new JSONArray(response_string);
System.out.println("json:" + json.toString());
} catch (Exception e) {
e.printStackTrace();
}
<?php
# Don't forget to add your HMAC Authorization Headers
$data = array (
'contact' =>
array (
'address1' => 'STREETS',
'address2' => '',
'city' => 'Omaha',
'state' => 'NE',
'postalCode' => '68106',
'country' => 'USA',
),
'productsToShips' =>
array (
0 =>
array (
'productId' => '90622',
'quantity' => 1,
),
1 =>
array (
'productId' => '89262',
'quantity' => 1,
),
),
'orderId' => 'E0xgE',
)
$data_json = json_encode($data);
$headers = array(
'date: ' . $date,
'Authorization: ' . $hmacAuth,
'Content-Type: application/json',
'Content-Length: ' . strlen($data_json)
);
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url . "/marketplace/v1/shippingoptions");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data_json);
$res = curl_exec($ch);
echo($res);
?>
Example payload:
equipment.json
{
"contact": {
"address1": "STREETS",
"address2": "",
"city": "Omaha",
"state": "NE",
"postalCode": "68106",
"country": "USA"
},
"productsToShips": [
{
"productId": "90622",
"quantity": 1
},
{
"productId": "89262",
"quantity": 1
}
],
"orderId": "E0xgE"
}
The above command returns JSON structured like this (partial response):
{
"addressVerificationResult": {
"resolvedAddress": {
"streetAddressLine1": "3242 DARWIN DR",
"streetAddressLine2": null,
"city": "FREMONT",
"state": "CA",
"zip": "94555",
"countryCode": "US"
},
"addressValid": true
},
"shippingOptions": [
{
"id": 93226,
"productId": "50714",
"shippingOption": "2da",
"carrier": null,
"carrierCode": null,
"productShortDescription": "Shipping Fee - 2 Day Service",
"productLongDescription": "Shipping Fee - 2 Day Service",
"defaultPurchaseType": "P",
"shippingCost": 19.95,
"": null,
"default": false
},
{
"id": 93227,
"productId": "50715",
"shippingOption": "1da",
"carrier": null,
"carrierCode": null,
"productShortDescription": "Shipping Fee - Priority Overnight",
"productLongDescription": "Shipping Fee - Priority Overnight",
"defaultPurchaseType": "P",
"shippingCost": 65,
"deliveryTimestamp": null,
"default": false
},
{
"id": 93228,
"productId": "50732",
"shippingOption": "1D SHIPPING FEE",
"carrier": null,
"carrierCode": null,
"productShortDescription": "1 Day Service (Standard Overnight)",
"productLongDescription": "1 Day Service (Standard Overnight)",
"defaultPurchaseType": "P",
"shippingCost": 65,
"deliveryTimestamp": null,
"default": false
},
{
"id": 93229,
"productId": "50733",
"shippingOption": "1d-S",
"carrier": null,
"carrierCode": null,
"productShortDescription": "Shipping Fee - Saturday Service",
"productLongDescription": "Shipping Fee - Saturday Service",
"defaultPurchaseType": "P",
"shippingCost": 65,
"deliveryTimestamp": null,
"default": false
}
],
"success": false,
"message": "No applicable shipping options found",
"errorCode": "50"
}
Request
POST /marketplace/v1/shippingoptions
The endpoint takes a JSON object as input. Refer to the “Example request payload” for the JSON structure of the request payload object.
| Parameter | Required | Data Type | Description |
|---|---|---|---|
| productsToShips | ✔ | array | Array of objects each (representing Array of products to ship) contains productId and quantity. |
| productId | ✔ | string | productId:productId. |
| quantity | ✔ | string | quantity: Quantity. |
| orderId | ✔ | string | orderId :orderId. |
| contact | ✔ | object | Contact information used for contact information. Contains address1, address2, city, state, postalCode and country. |
| address1 | ✔ | string | Street address. |
| address2 | string | Second line of street address, if applicable. i.e. Unit, Floor, Suite, etc. | |
| city | ✔ | string | City. |
| state | ✔ | string | State in abbreviated format. i.e. for California send "CA". |
| country | ✔ | string | ISO Standard Country Code of the country. |
| postalCode | ✔ | string | ZIP/postal code. |
Response
This API returns an array of objects. Each object contains the following keyword-value pairs.
| Parameter | Data Type | Description |
|---|---|---|
| streetAddressLine1 | string | streetAddressLine1. |
| streetAddressLine2 | string | streetAddressLine2. |
| city | string | city. |
| state | string | state. |
| zip | string | zip. |
| countryCode | string | countryCode. |
| addressValid | boolean | addressValid. |
| id | Long | Product catalog Id. |
| productId | string | product id |
| shippingOption | string | shippingOption |
| carrier | string | carrier. |
| carrierCode | string | carrierCode. |
| productShortDescription | string | productShortDescription. |
| productLongDescription | string | productLongDescription. |
| defaultPurchaseType | string | defaultPurchaseType. |
| shippingCost | BigDecimal | shippingCost. |
| deliveryTimestamp | calendar | deliveryTimestamp. |
| default | boolean | default flag true or false. |
| promotionAppliedMessage | string | promotionAppliedMessage. |