---
title: "Make a Payment with Surcharge"
method: POST
path: "/payment"
---

# Make a Payment with Surcharge

`POST /payment`

## Query parameters

- `echo` boolean
- `includeCustomerMatches` boolean

## Request body

- object
  - `merchantId` string, required — Id of the merchant
  - `amount` number, float, required — The payment amount. Must not be 0.
  - `paymentType` string — Type of transaction Values: Sale, Refund, CashAdvance, Prepaid, Adjustment, Void, Reversal, Authorization, SaleCompletion, PaymentTransaction, Withdrawal, Balance
  - `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?
  - `tenderType` string — Values: Card, Check, Cash, Multiple, Loyalty, ACH
  - `cardPresent` boolean — Is the credit card is present at the time of payment?
  - `cardAccount` object — Card Account Object (Required if tenderType is Card)
    - `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)
    - `magstripe` string — Magnetic Stripe Data
    - `alias` string — Client provided, easy to remember name for the card
    - `emvData` string — Byte array converted to string - ICC, chip data for EMV transactions
    - `emvDataKsn` string — KSN for encrypted EMV data
    - `track1` string — Track 1 data - base64 encrypted value or plaintext
    - `track2` string — Track 2 data - base64 encrypted value or plaintext
    - `track1Ksn` string — KSN for encrypted track 1 data
    - `track2Ksn` string — KSN for encrypted track 2 data
  - `bankAccount` object — Bank Account Object (Required if tenderType is Check or ACH)
    - `accountNumber` string — Account Number
    - `routingNumber` string — Routing Number
    - `type` string — Account Type. Values: Checking, Savings
    - `name` string — Account holder's name
    - `alias` string — Alias or common name used to refer to this account
    - `isDefault` string — Is this the default account
    - `checkNumber` string
    - `individualId` string
    - `token` string
  - `entryClass` string — Gets or sets the ACH entry class Values: CCD, PPD, TEL, WEB
  - `isSettleFunds` boolean — Should this transaction be settled?
  - `customer` object — Associate the payment to an existing customer in your customer database.
    - `id` string — Customer to associate the payment with
    - `firstName` string — Customer First Name (Creates customer)
    - `lastName` string — Customer Last Name (Creates customer)
    - `type` string — Values: Person, Business
  - `customerName` string — Customer Name (256 char) (Does NOT associate payment to customer)
  - `customerCode` string — Client provided customer reference number (Associates with Customer Number). *Cannot be combined with invoiceId and clientReference if B2B is on*
  - `meta` string — Memo field
  - `replayId` integer — 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, QuickPay, Recurring, Link2Pay, Terminal
  - `clientReference` string — Client provided payment reference number; can be associated with multiple payments (17 char max)
  - `invoice` string — Client provided invoice number (Generated by server if not provided,16 char max)
  - `invoiceIds` string[] — If there are multiple invoices, you can send in an array of existing invoice ids (Note: they must already exist in MX Merchant)
  - `orderIds` string[] — If there are multiple orders, you can send in an array of existing order ids (Note: they must already exist in MX Merchant)
  - `tax` number, float — Tax Amount (included in amount)
  - `taxExempt` boolean — If true, tax amount must be 0
  - `cardPresentType` string — Values: CardPresentKeyed, CardPresentSwiped, CardNotPresent
  - `posData` object — 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>
  - `device` string — Gets/Sets the device identifier, this is the terminal id.
  - `purchases` unknown[] — Gets/Sets the list of purchases. Used by level 3 data during settlement
    - unknown
  - `shipAmount` number, 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, used by level 3 data during settlement
  - `shouldVaultCard` 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.
  - `tip` number, float — Gets/Sets the amount of the gratuity (included in amount).
  - `vatAmount` number, float — Gets/Sets the vat amount, used by level 3 data during settlement
  - `vatRate` number, float — Gets/Sets the VAT rate, used by level 3 data during settlement
  - `tags` string[] — Associate a tag with the payment (You must set up the tag first in MX Merchant)
  - `surchargeAmount` string — Dollar amount for the surcharge.
  - `surchargeLabel` string — Labels for the surcharge: surcharge, convenience fee, non-cash adjustment
  - `surchargeRate` string — Rate for surcharge on the merchant account.
  - `mxAdvantageEnabled` boolean — If true, MX Advantage is enabled.
  - `mxAdvantageFeeLabel` string — Label for surcharge.
  - `mxAdvantageFeeType` string — Type of surcharge.
  - `mxAdvantageFeeAmount` string — The amount of the MX Advantage surcharge.

## Response `201`

201

- object
  - `created` string
  - `paymentToken` string
  - `id` integer
  - `creatorName` string
  - `isDuplicate` boolean
  - `shouldVaultCard` boolean
  - `merchantId` integer
  - `batch` string
  - `batchId` integer
  - `tenderType` string
  - `currency` string
  - `amount` string
  - `cardAccount` object
    - `cardType` string
    - `entryMode` string
    - `last4` string
    - `cardId` string
    - `token` string
    - `expiryMonth` string
    - `expiryYear` string
    - `hasContract` boolean
    - `cardPresent` boolean
    - `isDebit` boolean
    - `isCorp` boolean
  - `posData` object
    - `panCaptureMethod` string
  - `authOnly` boolean
  - `authCode` string
  - `status` string
  - `risk` object
    - `cvvResponseCode` string
    - `cvvResponse` string
    - `cvvMatch` boolean
    - `avsResponse` string
    - `avsAddressMatch` boolean
    - `avsZipMatch` boolean
  - `requireSignature` boolean
  - `settledAmount` string
  - `settledCurrency` string
  - `cardPresent` boolean
  - `authMessage` string
  - `availableAuthAmount` string
  - `reference` string
  - `surchargeAmount` string
  - `surchargeRate` string
  - `surchargeLabel` string
  - `type` string
  - `taxExempt` boolean
  - `reviewIndicator` integer
  - `source` string

## Other responses

- `400` — 400

---

[API](https://skmtc.net/mxmerchant/apis/checkout-api.md) · [All operations](https://skmtc.net/mxmerchant/apis/checkout-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/mxmerchant/checkout-api/versions/6807b698abcb/schema)