Merchant API

VariableTypeDescription
LimitInt32How many results to return
offsetint32Which record to start on
merchantIdstringThe identification number of the merchant's account in the MX Merchant system.
activebooleanis this user active
saleLimitfloathighest payment amount this user can make
refundLimitfloatHighest refund amount this user can make
Photoobjectbase64 encoded profile picture
rolestringwhat role does this user need? Values: Administrator, Supervisor, Read Only, clerk
usernamestringUsername of the new user
firstNamestringUser's first name
lastNamestringUser's last name
emailstringUser's email address
mobilestringUser's phone number
passwordstringUser's new or temporary password
roleIdint32Account role of API key; Default(Supervisor) is 2
namestringName of Key
descriptionstringDescription of Key
LockedbooleanIs this key locked or active
pageSizeint32Number of records to return

Lost Provention Object

VariableTypeDescription
KeyedAvsAddressbooleanRequire Street Address when doing keyed trnsactions
KeyedAvsZipbooleanRequire Postal Code when doing keyed transactions
KeyedCvvbooleanRequire CVV when doing keyed transactions
swipeAvsAddressbooleanRequire Street Address when doing swiped transactions
swipedAvsZipbooleanRequire Postal Code when doing swiped transactions
swipedLastFourDigitsbooleanRequire Last 4 Digits when doing swiped transactions
checkPhoneNumberbooleanRequire Phone Number when doing check transactions
checkNumberbooleanRequire Check Number when doing check transactions
declineOnCvvMismatchbooleanAuto-decline on CVV mismatch
declineOnAvsZipMismatchbooleanAuto-decline on Postal Code mismatch
declineOnAvsStreetMismatchbooleanAuto-decline on Street Address mismatch
enableEmsbooleanEnable or Disable EMS Fraud Scoring
EemsPaymentAmountThresholdbooleanOnly trigger EMS checks for payment over this amount
declineOnEmsScoreExceededbooleanAuto-decline if EMS score threshold is exceeded
declineEmsScoreThresholdboleanEMS Score threshold

Time Restriction Object

VariableTypeDescription
sundaybooleandate
mondaybooleandate
tuesdaybooleandate
wednesdaybooleandate
thursdaybooleandate
fridaybooleandate
saturdaybooleandate
startTimeMinuteStringdate
endTimeMinuteStringdate

Merchants Object

VariableTypeDescription
IdstringMerchant Id
dbastringMerchant's name
xmidstringXMID of the Merchant

Payment API

