Merchant settings define how transactions are processed, validated, and displayed across various merchant operations. These configurations control everything from fraud prevention and payment methods to invoice automation and receipt display.

You can retrieve all settings using the GET /checkout/v3/merchantsetting/{merchantId} endpoint.

This endpoint provides integration-relevant preferences, meaning only settings that directly impact APIs or merchant operations are returned.

Update Merchant Settings

These settings allow merchants to manage how payments are accepted, processed, and settled. By updating these parameters, you can enable new payment types, automate settlement cycles, and optimize transaction handling — all directly through API.

Loss Prevention Settings

These settings define validation and fraud prevention rules for transactions across different payment types (keyed, swiped, or check).

The below Loss Prevention settings can be updated via the POST /checkout/v3/fraudSetting?merchantId={merchantId} endpoint.

API Node	Description
`keyedCvv`	Set to `true` to require the CVV for manually entered card transactions.
`keyedAvsZip`	Set to `true` to require and validate the ZIP/postal code for keyed card transactions.
`keyedAvsAddress`	Set to `true` to require the billing street address for keyed card transactions.
`swipedAvsZip`	Set to `true` to require and validate the ZIP/postal code for swiped transactions.
`swipedAvsAddress`	Set to `true` to require the billing street address for swiped transactions.
`swipedLastFourDigits`	Set to `true` to require the last four digits of the card number for swiped transactions.
`checkPhoneNumber`	Set to `true` to require the customer’s phone number when accepting check payments.
`checkNumber`	Set to `true` to require a check number when processing check payments.
`declineOnCvvMismatch`	Set to `true` to automatically decline transactions when the CVV does not match.
`declineOnAvsZipMismatch`	Set to `true` to automatically decline transactions when the ZIP/postal code does not match.
`declineOnAvsStreetMismatch`	Set to `true` to automatically decline transactions when the street address does not match.
`enableEms`	Set to `true` to enable Enhanced Merchant Screening (EMS) for fraud detection.
`emsPaymentAmountThreshold`	Specify the minimum transaction amount that triggers EMS screening.
`declineEmsScoreThreshold`	Specify the EMS risk score threshold above which a transaction should be declined.

These configurations determine how strictly AVS/CVV validation and EMS fraud screening are enforced.

Payment Settings

Payment settings define which payment methods merchants accept and how transactions behave during processing. They also include advanced options such as B2B optimization, and detecting duplicate transactions.

The B2B Optimizer settings enhance interchange optimization by capturing richer transaction data, particularly for Business-to-Business (B2B) payments.

Merchants using corporate or purchasing cards benefit from lower interchange rates and more detailed reporting when Level II/III data is enabled.

The below settings can be updated via the PUT /checkout/v3/merchantsetting/{merchantId} endpoint.

API Node	Description
`payment.promptForCustomData`	Set to true to enable prompts for advanced or custom data in MX Express.
`payment.includeB2bFields`	Set to true to include Business-to-Business (B2B) fields during transactions.
`payment.enableAchPayments`	Set to true to enable ACH (bank account) payments.
`payment.enableCashPayments`	Set to true to enable cash payments.
`payment.enableCardPayments`	Set to true to enable credit/debit card transactions.
`payment.enableCheckPayments`	Set to true to enable check payments.
`payment.quickPayTransactionType`	Defines the default transaction type for Quick Pay (e.g., “Sale”).
`payment.quickPayTender`	Defines the default tender type for Quick Pay (e.g., Card or Cash).
`payment.quickPayCardPresent`	Specifies whether the card is present (CardPresent / CardNotPresent).
`payment.quickPayEndOfPayment`	Defines the behavior after payment (e.g., CloseQuickPay).
`payment.autoCloseTime`	Defines the auto-close batch time (e.g., “4:00 AM”).
`payment.enableAutoClose`	Set to true to enable automatic batch closing at the configured time.
`payment.terminalAutoCloseTime`	Specifies the terminal-specific auto-close time.
`payment.enableTerminalAutoClose`	Set to true to enable terminal-specific automatic batch closing.
`payment.enableTerminalBatch`	Set to true to enable terminal-based batching.
`payment.enableTip`	Set to true to enable tip entry during transactions.
`payment.achIndicator`	Defines the ACH transaction type (e.g., CCD or PPD).
`payment.enableDuplicateCheck`	Set to true to enable duplicate transaction detection.
`payment.duplicateTimeout`	Defines the time window (e.g., “00:2:0”) to check for duplicate transactions.
`payment.enableVaultCard`	Set to true to enable card vaulting for future transactions.
`payment.enableAuthorize`	Set to true to enable pre-authorization before capture.
`payment.enableTaxExempt`	Set to true to allow transactions to be marked as tax-exempt.
`payment.enableSettleFunds`	Set to true to enable settlement of funds after authorization.
`payment.enableDynamicDescriptor`	Set to true to allow dynamic descriptors on customer statements.
`payment.enabledB2BLineItem`	Set to true to enable B2B line-item entry functionality.
`payment.mxAdvantageEnabled`	Set to true to enable the MX Advantage surcharge program.
`payment.mxAdvantageFeeLabel`	Specifies the label used for surcharge display (e.g., “surcharge”).
`payment.mxAdvantageFees`	Defines surcharge configuration rules (applies only to credit, not debit).
`payment.EnableRekey`	Set to true to allow manual re-entry of card data if needed.
`payment.DaysAllowedForSaleCompletion`	Defines the number of days allowed to complete a sale.
`payment.enableBatchlessTransaction`	Set to true to enable real-time (non-batched) transaction processing.
`payment.mxAdvantageRateCard`	Defines the default surcharge rate (e.g., “0.0225” = 2.25%).

