Glossary

Merchant API

Variable	Type	Description
Limit	Int32	How many results to return
offset	int32	Which record to start on
merchantId	string	The identification number of the merchant's account in the MX Merchant system.
active	boolean	is this user active
saleLimit	float	highest payment amount this user can make
refundLimit	float	Highest refund amount this user can make
Photo	object	base64 encoded profile picture
role	string	what role does this user need? Values: Administrator, Supervisor, Read Only, clerk
username	string	Username of the new user
firstName	string	User's first name
lastName	string	User's last name
email	string	User's email address
mobile	string	User's phone number
password	string	User's new or temporary password
roleId	int32	Account role of API key; Default(Supervisor) is 2
name	string	Name of Key
description	string	Description of Key
Locked	boolean	Is this key locked or active
pageSize	int32	Number of records to return

Lost Provention Object

Variable	Type	Description
KeyedAvsAddress	boolean	Require Street Address when doing keyed trnsactions
KeyedAvsZip	boolean	Require Postal Code when doing keyed transactions
KeyedCvv	boolean	Require CVV when doing keyed transactions
swipeAvsAddress	boolean	Require Street Address when doing swiped transactions
swipedAvsZip	boolean	Require Postal Code when doing swiped transactions
swipedLastFourDigits	boolean	Require Last 4 Digits when doing swiped transactions
checkPhoneNumber	boolean	Require Phone Number when doing check transactions
checkNumber	boolean	Require Check Number when doing check transactions
declineOnCvvMismatch	boolean	Auto-decline on CVV mismatch	True/False
declineOnAvsZipMismatch	boolean	Auto-decline on Postal Code mismatch
declineOnAvsStreetMismatch	boolean	Auto-decline on Street Address mismatch
enableEms	boolean	Enable or Disable EMS Fraud Scoring
EemsPaymentAmountThreshold	boolean	Only trigger EMS checks for payment over this amount
declineOnEmsScoreExceeded	boolean	Auto-decline if EMS score threshold is exceeded
declineEmsScoreThreshold	bolean	EMS Score threshold

Time Restriction Object

Variable	Type	Description
sunday	boolean	date
monday	boolean	date
tuesday	boolean	date
wednesday	boolean	date
thursday	boolean	date
friday	boolean	date
saturday	boolean	date
startTimeMinute	String	date
endTimeMinute	String	date

Merchants Object

Variable	Type	Description
Id	string	Merchant Id
dba	string	Merchant's name
xmid	string	XMID of the Merchant

Payment API

