Common Objects
creditcard
This request object holds all of the information needed to process a credit card transaction. While only some of the parameters are required by default, additional fraud modules may further put restrictions on these parameters. Parameters in bold are required.
Parameter Name |
Type |
Description |
number |
number |
Credit card number or token if missing or incorrect. Error codes 11-14 |
expiration |
string |
Credit card expiration date. All numbers, and needs to be formatted as MMYY. Error codes 15-17 |
cardholder |
string |
Name of the Cardholder |
cvc |
integer |
Card verification code on back of card. Its format should be ### or #### |
avs_street |
string |
Street address for address verification |
avs_zip |
integer |
Postal (Zip) code for address verification |
magstripe |
string |
Stores the magstripe data from the swiped card |
check
This request object holds all of the information needed to process a check transaction. Parameters in bold are required.
Parameter Name |
Type |
Description |
accountholder |
string |
Account holder name |
routing |
integer |
Bank Routing Number |
account |
integer |
Bank Account Number |
account_type |
string |
Checking or Savings |
dl_num |
integer |
Drivers license number/id |
dl_state |
string |
Drivers license state (two letter abbrev). See full list here. |
number |
integer |
Check number |
format |
string |
SEC Record type. See list of types here. |
flags |
string |
Comma delimited list of special check process flags. Not need for most scenarios. Available flags: prenote, sameday |
terminal_detail
This request object holds the information associated with a terminal device (if applicable).
Parameter Name |
Type |
Description |
type |
string |
Type of payment terminal |
entrymode |
string |
How payment was presented (i.e. swipe, contactless, manually key, etc.) |
contactless |
bool |
Contactless payment flag (Y/N) |
lane_id |
string |
A numeric field that identifies a merchant's terminal. The MasterCard lane identifier. |
amount_detail
This request object holds optional granular details for the transaction amount. This allows a merchant to track the breakdown of the total amount. For example, a merchant can enter the exact tip amounts being collected from a customer.
Parameter Name |
Type |
Description |
subtotal |
double |
This field is optional, but if it is sent, it must be consistent with the following equation: amount = subtotal - discount + shipping + duty + tax . |
tax |
double |
The amount of tax collected. |
nontaxable |
char(Y/N) |
Transaction is non taxable (Y/N) |
tip |
double |
Amount of tip collected. |
discount |
double |
Amount of discount applied to total transaction. |
shipping |
double |
Amount of shipping fees collected. |
duty |
double |
Amount of duty collected. |
enable_partialauth |
bool |
Enable partial amount authorization. If the available card balance is less than the amount request, the balance will be authorized and the POS must prompt the customer for another payment to cover the remainder. The result_code will be "P" and auth_amount will contain the partial amount that was approved. |
show_tip_line |
bool |
Set to true, to add line to add a tip to printed receipts. |
billing_address
This request object holds all information associated with billing. By default, this object is optional, but becomes required when certain Fraud Modules are enabled.
Parameter Name |
Type |
Description |
company |
string |
Company or Organization Name |
firstname |
string |
First name associated with billing address |
lastname |
string |
Last name |
street |
string |
Primary street number/address information. (i.e. 1234 Main Street) |
street2 |
string |
Additional address information such as apartment number, building number, suite information, etc. |
city |
string |
Billing City |
state |
string |
Two-letter State abbreviation or full state name. |
postalcode |
integer |
Zip code |
country |
string |
Three-letter country code. See full list here |
phone |
string |
The phone number associated with a billing address. The preferred format is to eliminate all non-numeric characters, but any standard formatting is accepted. |
fax |
string |
The fax number associated with a billing address. The preferred format is to eliminate all non-numeric characters, but any standard formatting is accepted. |
shipping_address
This request object holds all information associated with shipping. By default, this object is optional, but becomes required when certain Fraud Modules are enabled.
Parameter Name |
Type |
Description |
company |
string |
Company or Organization Name |
firstname |
string |
First name |
lastname |
string |
Last name |
street |
string |
Primary street number/address information. (i.e. 1234 Main Street) |
street2 |
string |
Additional address information such as apartment number, building number, suite information, etc... |
city |
string |
Shipping City |
state |
string |
Two-letter State abbreviation or full state name. |
postalcode |
integer |
Zip code |
country |
string |
Three-letter country code. See full list here |
phone |
string |
The phone number associated with a shipping address. The preferred format is to eliminate all non-numeric characters, but any standard formatting is accepted. |
avs
This response object holds information associated with the verification status of the Address Verification System (AVS). The AVS system checks the billing address supplied with the address on file at the credit card company.
Parameter Name |
Type |
Description |
result_code |
string |
Address verification result code. (See codes here.) |
result |
string |
Long version of above |
cvc
This response object holds information associated with the verification status of the Card Verification Code (CVC). The cvc system checks to see if the supplied cvc code matches the code on file at the credit card company.
Parameter Name |
Type |
Description |
result_code |
char |
CVC result code (See codes here.) |
result |
string |
Long version of above |
batch
This response object holds information associated with the batch that the transaction belongs to.
Parameter Name |
Type |
Description |
type |
string |
Denotes this object is a batch. |
key |
string |
This is the id of the batch. |
sequence |
string |
The batch sequence number. The first batch the merchant closes is 1, the second is 2, etc. |
traits
This object holds card flags that represents transaction characteristics.
Parameter Name |
Type |
Description |
is_debt |
bool |
Set to true if this transaction is to pay an existing debt. Click here for more information. |
is_bill_pay |
bool |
Set to true if this transaction is a bill pay transaction. |
is_recurring |
bool |
Set to true if this transaction is a recurring transaction. |
is_healthcare |
bool |
Set to true if this transaction is a healthcare transaction. |
is_cash_advance |
bool |
Set to true if this transaction contains a cash advance. |
custom_fields
This response object holds custom fields created the merchant has created.
Parameter Name |
Type |
Description |
1 |
string |
Optional fields for storing custom data. Character Limit: 255 |
2 |
string |
Optional fields for storing custom data. Character Limit: 255 |
3 |
string |
Optional fields for storing custom data. Character Limit: 255 |
... |
|
|
19 |
string |
Optional fields for storing custom data. Character Limit: 255 |
20 |
string |
Optional fields for storing custom data. Character Limit: 255 |
lineitems
This response object holds line items associated with a transaction or an invoice.
Parameter Name |
Required |
Type |
Description |
lineid |
|
integer |
Gateway generated unique line identifier. Will only be included in responses. |
product_refnum |
|
integer |
Gateway generated unique product identifier. Will only be included if the line item is a product from the database. |
product_key |
|
string |
Gateway generated unique product identifier. Will only be included if the line item is a product from the database. |
sku |
|
string |
This is the product’s Stock Keeping Unit number. |
name |
Required |
string |
Product name. |
description |
Required |
string |
Line item description. |
cost |
Required |
double |
Cost of line item. |
qty |
Required |
number |
Quantity of products. |
taxable |
|
boolean |
Denotes if invoice total is taxable. Possible Values: Y or N . Defaults to N . |
tax_rate |
|
number |
Tax percentage that should be applied to line item amount. |
discount_rate |
|
number |
Discount percentage that should be applied to line item amount. |
discount_amount |
|
double |
Discount amount that should be applied to line item amount. |
locationid |
|
number |
In response only. Location of warehouse identifier for warehouse selected in settings |
commodity_code |
|
string |
Commodity code for line item. |
manufacturer |
|
string |
Manufacturer of line item. |
category |
|
string |
Category of line item. Will only be included if the line item is a product from the database. |
size |
|
string |
Line item size. |
color |
|
string |
Line item color. |
transactions (invoice response)
Parameter Name |
Type |
Description |
trans_refnum |
number |
|
trans_key |
string |
|
response |
string |
|
amount |
double |
|
authcode |
string |
|
created |
datetime |
|
type |
string |
|
status |
string |
|
ccnum4 |
number |
Last 4 digits of credit card number used to pay transaction |
cardtype |
number |
|
cardtype_name |
number |
|
checknum |
number |
|
Change Log
Date |
Change |
2018-04-09 |
Corrected parameter names firstname (previously documented as first_name ), lastname (previously documented as last_name ), and postalcode (previously documented as zip ) in the billing_address and shipping address objects. |
2018-03-15 |
Added company to billing_address and shipping_address. |
2017-09-22 |
Added check flags prenote and sameday to check object. |
2017-12-08 |
Added page. Includes sections: creditcard, check, terminal_detail, amount_detail, billing_address, shipping_address, avs, cvc, and batch. |
2017-12-08 |
Added customdata, lineitems, and transactions (invoice response) objects. |
Click here for the full REST API change log.