VariableTypeDescription
echobooleanReturn Response
includeCustomerMatchesbooleanReturn customers that have this card vaulted in their account
merchantIdstringThe identification number of the merchant's account in the MX Merchant system.
amountfloatthe payment amount. Must not be 0.
paymentTypestringType of transactions Values: Sale, Refund, CashAdvance, Prepaid, Adjustment, Void, Reversal, Authorization, SaleCompletion, PaymentTransaction, Withdrawal, Balance
tenderTypestringValues: Card, Check, Cash, Mutiple, Loyalty, ACH
entryClassstringGets or sets the ACH entry class Values: CCD, PPD, TEL, WEB
cardPresentbooleanIs the credit card is present at the time of payment?
authOnlybooleanIndicates that this payment should NOT be added to current batch. AuthOnly payment won't be settled.
isAuthbooleanShould this card be authorized?
isSettleFundsbooleanshould this transaction be settled?
customerNamestringCustomer Name(256 char)(Does Not assoicate payment to customer)
customerCodestringClient provided customer reference number(assoicated with Customer Number). Cannot be combined with invoideId and clientReference if B2b is On
metastringMemo Field
replayIdint32A 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.
sourcestringValues: API, Quick Pay, Recurring, Link2Pay, Terminal
clientReferencestringClient provided payment reference number; can be assoicated with multiple payments (17 char max)
invoicestringClient provided invoice number(Generated by servver if not provided, 16 char max)
invoiceIdsarray of stringsIf there are multiple invoices, you can send in an array of existing invoice ids (Note: they must already exist in MX Merchant)
orderIdsarray of stringsIf there are multiple orders, you can send in an array of existing order ids (Note: they must already exist in MX Merchant)
taxfloatTax Amount(included in amount)
taxExemptbooleanif true, tax amount must be 0
cardPresentTypestringvalues:CardPresentKeyed, CardPresentSwiped, CardNotPresent
devicestringGets/Sets the device identifier, this is the terminal id
shipAmountfloatGets/Sets the ship amount, used by level 3 data during settlement
shipToCountrystringGets/Sets the 3-digit alphanumeric ship-to country code, i. e. USA, used by level 3 data during settlement
shipToZipstringGets/Sets the ship-to zip code, using by level 3 data during settlement
shouldVaultCardbooleanUse 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.
tipfloatGets/Sets the amount of the gratuity (included in amount).
vatAmountfloatGets/Sets the vat amount, used by level 3 data during settlement
vatRatefloatGets/Sets the VAT rate, used by level 3 data during settlement
transactionTypestringValues: Any, Sale, Refund, Authorization
tenderTypestringValues: Any, Card, Cash, Check, Ach
statusstringValues: Any, Approved, Voided, Declined
dateTypestringValues: Any, Today, Yesterday, WeekToDate, MonthToDate, Last7, Last30, Custom
startDatestringYYYY-MM-DDthh:mm:ssZ(Required for Custom dataType)
endDatestringYYYY-MM-DDThh:mm:ssZ(Required for Custom dataType)
sourcestringValues: Any, quickPay, link2Pay, Recurring, Order, mxExpress, mxRetail, API, BIP, terminal
limitint32Number of records to return
idint32Specific paymentId to return a single payment
includeCustomerbooleanReturns the customer object associcated with the payment
paymentIdstringThe id of the payment
forcebooleanForce a refund if transaction has already settled
startTimestringYYYY-MM-DDThh:mm:ssZ(Required for Custom dateType)
endTimestringYYYY-MM-DDThh:mm:ssZ(Required for Custome dateType)
tenderstringBatch tender type. Values: Card, Cash, Check, ACH
minAmountint32Amount filter
maxAmountint32Amount filter
limitint32How many records to return
offsetint32Which record to start on
batchIdint32Batch Id

Card Account Object

VariableTypeDescription
numberstringCard Number
expiryMonthstringCard Expiration Month
ExpiryYearstringCard Expiration Year
tokenstringVaulted Payment Token
avsStreetStringBilling Street Address (required if Loss Prevention Setting is turned on)
avsZipstringBilling Postal Code (required if Loss Prevention Setting is turned on)
cvvstring3 or 4 digit card verification value (CVV) (required if Loss Prevention Setting is turned on)
expiryDatestringCard Expiration Date
magstripstringMagnetic Stripe Data
aliasstringClint Provided, easy to remember name for the card
emvDatastringByte array converted to string - ICC, ship data for EMV transactions
emvDataKsnstringKSN for encrypted emv data
track1stringTrack 1 data - base64
track2stringTrack 2 data - based 64 encrypted value or plaintext
track1KsnstringKSN for encrypted track 1 data
track2KsnstringKSN for encrypted track 2 data

Bank Account Object

VariableTypeDescription
accountNumberstringAccount Number
routingNumberstringRouting Number
typestringAccount Type. Values: Checkings, Savings
namestringAccount holder's name
aliasstringAlias or common name used to refer to this account
isDefaultbooleanis this the default account
checkNumberstringthe check's number
individualIdstringSets the ACH individual id(Customer Number)
tokenstringTokenized reference used to replay secure bankAccount information

Customer Object

VariableTypeDescription
idstringCustomer to assoicate the payment with
firstNamestringCustomer First Name (Creates customer)
lastNamestringCustomer Last Name (Creates customer)
typestringValues: Person, business

posData Object

VariableTypeDescription
cardholderPesencestringIs cardholder present at the time of payment? Values: Unknown, Present, NotPresent, Mail, Phone, Standing, Recurring, Ecom
cardPresentbooleanindicates if the card is present at time of the payment
deviceAttenddancestringHow is the terminal attended. Values: Unknown, Attended, Attended, HomePc, VoiceAru, Recurring
deviceInputCapabilitystringValues: Unknown, VoiceAru, Swipe, ContactlessChip, ContactlessSwipe, ChipSwipe, KeyedOnly, SwipeKeyed, ChipSwipeKeyed, Chip
deviceLocationstringWhere is terminal located? Values: Unknown, OnPremise, RemoteMerchant, HomePcDevice, VoiceAru, OnPremiseHomePcDevice, Recurring
panCaptureMethodstringMethod of PAN entry. Values: Unknown, Manual, Swipe, Chip, ContactlessSwipe, ContactlessChip, Fallback, ContactlessMobile
partialApprovalSupportstringDoes POS support partial approvals? (Discover only) Values: NotSupported, Supported, MerchandiseOnly, CashOnly, Exclusive
PinCaptureCapabilitystringPIN 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

