v1

latestOpenAPI 3.1.02026-07-241660500.9 KB

Make a Payment with Surcharge

post/payment

Query parameters

echoboolean

includeCustomerMatchesboolean

Return customers that have this card vaulted in their account

Request body

merchantIdstring required

Id of the merchant

amountnumber float required

The payment amount. Must not be 0.

paymentTypestring

Type of transaction Values: Sale, Refund, CashAdvance, Prepaid, Adjustment, Void, Reversal, Authorization, SaleCompletion, PaymentTransaction, Withdrawal, Balance

authOnlyboolean

Indicates that this payment should NOT be added to current batch. AuthOnly payment won't be settled.

isAuthboolean

Should this card be authorized?

tenderTypestring

Values: Card, Check, Cash, Multiple, Loyalty, ACH

cardPresentboolean

Is the credit card is present at the time of payment?

entryClassstring

Gets or sets the ACH entry class Values: CCD, PPD, TEL, WEB

isSettleFundsboolean

Should this transaction be settled?

customerNamestring

Customer Name (256 char) (Does NOT associate payment to customer)

customerCodestring

Client provided customer reference number (Associates with Customer Number). Cannot be combined with invoiceId and clientReference if B2B is on

metastring

Memo field

replayIdinteger

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.

sourcestring

Values: API, QuickPay, Recurring, Link2Pay, Terminal

clientReferencestring

Client provided payment reference number; can be associated with multiple payments (17 char max)

invoicestring

Client provided invoice number (Generated by server if not provided,16 char max)

invoiceIdsstring[]

If there are multiple invoices, you can send in an array of existing invoice ids (Note: they must already exist in MX Merchant)

orderIdsstring[]

If there are multiple orders, you can send in an array of existing order ids (Note: they must already exist in MX Merchant)

taxnumber float

Tax Amount (included in amount)

taxExemptboolean

If true, tax amount must be 0

cardPresentTypestring

Values: CardPresentKeyed, CardPresentSwiped, CardNotPresent

posDataobject

POS transaction Data <h4> <em>Although the “posData” object is not a requirement for payment requests, we highly recommend that you use it. The values passed will help the host determine how the transaction will be presented to the authorization networks for approval. This may impact data integrity, chargebacks, and or final qualification for the transaction.</em></h4>

devicestring

Gets/Sets the device identifier, this is the terminal id.

shipAmountnumber float

Gets/Sets the ship amount, used by level 3 data during settlement

shipToCountrystring

Gets/Sets the 3-digit alphanumeric ship-to country code, i.e. USA, used by level 3 data during settlement

shipToZipstring

Gets/Sets the ship-to zip code, used by level 3 data during settlement

shouldVaultCardboolean

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.

tipnumber float

Gets/Sets the amount of the gratuity (included in amount).

vatAmountnumber float

Gets/Sets the vat amount, used by level 3 data during settlement

vatRatenumber float

Gets/Sets the VAT rate, used by level 3 data during settlement

tagsstring[]

Associate a tag with the payment (You must set up the tag first in MX Merchant)

surchargeAmountstring

Dollar amount for the surcharge.

surchargeLabelstring

Labels for the surcharge: surcharge, convenience fee, non-cash adjustment

surchargeRatestring

Rate for surcharge on the merchant account.

mxAdvantageEnabledboolean

If true, MX Advantage is enabled.

mxAdvantageFeeLabelstring

Label for surcharge.

mxAdvantageFeeTypestring

Type of surcharge.

mxAdvantageFeeAmountstring

The amount of the MX Advantage surcharge.

Response

201

createdstring

paymentTokenstring

idinteger

creatorNamestring

isDuplicateboolean

shouldVaultCardboolean

merchantIdinteger

batchstring

batchIdinteger

tenderTypestring

currencystring

amountstring

authOnlyboolean

authCodestring

statusstring

requireSignatureboolean

settledAmountstring

settledCurrencystring

cardPresentboolean

authMessagestring

availableAuthAmountstring

referencestring

surchargeAmountstring

surchargeRatestring

surchargeLabelstring

typestring

taxExemptboolean

reviewIndicatorinteger

sourcestring

Example response

{
  "created": "2020-12-04T16:04:23.127Z",
  "paymentToken": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXbzaQ",
  "id": 10000001505878,
  "creatorName": "Andrew Ferrer",
  "shouldVaultCard": true,
  "merchantId": 1000000000,
  "batch": "0003",
  "batchId": 10000000224661,
  "tenderType": "Card",
  "currency": "USD",
  "amount": "1248.48",
  "cardAccount": {
    "cardType": "Visa",
    "entryMode": "Keyed",
    "last4": "4242",
    "cardId": "XXXXXXXXXXXXXXXXXXXXXXXQMsf",
    "token": "XXXXXXXXXXXXXXXXXXXXXXXbzaQ",
    "expiryMonth": "12",
    "expiryYear": "33"
  },
  "posData": {
    "panCaptureMethod": "Manual"
  },
  "authCode": "PPSa78",
  "status": "Approved",
  "risk": {
    "cvvResponseCode": "M",
    "cvvResponse": "Match",
    "cvvMatch": true,
    "avsResponse": "No Response from AVS"
  },
  "settledAmount": "0",
  "settledCurrency": "USD",
  "authMessage": "Approved or completed successfully. ",
  "availableAuthAmount": "0",
  "reference": "033916000059",
  "surchargeAmount": "36.36",
  "surchargeRate": "0.03",
  "surchargeLabel": "surcharge",
  "type": "Sale",
  "reviewIndicator": 1,
  "source": "QuickPay"
}