Variable	Type	Description
echo	boolean	Return Response
includeCustomerMatches	boolean	Return customers that have this card vaulted in their account
merchantId	string	The identification number of the merchant's account in the MX Merchant system.
amount	float	the payment amount. Must not be 0.
paymentType	string	Type of transactions Values: Sale, Refund, CashAdvance, Prepaid, Adjustment, Void, Reversal, Authorization, SaleCompletion, PaymentTransaction, Withdrawal, Balance
tenderType	string	Values: Card, Check, Cash, Mutiple, Loyalty, ACH
entryClass	string	Gets or sets the ACH entry class Values: CCD, PPD, TEL, WEB
cardPresent	boolean	Is the credit card is present at the time of payment?
authOnly	boolean	Indicates that this payment should NOT be added to current batch. AuthOnly payment won't be settled.
isAuth	boolean	Should this card be authorized?
isSettleFunds	boolean	should this transaction be settled?
customerName	string	Customer Name(256 char)(Does Not assoicate payment to customer)
customerCode	string	Client provided customer reference number(assoicated with Customer Number). Cannot be combined with invoideId and clientReference if B2b is On
meta	string	Memo Field
replayId	int32	A merchant-supplied identifier to uniquely identify a payment request to facilitate retries due to I/O related issues. This identifier must be unique. If supplied, we will check for a payment that matches this identifier. If found will return an identical response of the original request. Represents a bigInt value.
source	string	Values: API, Quick Pay, Recurring, Link2Pay, Terminal
clientReference	string	Client provided payment reference number; can be assoicated with multiple payments (17 char max)
invoice	string	Client provided invoice number(Generated by servver if not provided, 16 char max)
invoiceIds	array of strings	If there are multiple invoices, you can send in an array of existing invoice ids (Note: they must already exist in MX Merchant)
orderIds	array of strings	If there are multiple orders, you can send in an array of existing order ids (Note: they must already exist in MX Merchant)
tax	float	Tax Amount(included in amount)
taxExempt	boolean	if true, tax amount must be 0
cardPresentType	string	values:CardPresentKeyed, CardPresentSwiped, CardNotPresent
device	string	Gets/Sets the device identifier, this is the terminal id
shipAmount	float	Gets/Sets the ship amount, used by level 3 data during settlement
shipToCountry	string	Gets/Sets the 3-digit alphanumeric ship-to country code, i. e. USA, used by level 3 data during settlement
shipToZip	string	Gets/Sets the ship-to zip code, using by level 3 data during settlement
shouldVaultCard	boolean	Use this param to valut a new card to a new or existing customer. Send in customer.id to vault an existing customer, and at a minimum, customer.firstName or customer. LastName to vault the card to a new customer.
tip	float	Gets/Sets the amount of the gratuity (included in amount).
vatAmount	float	Gets/Sets the vat amount, used by level 3 data during settlement
vatRate	float	Gets/Sets the VAT rate, used by level 3 data during settlement
transactionType	string	Values: Any, Sale, Refund, Authorization
tenderType	string	Values: Any, Card, Cash, Check, Ach
status	string	Values: Any, Approved, Voided, Declined
dateType	string	Values: Any, Today, Yesterday, WeekToDate, MonthToDate, Last7, Last30, Custom
startDate	string	YYYY-MM-DDthh:mm:ssZ(Required for Custom dataType)
endDate	string	YYYY-MM-DDThh:mm:ssZ(Required for Custom dataType)
source	string	Values: Any, quickPay, link2Pay, Recurring, Order, mxExpress, mxRetail, API, BIP, terminal
limit	int32	Number of records to return
id	int32	Specific paymentId to return a single payment
includeCustomer	boolean	Returns the customer object associcated with the payment
paymentId	string	The id of the payment
force	boolean	Force a refund if transaction has already settled
startTime	string	YYYY-MM-DDThh:mm:ssZ(Required for Custom dateType)
endTime	string	YYYY-MM-DDThh:mm:ssZ(Required for Custome dateType)
tender	string	Batch tender type. Values: Card, Cash, Check, ACH
minAmount	int32	Amount filter
maxAmount	int32	Amount filter
limit	int32	How many records to return
offset	int32	Which record to start on
batchId	int32	Batch Id

Card Account Object

Variable	Type	Description
number	string	Card Number
expiryMonth	string	Card Expiration Month
ExpiryYear	string	Card Expiration Year
token	string	Vaulted Payment Token
avsStreet	String	Billing Street Address (required if Loss Prevention Setting is turned on)
avsZip	string	Billing Postal Code (required if Loss Prevention Setting is turned on)
cvv	string	3 or 4 digit card verification value (CVV) (required if Loss Prevention Setting is turned on)
expiryDate	string	Card Expiration Date
magstrip	string	Magnetic Stripe Data
alias	string	Clint Provided, easy to remember name for the card
emvData	string	Byte array converted to string - ICC, ship data for EMV transactions
emvDataKsn	string	KSN for encrypted emv data
track1	string	Track 1 data - base64
track2	string	Track 2 data - based 64 encrypted value or plaintext
track1Ksn	string	KSN for encrypted track 1 data
track2Ksn	string	KSN for encrypted track 2 data

Bank Account Object

Variable	Type	Description
accountNumber	string	Account Number
routingNumber	string	Routing Number
type	string	Account Type. Values: Checkings, Savings
name	string	Account holder's name
alias	string	Alias or common name used to refer to this account
isDefault	boolean	is this the default account
checkNumber	string	the check's number
individualId	string	Sets the ACH individual id(Customer Number)
token	string	Tokenized reference used to replay secure bankAccount information

Customer Object

Variable	Type	Description
id	string	Customer to assoicate the payment with
firstName	string	Customer First Name (Creates customer)
lastName	string	Customer Last Name (Creates customer)
type	string	Values: Person, business

posData Object