VariableTypeDescription
merchantIdstringThe identification number of the merchant's account in the MX Merchant system.
limitint32Number of records to return
ascendingbooleansort ascending or descending
filterstringSearch fields; can search on name, customer number, email, city, state or zip
spendProfilestringSearch customers by spend profile
sortFieldstringField to sort by
lastActivitystringFilter results to time customer as last active. Values: lifetime, Month, Week, Yesterday, Today, Last30, Last7, Custom
startDatedateStart date for time filter
endDatedateEnd date for time filter
echobooleanReturn results
namestringCustomer's full name(display name)
firstNamestringCustomer's first name
lastNamestringCustomer's last name
address1stringstreet address
address2stringApartment, suite, department
citystringCity
statestringState
zipstringZip code
addressNamestringName for address, i.e. home, work
customerTypestringType of customer: Business or Person
emailstringCustomer's email address
mobilestringCustomer's cell phone number
phonestringCustomer's phone number
numberclientprovided customer number
isTaxExemptbooleanIs this customer tax exempt?
taxIdstringCustomer's SSN or EIN(9 digits) required for tax exempt customers)
spendProfilestringCustomer's spend profie
activeStatusbooleanis the customer active?
SelectedSpendProfilestringSpend profile selected for customer
spendProfileOverridebooleanif the spend profile was selected or sent manually, this would be true.
customerIdint32Id of customer
Idint32Id of customer
countrystringCountry
isDefaultbooleanis this the default address
subIdint32Id of address
echobooleanReturn results(otherwise, you will just see an HTTP response code
codestringAccount Code(default is card
numberstringCard Number
magstripestringMagstripe data; you would send in this field instead of number and expiry fields
expiryMonthstringMagstripe data; you would send in this field instead of numbe and expiry fields
expiryYearstringCard expiration year
avsZipstringBilling zip code
avsStreetstringBilling street address
cvvstringCard verification value
namestringCardholder's name
aliasstringAdd an additional identifier to your customerCardAccount object
tokenstringA string generated when you vault a card
(Vault Card Account) idint32vaulted card id
accountNumberstringBank account number
routingNumberstringRouting Number
(Vaulted Bank Account) namestringCustomer Name
typestringAccount Typer(Either Checking or Savings)
(Vaulted Bank Account) codestringAccount code(default is bank)
addressIdint32Assoicate a billing address with the account you can then us the token returned to make payments
(Update Vault Account) idint32Vault id
imagefileBase64 endcoded image(must be larger than 120 x 120 pixel
textstring256 char string
offsetint32offset int32
(custom fields for customer) idstringId for the custom field(Auto-generated by server)
(custom fields for customer) namestringDescriptor name for the custom field
fieldNamestringName for the custom field object
fieldDataTypestringType of field. Values: Boolean, String, Integer, Decimal, or List
fieldSourceTypestringAlways customer
isDeletedbooleanTrue/False
isSystembooleanTrue/False

CustomFields Object

VariableTypeDescription
fieldDataTypestringField Data Type of your custom Field. Values: String, Integer, Boolean, Decimal, or List
fieldDefinitionIdint32Id of field
isRequiredbooleanIs this field Required
namestringFieldName

Options Object

VariableTypeDescription
namestringName of Option
ValuestirngSame as Name

Report API

VariableTypeDescription
merchantIdint32The identification number of the merchant's account in the MX Merchant system.
startDatedatestart date in MM/DD/YYYY format
endDatedateEnd date in MM/DD/YYYY format
limitint32Limit of the data
offsetint32Offset of the data
groupBystringOptions to Group results by. Values: merchantcubedate, batch
batchIdint32Batchid
dateTypeFilterstringDate type filter. Values: Today, Yesterday, Week, Month, Last7, Last30, Custom
dateRangestringDate Type filer. Values: Lifetime, Month, nextMonth, Custome
expiredOnlybooleanReutn only expired Cards?
transactionTypestringTransaction type. Values: Any, Sale, Refund, Authorization
statusstringTransaction status. Values: Any, Approved, Voided, Declined
minAMountint32Minimum transaction amonut to return
maxAmountint32Maximum transaction amount to return
statementDatedateStatementdate in MM/DD/YYYY format
errorsbooleanShow only errors or successes
methodstringFilter by Status. Values: 200, 201. 204, 400, 401, 404, 405, 500

Token API

VariableTypeDescription
merchantIdint32The identification number of the merchant's account in the MX Merchant system.
tokenstringlimited use token
firstNamestringCustomer first name
lastNamestringCustomer last name
customerIdint32Customer id
numberstringCard number
expiryMonthstringCard expiration month
expiryYearstringCard expiration year
avsZipstringBilling zip code
avsStreetstringBilling street address
cvvstringCard verfication value
echobooleanReturn result
tenderTypestringTender type. Values: Card, Cash, Check, ACH(if enabled);
amountfloatAmount

Card Account Object

VariableTypeDescription
numberstringCard Number
expiryMonthstringCard Expiration Month
ExpiryYearstringCard Expiration Year
tokenstringVaultd Payment Token
avsStreetStringBilling Street Address (required if Loss Prevention Setting is turned on)
avsZipstringBilling Postal Code (required if Loss Prevention Setting is turned on)
cvvstring3 or 4 digit card verification value (CVV) (required if Loss Prevention Setting is turned on)
expiryDatestringCard Expiration Date
magstripstringMagnetic Stripe Data
aliasstringClint Provided, easy to remember name for the card
emvDatastringByte array converted to string - ICC, ship data for EMV transactions
emvDataKsnstringKSN for encrypted emv data
track1stringTrack 1 data - base64
track2stringTrack 2 data - based 64 encrypted value or plaintext
track1KsnstringKSN for encrypted track 1 data
track2KsnstringKSN for encrypted track 2 data

Recurring Payments API

VariableTypeDescription
echobooleanReturn response? values: True or False
contractIdintContract's Id
subscriptionIdStringSubscription's Id
acount.tokenstringToken for vaulted card
subscription.customerIdint32customer id
subscription.cardAccountidint32VaultedCard for auto-pay
subscription.allowPartialPaymentbooleanAllow partial payments?
subscription.statusstringSubscription status
subscription.sendReceiptstringSend recepeit? Always, Never, Once
subScription.eftAgreementRequestedbooleanRequest customer agreement
subscription.startDatedateSubscription stat date
purchasesArray of objectsPurchases array
purchases[0].productNamestringProduct name
purchases[0].descriptionstringProduct description
purchases[0].pricefloatProduct price
purchases[0].quantityint32Qunatity
purchases[0].discountAmountstringitem level discount amount
purchase[0].taxAmountstringitem level tax amount
purchases[0].subTotalAmountstringitem subtotal
purchases[0].priceDiscountAmountstringDollar value amount of discount
frequencyint32How often does this contract run?Ex.1 for every 1 month
intervalstringWhich interval does this contract run on? Values: Once, Daily, Weekly, Monthly, Yearly.
weekDaystringIf weekly interval, this sets the day of the week. Values: Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, Saturday.
dayNumberint32If monthly interval, this sets the day of the month.
monthstringIf 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).
dayTypestringIf 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.
daystringValues: Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, Day, Weekday, Weekend.
totalAmountfloatTotal amount of transaction including taxes and discounts
subTotalAmountstringTotal Amount of transactions before taxes and discounts
discountAMountfloatDiscount amount
taxAmountfloatTax Amount
memostringMemo field(256 chars)
quantitystringNumber of different products purchases

Account Object

VariableTypeDescription
numberstringCard Number
expiryMonthstringCard Expiration Month
ExpiryYearstringCard Expiration Year
tokenstringVaultd Payment Token
avsStreetStringBilling Street Address (required if Loss Prevention Setting is turned on)
avsZipstringBilling Postal Code (required if Loss Prevention Setting is turned on)
cvvstring3 or 4 digit card verification value (CVV) (required if Loss Prevention Setting is turned on)
expiryDatestringCard Expiration Date
magstripstringMagnetic Stripe Data
aliasstringClint Provided, easy to remember name for the card
emvDatastringByte array converted to string - ICC, ship data for EMV transactions
emvDataKsnstringKSN for encrypted emv data
track1stringTrack 1 data - base64
track2stringTrack 2 data - based 64 encrypted value or plaintext
track1KsnstringKSN for encrypted track 1 data
track2KsnstringKSN for encrypted track 2 data

Customer Object

VariableTypeDescription
customer.idint32Customer Id
merchantIdint32The identification number of the merchant's account in the MX Merchant system.

Subscription Object

VariableTypeDescription
customerIdint32cardAccountId
cardAccountIdint32cardAccountId
allowPartialPaymentbooleanAllow the customer to make partial payments
statusstringStatus of the contract. Values: Active, Pending, Paused, Completed, Completed, Cancelled
sendReceiptstringAlways, Never, Once
eftAgreementRequestedbooleanSend Customer Agreement
occurencesstringNumber of Occurrences
startDatedateDate of start time

Purchases Object

VariableTypeDescription
productNamestringName of product
pricefloatPrice of product
quantityint32Quantity
discountAmountstringAmount of discount
taxAmountstringAmount of tax
subTotalAmountstringSubtotal
descriptionstringDescription of product

Notification API

VariableTypeDescription
echobooleanResponse of results
eventTypestringValues: Chargeback, Deposit, PaymentSuccess, PaymentFail, UpcomingSAQExpiration, RefundCreated, NewStatement, BatchClosed, ExpiredCard
merchantIdint32The identification number of the merchant's account in the MX Merchant system.
sendEmailbooleanSend email notification
emailAddressstringEmail address to send email notification to
sendSMSbooleanSend text message notification
phoneNumberstringPhone number to send SMS notification to
sendWebhookbooleanSend webhook notification
callbackUrlstringURL tp send webhook notification to
tesholdint32Thresholds are required for SAQ expiration and any notification related to dollar amounts
sourcestringComma 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.
limitint32How many records to return
offsetint32which record to start with
searchstring6 or 10 digit BIN you wish to search

Terminal API

VariableTypeDescription
merchatIdstringthe identification number of the merchant's account in the MX Merchant system
providerKeystringA lower-case string without spaces that identifies the provicer that issued the terminal
descriptionstringdescription of terminal
defaultModelstringDefault Model
enabledbooleanEnables the terminal
externalIdstringThe identification number from the external source for the terminal/dive
externalSourcestringThe name identifying from where the externalId originated
forceOnlinebooleanForces the device online
namestringName of the terminal
idstringid of the terminal
isPercentagebooleanis their a percentage on the terminal
statusstringstatus of the terminal
timeoutSecondsfloathow long the terminal will time out
terminalIdstringThe identficiation number from the MX Merchant system for the terminal/device
statusstringThe enabled status of the terminal in the MX Merchant system
freeTextSearchstringThis is free text search field, which will search by terminal name of description
limitfloatNumber of records to return at a time
offsetfloatOffset is the position in the dataset of a particicular record. By specifying offset, you retrieve a subset of records starting with the offset value.
amountfloatthe payment amount. Must not be 0.
typestringType of transaction Values: Sale, Refund, CashAdvance, Prepaid, Adjustment, Void, Reversal, Authorization, SaleCompletion, PaymentTransaction, Withdrawal, Balance
replayIdint32A 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.
vaultCardbooleanUse 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.
referencestringThe reference number from the MX Merchant transaction
transactionIdstringThe identification number form the MX Merchant system for the transaction

Currency Object

VariableTypeDescription
allowDynamicbooleanAllow dynamic currency
defaultstringdefault currency
optionsstringother options of currecy

EntryModes Object

VariableTypeDescription
swipebooleanSwipe entry
InsertbooleanInsert entry
tapbooleanTap entry
pinpadbooleanpinpad entry

Key Object

VariableTypeDescription
ActivationstringActivation code
SecretstringSecret code

paymenMethods Object

VariableTypeDescription
creditbooleanallow credit payment method
debitbooleanallow debit payment method

Tip Object

VariableTypeDescription
allowbooleanallow tips
allowCustombooleanallow custom tips
valuefloatrate value of tip
isPercentagebooleanallow rates