Payment settings help merchants balance operational efficiency and control whether by auto-closing batches, adding surcharges, or supporting multiple tenders.

Invoice Settings

Control how merchants create and manage invoices, enable payment options, and automate reminders.

The below settings can be updated via the PUT /checkout/v3/merchantsetting/{merchantId} endpoint.

API Node	Description
`invoice.enableItems`	Set to true to allow adding products or services to invoices.
`invoice.enableTasks`	Set to true to allow adding tasks (e.g., billable hours) to invoices.
`invoice.enableFulfillment`	Set to true to enable fulfillment/shipping options on invoices.
`invoice.defaultFulfillment`	Defines the default fulfillment setting (e.g., `"0"` = disabled).
`invoice.enableInvoicing`	Set to true to enable invoicing functionality overall.
`invoice.paymentTerms`	Defines invoice payment terms — options: `OnReceipt`, `Net15`, `Net30`, `Net60`, or `Net90`.
`invoice.legalTerms`	Displays legal terms on the invoice (leave blank if not applicable).
`invoice.enableClickToPay`	Set to true to enable Click-to-Pay links for invoice payments.
`invoice.enableAch`	Set to true to allow ACH (bank) payments for invoices.
`invoice.reminderDays`	Defines days before the due date to send a payment reminder.
`invoice.receiptDays`	Defines days after the due date to send a follow-up notification.
`invoice.enableCardPayment`	Set to true to allow card payments on invoices.
`invoice.interval`	Defines the recurrence interval for invoices (e.g., Once, Weekly, Monthly).
`invoice.frequency`	Defines how many times a recurring invoice should repeat.
`invoice.dayNumber`	Defines the day number for recurrence (e.g., `1` = 1st of the month).
`invoice.dayType`	Defines the type of recurrence interval — Day, Week, or Month.
`invoice.day`	Specifies the exact day value, if applicable.
`invoice.requireAuthorization`	Set to true to require customer authorization before invoice payment.
`invoice.sendDeclineEmail`	Set to true to send an email notification when payment is declined.
`invoice.enableReattemptDeclinedPayment`	Set to true to automatically retry declined payments.
`invoice.month`	Defines the specific month for recurring invoices (if applicable).
`invoice.allowMultipleOrderDiscounts`	Set to true to allow multiple discounts per invoice.
`invoice.allowMultipleProductDiscounts`	Set to true to allow multiple discounts per product.
`invoice.InvoiceNumberSeed`	Defines the starting number for auto-generated invoice numbers.
`invoice.InvoiceNumberSeedLocked`	Set to true to lock the invoice number seed from modification.
`invoice.sendEmail`	Set to true to send invoices via email to customers.
`invoice.sendSms`	Set to true to send invoices via SMS/text message.
`invoice.autoGenerate`	Set to true to auto-generate recurring invoices.
`invoice.intervalValue`	Defines the numeric value of the recurrence interval (e.g., `30` = every 30 days).
`invoice.intervalLabel`	Defines the label for the interval (e.g., “Days”, “Weeks”, “Months”).

Receipt Settings

Customize how customer receipts are displayed and what information they include.

The below settings can be updated via the PUT /checkout/v3/merchantsetting/{merchantId} endpoint.

API Node	Description
`receipt.showPhone`	Set to true to display the business phone number on the receipt.
`receipt.showWebsiteUrl`	Set to true to display the business website URL on the receipt.
`receipt.imageDataUrl`	Contains the Base64-encoded data for a custom logo or image shown on the receipt.
`receipt.name`	Displays the business or location name on the receipt.
`receipt.phone`	Defines the business phone number printed on receipts.
`receipt.email`	Defines the business email address used for receipts or customer support.
`receipt.websiteUrl`	Specifies the business website URL, shown if `showWebsiteUrl` is enabled.
`receipt.showHistory`	Set to true to include past transaction history on the receipt.
`receipt.showLoyaltyPoints`	Set to true to display loyalty or rewards points information.
`receipt.showTip`	Set to true to include tip information on the printed or emailed receipt.
`receipt.address.address1`	Defines the business street address (line 1) printed on the receipt.
`receipt.address.city`	Defines the business city displayed on the receipt.
`receipt.address.state`	Defines the business state abbreviation shown on the receipt.
`receipt.address.zip`	Defines the business ZIP or postal code displayed on the receipt.
`receipt.receiptType`	Specifies the receipt style or template (e.g., `"Modern"`).
`receipt.showMasterCardMasterPass`	Set to true to display MasterCard MasterPass branding (legacy feature).
`receipt.showInvoiceMemo`	Set to true to include the invoice memo field on the receipt.
`receipt.bccView`	Reserved field for future UI support (currently `null`).
`receipt.receiptMessage`	Defines a custom message displayed at the top of the receipt.
`receipt.bccReceiptTo`	Specifies the email address that receives a BCC copy of each receipt (if configured).

See Also