Variable	Type	Description
cardholderPesence	string	Is cardholder present at the time of payment? Values: Unknown, Present, NotPresent, Mail, Phone, Standing, Recurring, Ecom
cardPresent	boolean	indicates if the card is present at time of the payment
deviceAttenddance	string	How is the terminal attended. Values: Unknown, Attended, Attended, HomePc, VoiceAru, Recurring
deviceInputCapability	string	Values: Unknown, VoiceAru, Swipe, ContactlessChip, ContactlessSwipe, ChipSwipe, KeyedOnly, SwipeKeyed, ChipSwipeKeyed, Chip
deviceLocation	string	Where is terminal located? Values: Unknown, OnPremise, RemoteMerchant, HomePcDevice, VoiceAru, OnPremiseHomePcDevice, Recurring
panCaptureMethod	string	Method of PAN entry. Values: Unknown, Manual, Swipe, Chip, ContactlessSwipe, ContactlessChip, Fallback, ContactlessMobile
partialApprovalSupport	string	Does POS support partial approvals? (Discover only) Values: NotSupported, Supported, MerchandiseOnly, CashOnly, Exclusive
PinCaptureCapability	string	PIN capture capability of device. For Terminals the pinCaptureCapability value should be sent with the maximum amount of digits the terminal supports for pin entry. (Values: Unknown, Capable, Incapable, Inoperative, Offline, Four, Five, Six, Seven, Eight, Nine, Ten, Eleven, Twelve)

Customer API

Variable	Type	Description
merchantId	string	The identification number of the merchant's account in the MX Merchant system.
limit	int32	Number of records to return
ascending	boolean	sort ascending or descending
filter	string	Search fields; can search on name, customer number, email, city, state or zip
spendProfile	string	Search customers by spend profile
sortField	string	Field to sort by
lastActivity	string	Filter results to time customer as last active. Values: lifetime, Month, Week, Yesterday, Today, Last30, Last7, Custom
startDate	date	Start date for time filter
endDate	date	End date for time filter
echo	boolean	Return results
name	string	Customer's full name(display name)
firstName	string	Customer's first name
lastName	string	Customer's last name
address1	string	street address
address2	string	Apartment, suite, department
city	string	City
state	string	State
zip	string	Zip code
addressName	string	Name for address, i.e. home, work
customerType	string	Type of customer: Business or Person
email	string	Customer's email address
mobile	string	Customer's cell phone number
phone	string	Customer's phone number
number	client	provided customer number
isTaxExempt	boolean	Is this customer tax exempt?
taxId	string	Customer's SSN or EIN(9 digits) required for tax exempt customers)
spendProfile	string	Customer's spend profie
activeStatus	boolean	is the customer active?
SelectedSpendProfile	string	Spend profile selected for customer
spendProfileOverride	boolean	if the spend profile was selected or sent manually, this would be true.
customerId	int32	Id of customer
Id	int32	Id of customer
country	string	Country
isDefault	boolean	is this the default address
subId	int32	Id of address
echo	boolean	Return results(otherwise, you will just see an HTTP response code
code	string	Account Code(default is card
number	string	Card Number
magstripe	string	Magstripe data; you would send in this field instead of number and expiry fields
expiryMonth	string	Magstripe data; you would send in this field instead of numbe and expiry fields
expiryYear	string	Card expiration year
avsZip	string	Billing zip code
avsStreet	string	Billing street address
cvv	string	Card verification value
name	string	Cardholder's name
alias	string	Add an additional identifier to your customerCardAccount object
token	string	A string generated when you vault a card
(Vault Card Account) id	int32	vaulted card id
accountNumber	string	Bank account number
routingNumber	string	Routing Number
(Vaulted Bank Account) name	string	Customer Name
type	string	Account Typer(Either Checking or Savings)
(Vaulted Bank Account) code	string	Account code(default is bank)
addressId	int32	Assoicate a billing address with the account you can then us the token returned to make payments
(Update Vault Account) id	int32	Vault id
image	file	Base64 endcoded image(must be larger than 120 x 120 pixel
text	string	256 char string
offset	int32	offset int32
(custom fields for customer) id	string	Id for the custom field(Auto-generated by server)
(custom fields for customer) name	string	Descriptor name for the custom field
fieldName	string	Name for the custom field object
fieldDataType	string	Type of field. Values: Boolean, String, Integer, Decimal, or List
fieldSourceType	string	Always customer
isDeleted	boolean	True/False
isSystem	boolean	True/False

CustomFields Object

Variable	Type	Description
fieldDataType	string	Field Data Type of your custom Field. Values: String, Integer, Boolean, Decimal, or List
fieldDefinitionId	int32	Id of field
isRequired	boolean	Is this field Required
name	string	FieldName

Options Object

Variable	Type	Description
name	string	Name of Option
Value	stirng	Same as Name

Report API

Variable	Type	Description
merchantId	int32	The identification number of the merchant's account in the MX Merchant system.
startDate	date	start date in MM/DD/YYYY format
endDate	date	End date in MM/DD/YYYY format
limit	int32	Limit of the data
offset	int32	Offset of the data
groupBy	string	Options to Group results by. Values: merchantcubedate, batch
batchId	int32	Batchid
dateTypeFilter	string	Date type filter. Values: Today, Yesterday, Week, Month, Last7, Last30, Custom
dateRange	string	Date Type filer. Values: Lifetime, Month, nextMonth, Custome
expiredOnly	boolean	Reutn only expired Cards?
transactionType	string	Transaction type. Values: Any, Sale, Refund, Authorization
status	string	Transaction status. Values: Any, Approved, Voided, Declined
minAMount	int32	Minimum transaction amonut to return
maxAmount	int32	Maximum transaction amount to return
statementDate	date	Statementdate in MM/DD/YYYY format
errors	boolean	Show only errors or successes
method	string	Filter by Status. Values: 200, 201. 204, 400, 401, 404, 405, 500

Token API

Variable	Type	Description
merchantId	int32	The identification number of the merchant's account in the MX Merchant system.
token	string	limited use token
firstName	string	Customer first name
lastName	string	Customer last name
customerId	int32	Customer id
number	string	Card number
expiryMonth	string	Card expiration month
expiryYear	string	Card expiration year
avsZip	string	Billing zip code
avsStreet	string	Billing street address
cvv	string	Card verfication value
echo	boolean	Return result
tenderType	string	Tender type. Values: Card, Cash, Check, ACH(if enabled);
amount	float	Amount

Card Account Object

Variable	Type	Description
number	string	Card Number
expiryMonth	string	Card Expiration Month
ExpiryYear	string	Card Expiration Year
token	string	Vaultd Payment Token
avsStreet	String	Billing Street Address (required if Loss Prevention Setting is turned on)
avsZip	string	Billing Postal Code (required if Loss Prevention Setting is turned on)
cvv	string	3 or 4 digit card verification value (CVV) (required if Loss Prevention Setting is turned on)
expiryDate	string	Card Expiration Date
magstrip	string	Magnetic Stripe Data
alias	string	Clint Provided, easy to remember name for the card
emvData	string	Byte array converted to string - ICC, ship data for EMV transactions
emvDataKsn	string	KSN for encrypted emv data
track1	string	Track 1 data - base64
track2	string	Track 2 data - based 64 encrypted value or plaintext
track1Ksn	string	KSN for encrypted track 1 data
track2Ksn	string	KSN for encrypted track 2 data

Recurring Payments API

Variable	Type	Description
echo	boolean	Return response? values: True or False
contractId	int	Contract's Id
subscriptionId	String	Subscription's Id
acount.token	string	Token for vaulted card
subscription.customerId	int32	customer id
subscription.cardAccountid	int32	VaultedCard for auto-pay
subscription.allowPartialPayment	boolean	Allow partial payments?
subscription.status	string	Subscription status
subscription.sendReceipt	string	Send recepeit? Always, Never, Once
subScription.eftAgreementRequested	boolean	Request customer agreement
subscription.startDate	date	Subscription stat date
purchases	Array of objects	Purchases array
purchases[0].productName	string	Product name
purchases[0].description	string	Product description
purchases[0].price	float	Product price
purchases[0].quantity	int32	Qunatity
purchases[0].discountAmount	string	item level discount amount
purchase[0].taxAmount	string	item level tax amount
purchases[0].subTotalAmount	string	item subtotal
purchases[0].priceDiscountAmount	string	Dollar value amount of discount
frequency	int32	How often does this contract run?Ex.1 for every 1 month
interval	string	Which interval does this contract run on? Values: Once, Daily, Weekly, Monthly, Yearly.
weekDay	string	If weekly interval, this sets the day of the week. Values: Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, Saturday.
dayNumber	int32	If monthly interval, this sets the day of the month.
month	string	If yearly interval, this sets the month of the year (Also include dayNumber if you would like to bill on a different day than the first of the month).
dayType	string	If you would like to bill on a floating date (i.e., first Saturday), use this combined with day field below instead of dayNumber. Values: Day, First, Second, Third, Fourth, Last.
day	string	Values: Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, Day, Weekday, Weekend.
totalAmount	float	Total amount of transaction including taxes and discounts
subTotalAmount	string	Total Amount of transactions before taxes and discounts
discountAMount	float	Discount amount
taxAmount	float	Tax Amount
memo	string	Memo field(256 chars)
quantity	string	Number of different products purchases

Account Object

Variable	Type	Description
number	string	Card Number	-
expiryMonth	string	Card Expiration Month	-
ExpiryYear	string	Card Expiration Year	-
token	string	Vaultd Payment Token	-
avsStreet	String	Billing Street Address (required if Loss Prevention Setting is turned on)	-
avsZip	string	Billing Postal Code (required if Loss Prevention Setting is turned on)	-
cvv	string	3 or 4 digit card verification value (CVV) (required if Loss Prevention Setting is turned on)	-
expiryDate	string	Card Expiration Date	-
magstrip	string	Magnetic Stripe Data	-
alias	string	Clint Provided, easy to remember name for the card	-
emvData	string	Byte array converted to string - ICC, ship data for EMV transactions	-
emvDataKsn	string	KSN for encrypted emv data	-
track1	string	Track 1 data - base64	-
track2	string	Track 2 data - based 64 encrypted value or plaintext	-
track1Ksn	string	KSN for encrypted track 1 data	-
track2Ksn	string	KSN for encrypted track 2 data	-

Customer Object

Variable	Type	Description
customer.id	int32	Customer Id
merchantId	int32	The identification number of the merchant's account in the MX Merchant system.

Subscription Object

Variable	Type	Description
customerId	int32	cardAccountId
cardAccountId	int32	cardAccountId
allowPartialPayment	boolean	Allow the customer to make partial payments
status	string	Status of the contract. Values: Active, Pending, Paused, Completed, Completed, Cancelled
sendReceipt	string	Always, Never, Once
eftAgreementRequested	boolean	Send Customer Agreement
occurences	string	Number of Occurrences
startDate	date	Date of start time

Purchases Object

Variable	Type	Description
productName	string	Name of product
price	float	Price of product
quantity	int32	Quantity
discountAmount	string	Amount of discount
taxAmount	string	Amount of tax
subTotalAmount	string	Subtotal
description	string	Description of product

Notification API

Variable	Type	Description
echo	boolean	Response of results
eventType	string	Values: Chargeback, Deposit, PaymentSuccess, PaymentFail, UpcomingSAQExpiration, RefundCreated, NewStatement, BatchClosed, ExpiredCard
merchantId	int32	The identification number of the merchant's account in the MX Merchant system.
sendEmail	boolean	Send email notification
emailAddress	string	Email address to send email notification to
sendSMS	boolean	Send text message notification
phoneNumber	string	Phone number to send SMS notification to
sendWebhook	boolean	Send webhook notification
callbackUrl	string	URL tp send webhook notification to
teshold	int32	Thresholds are required for SAQ expiration and any notification related to dollar amounts
source	string	Comma separated list of sources from which to be notified for payments and refunds. This can be QuickPay, invoice, Recurrnig, Order, MXExpress, MXRetail, API, and/or link2Pay.
limit	int32	How many records to return
offset	int32	which record to start with
search	string	6 or 10 digit BIN you wish to search

Terminal API

Variable	Type	Description
merchatId	string	the identification number of the merchant's account in the MX Merchant system
providerKey	string	A lower-case string without spaces that identifies the provicer that issued the terminal
description	string	description of terminal
defaultModel	string	Default Model
enabled	boolean	Enables the terminal
externalId	string	The identification number from the external source for the terminal/dive
externalSource	string	The name identifying from where the externalId originated
forceOnline	boolean	Forces the device online
name	string	Name of the terminal
id	string	id of the terminal
isPercentage	boolean	is their a percentage on the terminal
status	string	status of the terminal
timeoutSeconds	float	how long the terminal will time out
terminalId	string	The identficiation number from the MX Merchant system for the terminal/device
status	string	The enabled status of the terminal in the MX Merchant system
freeTextSearch	string	This is free text search field, which will search by terminal name of description
limit	float	Number of records to return at a time
offset	float	Offset is the position in the dataset of a particicular record. By specifying offset, you retrieve a subset of records starting with the offset value.
amount	float	the payment amount. Must not be 0.
type	string	Type of transaction Values: Sale, Refund, CashAdvance, Prepaid, Adjustment, Void, Reversal, Authorization, SaleCompletion, PaymentTransaction, Withdrawal, Balance
replayId	int32	A merchant-supplied identifier to uniquely identify a payment request to facilitate retries due to I/O related issues. This identifier must be unique. If supplied, we will check for a payment that matches this identifier. If found will return an identical response of the original request. Represents a bigInt value.
vaultCard	boolean	Use this param to vault a new card to a new or existing customer. Send in customer.id to vault to an existing customer, and at a minimum, customer.firstName or customer.lastName to vault the card to a new customer.
reference	string	The reference number from the MX Merchant transaction
transactionId	string	The identification number form the MX Merchant system for the transaction

Currency Object

Variable	Type	Description
allowDynamic	boolean	Allow dynamic currency
default	string	default currency
options	string	other options of currecy

EntryModes Object

Variable	Type	Description
swipe	boolean	Swipe entry
Insert	boolean	Insert entry
tap	boolean	Tap entry
pinpad	boolean	pinpad entry

Key Object

Variable	Type	Description
Activation	string	Activation code
Secret	string	Secret code

paymenMethods Object

Variable	Type	Description
credit	boolean	allow credit payment method
debit	boolean	allow debit payment method

Tip Object

Variable	Type	Description
allow	boolean	allow tips
allowCustom	boolean	allow custom tips
value	float	rate value of tip
isPercentage	boolean	allow rates

POS Entry Mode Codes

Discover

Code	Description
0	Unknown
1	Manual (key entered)
2	Magnetic stripe
3	Bar code
4	Optical character reader
5	Integrated circuit reader
7	Electronic commerce
8	Card present, magstripe defective and cannot be read
10	Credential on File
81	Radio frequency identification indicator
82	Mobile commerce (mCommerce)
90	Voice authorization
91	Voice response unit (VRU)
92	Batch authorization
93	Batch authorization cash access
94	Biometrics

MasterCard

Code	Description
0	Terminal not used
1	Key entry
2	Magnetic strip read (general or track 2)
3	Bar code read (Visa only)
4	OCR read
5	Chip card read-data reliable
6	Track 1 read
7	Proximity payment originating using VSDC chip data rules
10	Credential on File
79	Chip card—unable to read chip or magnetic stripe; manual
80	Chip card—fallback to magnetic stripe 3
81	PAN entry via electronic commerce, including chip
90	Entire content of magnetic stripe was transmitted in authorization request (CVV)
91	Proximity payment originating using magnetic strip data rules
95	Initiated by chip card: CVV data may be unreliable

Visa

Code	Description
0	Terminal not used
1	Key entry
2	Magnetic strip read (general or track 2)
3	Bar code read (Visa only)
4	OCR read
5	Chip card read-data reliable
6	Track 1 read
7	Proximity payment originating using VSDC chip data rules
10	Credential on File
90	Entire content of magnetic stripe was transmitted in authorization request (CVV)
91	Proximity payment originating using magnetic strip data rules
92	Initiated by chip card: CVV data may be unreliable

American Express

Code	Description
0	Unknown
1	Manual, no terminal
2	Magnetic stripe read
3	Optical Code (Bar code, QR code)
4	Optical Character Recognition (OCR)
5	"Integrated Circuit Card (ICC) Note: American Express-certified EMV terminal and link"
6	Key entered
A	Credential on File
S	"Manually entered or keyed transaction with keyed CID/4DBC/4CSC. Data Field 53, Security Related Control Information must be present."
W	"Swiped transaction with keyed CID/4DBC/4CSC. Data Field 53, Security Related Control Information must be present."