---
title: "Update a Merchant"
method: PUT
path: "/merchants/{merchant_id}"
tags: ["Merchants"]
---

# Update a Merchant

`PUT /merchants/{merchant_id}`

Update a `Merchant` to:
- Change the `Identity` information saved with the underlying processor
- [Enable Level 2/3 processing](/guides/online-payments/payment-features/level-2-level-3-processing)
- Enable [Buyer Charges](/guides/online-payments/payment-features/buyer-charges)
- Enable partial authorizations
- Disable a `Merchant` so the seller can't create new `Transfers` and `Authorizations`
- Disable a `Merchant` so their `Settlements` cannot be approved.
- Enable a `Merchant` to use the Settlement Queue
- Terminate a `Merchant` for suspected fraud, compliance violations, excessive chargebacks, or merchant churn.

## Request body

- union
  - UpdateMerchantDisableProcessing
    - `processing_enabled` boolean — Details if transaction processing is enabled for the `Merchant`. `ROLE_PARTNER` can only set this value to `false`.
    - `tags` Tags, nullable — Include up to 50 `key: value` pairs to annotate requests with custom metadata. - Maximum character length for individual `keys` is 40. - Maximum character length for individual `values` is 500. (For example, `order_number: 25`, `item_type: produce`, `department: sales`)
  - UpdateMerchantDisableSettlements
    - `settlement_enabled` boolean — Details if settlement approvals are enabled for the `Merchant`. `ROLE_PARTNER` can only set this value to `false`.
    - `tags` Tags, nullable — Include up to 50 `key: value` pairs to annotate requests with custom metadata. - Maximum character length for individual `keys` is 40. - Maximum character length for individual `values` is 500. (For example, `order_number: 25`, `item_type: produce`, `department: sales`)
  - UpdateMerchantEnableBuyerCharges
    - `convenience_charges_enabled` boolean — Set to **true** if you want to enable the `Merchant` to accept convenience fees and/or service fees.
    - `rent_surcharges_enabled` boolean — Set to **true** if you want to enable a `Merchant` to accept rent charges.
    - `surcharge_fees_enabled` boolean — Set to **true** if you want to enable a `Merchant` to accept surcharge fees.
    - `tags` Tags, nullable — Include up to 50 `key: value` pairs to annotate requests with custom metadata. - Maximum character length for individual `keys` is 40. - Maximum character length for individual `values` is 500. (For example, `order_number: 25`, `item_type: produce`, `department: sales`)
  - UpdateMerchantEnableL2L3Processing
    - `level_two_level_three_data_enabled` boolean — Set to **true** to enable the `Merchant` for Level 2 and Level 3 processing. Default value is **false**.
    - `tags` Tags, nullable — Include up to 50 `key: value` pairs to annotate requests with custom metadata. - Maximum character length for individual `keys` is 40. - Maximum character length for individual `values` is 500. (For example, `order_number: 25`, `item_type: produce`, `department: sales`)
  - UpdateMerchantEnableLoanRepayment
    - `loan_repayment` boolean — Set to `true` to enable the `Merchant` to process debt loan repayment. Only MCCs `6012` and `6051` are eligible.
    - `tags` Tags, nullable — Include up to 50 `key: value` pairs to annotate requests with custom metadata. - Maximum character length for individual `keys` is 40. - Maximum character length for individual `values` is 500. (For example, `order_number: 25`, `item_type: produce`, `department: sales`)
  - UpdateMerchantEnablePartialAuthorizations
    - `default_partial_authorization_enabled` boolean — - Set to **true** if you want to enable partial authorizations for a specific `Merchant`. - Partial authorizations enable the `Merchant` to collect a portion of the amount if the cardholder doesn't have the funds to cover the entire amount on their card.
    - `tags` Tags, nullable — Include up to 50 `key: value` pairs to annotate requests with custom metadata. - Maximum character length for individual `keys` is 40. - Maximum character length for individual `values` is 500. (For example, `order_number: 25`, `item_type: produce`, `department: sales`)
  - UpdateMerchantEnableSameDayACH
    - `disbursements_same_day_ach_pull_enabled` boolean — Indicates whether same-day ACH pull disbursements (debits) are enabled, allowing funds to be withdrawn from an account via same-day ACH transfer.
    - `disbursements_same_day_ach_push_enabled` boolean — Indicates whether same-day ACH push disbursements (credits) are enabled, allowing funds to be sent to an account via same-day ACH transfer.
    - `tags` Tags, nullable — Include up to 50 `key: value` pairs to annotate requests with custom metadata. - Maximum character length for individual `keys` is 40. - Maximum character length for individual `values` is 500. (For example, `order_number: 25`, `item_type: produce`, `department: sales`)
  - UpdateMerchantSettlementQueue
    - `settlement_queue_mode` 'MANUAL' | 'UNSET' — Set to `MANUAL` to enable the `Merchant` to use the Settlement Queue.
  - UpdateMerchantTerminate
    - `is_terminated` boolean — Set to `true` to terminate the `Merchant`. A merchant can only be terminated if its current `onboarding_state` is `APPROVED`.
    - `tags` Tags, nullable — Include up to 50 `key: value` pairs to annotate requests with custom metadata. - Maximum character length for individual `keys` is 40. - Maximum character length for individual `values` is 500. (For example, `order_number: 25`, `item_type: produce`, `department: sales`)
    - `termination_details` object
      - `description` string — An explanation that provides context for the termination.
      - `reason` 'CHURNED' | 'COMPLIANCE_VIOLATION' | 'EXCESSIVE_ACH_RETURNS' | 'EXCESSIVE_CHARGEBACKS' | 'FRAUD' | 'IDENTITY_THEFT' | 'ILLEGAL_TRANSACTIONS' | 'INSOLVENCY' | 'OTHER' | 'PCI_VIOLATION' | 'PROCESSOR_MIGRATION' | 'SUSPECTED_FRAUD' | 'UNSUPPORTED_BUSINESS_TYPE' | 'UNUSUAL_ACTIVITY' | 'VIOLATED_MERCHANT_TERMS_OF_SERVICE' — The reason for termination. Required if `is_terminated` is set to `true`.

## Response `200`

A single `Merchant`

- Merchant
  - `id` string — The ID of the resource.
  - `created_at` string, date-time — Timestamp of when the object was created.
  - `updated_at` string, date-time — Timestamp of when the object was last updated.
  - `application` string — ID of the `Application` associated with the resource.
  - `card_cvv_required` boolean — Set to `true` to require the card's CVV code.
  - `card_expiration_date_required` boolean — Set to `true` to require the card's expiration date.
  - `card_network_details` object, nullable
  - `convenience_charges_enabled` boolean — Set to `true` if you want to enable the `Merchant` to accept convenience fees and/or service fees.
  - `country` 'ABW' | 'AFG' | 'AGO' | 'AIA' | 'ALA' | 'ALB' | 'AND' | 'ARE' | 'ARG' | 'ARM' | 'ASM' | 'ATA' | 'ATF' | 'ATG' | 'AUS' | 'AUT' | 'AZE' | 'BDI' | 'BEL' | 'BEN' | 'BES' | 'BFA' | 'BGD' | 'BGR' | 'BHR' | 'BHS' | 'BIH' | 'BLM' | 'BLR' | 'BLZ' | 'BMU' | 'BOL' | 'BRA' | 'BRB' | 'BRN' | 'BTN' | 'BVT' | 'BWA' | 'CAF' | 'CAN' | 'CCK' | 'CHE' | 'CHL' | 'CHN' | 'CIV' | 'CMR' | 'COD' | 'COG' | 'COK' | 'COL' | 'COM' | 'CPV' | 'CRI' | 'CUB' | 'CUW' | 'CXR' | 'CYM' | 'CYP' | 'CZE' | 'DEU' | 'DJI' | 'DMA' | 'DNK' | 'DOM' | 'DZA' | 'ECU' | 'EGY' | 'ERI' | 'ESH' | 'ESP' | 'EST' | 'ETH' | 'FIN' | 'FJI' | 'FLK' | 'FRA' | 'FRO' | 'FSM' | 'GAB' | 'GBR' | 'GEO' | 'GGY' | 'GHA' | 'GIB' | 'GIN' | 'GLP' | 'GMB' | 'GNB' | 'GNQ' | 'GRC' | 'GRD' | 'GRL' | 'GTM' | 'GUF' | 'GUM' | 'GUY' | 'HKG' | 'HMD' | 'HND' | 'HRV' | 'HTI' | 'HUN' | 'IDN' | 'IMN' | 'IND' | 'IOT' | 'IRL' | 'IRN' | 'IRQ' | 'ISL' | 'ISR' | 'ITA' | 'JAM' | 'JEY' | 'JOR' | 'JPN' | 'KAZ' | 'KEN' | 'KGZ' | 'KHM' | 'KIR' | 'KNA' | 'KOR' | 'KWT' | 'LAO' | 'LBN' | 'LBR' | 'LBY' | 'LCA' | 'LIE' | 'LKA' | 'LSO' | 'LTU' | 'LUX' | 'LVA' | 'MAC' | 'MAF' | 'MAR' | 'MCO' | 'MDA' | 'MDG' | 'MDV' | 'MEX' | 'MHL' | 'MKD' | 'MLI' | 'MLT' | 'MMR' | 'MNE' | 'MNG' | 'MNP' | 'MRT' | 'MSR' | 'MTQ' | 'MUS' | 'MWI' | 'MYS' | 'MYT' | 'NAM' | 'NCL' | 'NER' | 'NFK' | 'NGA' | 'NIC' | 'NIU' | 'NLD' | 'NOR' | 'NPL' | 'NRU' | 'NZL' | 'OMN' | 'PAK' | 'PAN' | 'PCN' | 'PER' | 'PHL' | 'PLW' | 'PNG' | 'POL' | 'PRI' | 'PRK' | 'PRT' | 'PRY' | 'PSE' | 'PYF' | 'QAT' | 'REU' | 'ROU' | 'RUS' | 'RWA' | 'SAU' | 'SDN' | 'SEN' | 'SGP' | 'SGS' | 'SHN' | 'SJM' | 'SLB' | 'SLE' | 'SLV' | 'SMR' | 'SOM' | 'SPM' | 'SRB' | 'SSD' | 'STP' | 'SUR' | 'SVK' | 'SVN' | 'SWE' | 'SWZ' | 'SXM' | 'SYC' | 'SYR' | 'TCA' | 'TCD' | 'TGO' | 'THA' | 'TJK' | 'TKL' | 'TKM' | 'TLS' | 'TON' | 'TTO' | 'TUN' | 'TUR' | 'TUV' | 'TWN' | 'TZA' | 'UGA' | 'UKR' | 'UMI' | 'URY' | 'USA' | 'UZB' | 'VAT' | 'VCT' | 'VEN' | 'VGB' | 'VIR' | 'VNM' | 'VUT' | 'WLF' | 'WSM' | 'XKX' | 'YEM' | 'ZAF' | 'ZMB' | 'ZWE', nullable
  - `creating_transfer_from_report_enabled` boolean — Set to `true` to automatically create `Transfers` once settlement reports get generated.
  - `currencies` Currency[], nullable — ISO 4217 3-letter currency code.
  - `default_partial_authorization_enabled` boolean — - Set to **true** if you want to enable partial authorizations for a specific `Merchant`. - Partial authorizations enable the `Merchant` to collect a portion of the amount if the cardholder doesn't have the funds to cover the entire amount on their card.
  - `disbursements_same_day_ach_pull_enabled` boolean — Indicates whether same-day ACH pull disbursements (debits) are enabled, allowing funds to be withdrawn from an account via same-day ACH transfer.
  - `disbursements_same_day_ach_push_enabled` boolean — Indicates whether same-day ACH push disbursements (credits) are enabled, allowing funds to be sent to an account via same-day ACH transfer.
  - `fee_ready_to_settle_upon` 'RECONCILIATION' | 'SUCCESSFUL_CAPTURE' | 'PROCESSOR_WINDOW' | 'CONFIGURABLE_WINDOW' — Details how the `Merchant` settles fees.
  - `first_approved_at` string, date-time, nullable — This field shows the timestamp when the `Merchant` was first approved. If the `Merchant` has not been approved yet, the value is `null`.
  - `gross_settlement_enabled` boolean — Set to `true` to enable gross settlements.
  - `identity` string — The ID of the `Identity` resource associated with the `Merchant`.
  - `instant_payouts_card_push_enabled` boolean — Set to `true` if you want to allow the merchant to be enabled for settlement instant payouts.
  - `is_terminated` boolean — Set to `true` to terminate the `Merchant`. A merchant can only be terminated if its current `onboarding_state` is `APPROVED`.
  - `level_two_level_three_data_enabled` boolean — Set to `true` to enable the `Merchant` for Level 2 and Level 3 processing. Default value is `false`.
  - `loan_repayment` boolean — Whether the merchant is able to support loan repayment on the card networks.
  - `mcc` string, nullable — The Merchant Category Code ([MCC](http://www.dm.usda.gov/procurement/card/card\_x/mcc.pdf)) that this merchant will be classified under. For a list of approved MCCs, see [Approved Merchant Category Codes.](/guides/managing-operations/security-compliance/approved-merchant-category-codes)
  - `merchant_name` string — The legal name saved in the `Merchant` resource.
  - `merchant_profile` string — Details if a merchant's info was submitted to third-party processors for provisioning.
  - `mid` string, nullable — MID of the `Merchant`.
  - `onboarding_state` 'APPROVED' | 'PROVISIONING' | 'REJECTED' | 'UPDATE_REQUESTED' — Details the state of the `Merchant's` onboarding.
  - `processing_enabled` boolean — Details if transaction processing is enabled for the `Merchant`. `ROLE_PARTNER` can only set this value to `false`.
  - `processor` 'FINIX_V1' | 'DUMMY_V1' — Name of the transaction processor.
  - `processor_details` object — Additional details specific to the processor.
    - `mid` string
    - `api_key` string
  - `ready_to_settle_upon` 'RECONCILIATION' | 'SUCCESSFUL_CAPTURE' | 'PROCESSOR_WINDOW' | 'CONFIGURABLE_WINDOW' — Details how transactions captured by the `Merchant` are settled.
  - `ready_to_settle_upon_delay_alignment` 'ACH' | 'NONE' — Indicates whether transaction settlement should be delayed to synchronize the timing of all transactions, including both card and ACH, ensuring they are settled together. Possible values include: - `ACH` - Align all transactions to match the timing of ACH settlements, so card transactions settle at the same speed as ACH transactions. - `NONE` - Default behavior where card transactions settle the next day (T+1) and ACH transactions settle two days later (T+2).
  - `refunds_disabled` boolean — A value of `true` disables refunds for the `Merchant`, including both referenced and unreferenced refunds.
  - `rent_surcharges_enabled` boolean — Set to `true` if you want to enable a `Merchant` to accept rent charges.
  - `settlement_enabled` boolean — Details if settlement approvals are enabled for the `Merchant`. `ROLE_PARTNER` can only set this value to false.
  - `settlement_funding_identifier` 'UNSET' | 'MID_AND_DATE' | 'MID_AND_MERCHANT_NAME' — Includes additional information (like the MID or `Merchant` name) when submitting funding `Transfers` to processors. - `UNSET`: No additional details get provided to the processor. - `MID_AND_DATE`: The `MID` of the `Merchant` and the date the funding `Transfer` was submitted (Date is in UTC). e.g `MID:12345678-20220225` - `MID_AND_MERCHANT_NAME`: The `MID` of the `Merchant` and the `Merchant#name` (white spaces will be removed). e.g. `MID:12345678-NameOfMerchant` These details appear alongside the seller's payout in their bank account as a description of the deposit.
  - `settlement_queue_mode` 'UNSET' | 'MANUAL' — If `settlement_queue_mode` is set to `MANUAL`, Finix will automatically place all transactions (Sales, Fees, Refunds, and ACH Returns) into a settlement queue that you can manage. Each transaction will have a `Settlement Queue Entry`. When a `Settlement Queue Entry` is created, it will not be placed into `Settlement` until the `Settlement Queue Entry` is explicitly released. Note: We require the release of all settlement queue entries within 30 days of creation.
  - `surcharges_enabled` boolean — Set to `true` if you want to enable a `Merchant` to accept surcharge fees. For more details, see [Buyer Charges](/guides/online-payments/payment-features/buyer-charges).
  - `tags` Tags, nullable — Include up to 50 `key: value` pairs to annotate requests with custom metadata. - Maximum character length for individual `keys` is 40. - Maximum character length for individual `values` is 500. (For example, `order_number: 25`, `item_type: produce`, `department: sales`)
  - `termination_details` object
    - `terminated_at` string, date-time — Timestamp indicating when the termination occurred.
    - `reason` 'CHURNED' | 'COMPLIANCE_VIOLATION' | 'EXCESSIVE_ACH_RETURNS' | 'EXCESSIVE_CHARGEBACKS' | 'FRAUD' | 'IDENTITY_THEFT' | 'ILLEGAL_TRANSACTIONS' | 'INSOLVENCY' | 'OTHER' | 'PCI_VIOLATION' | 'PROCESSOR_MIGRATION' | 'SUSPECTED_FRAUD' | 'UNSUPPORTED_BUSINESS_TYPE' | 'UNUSUAL_ACTIVITY' | 'VIOLATED_MERCHANT_TERMS_OF_SERVICE' — The reason for termination. Finix reserves the right to return enums that are not listed here.
    - `description` string — An explanation that provides context for the termination.
    - `terminated_by` 'PLATFORM_USER' | 'PARTNER_USER' — The role that initiated the termination. If the API key belongs to the `USER` role, the following values will be returned: - If the role is `ROLE_PLATFORM`, it will return `PLATFORM_USER`. - If the role is `ROLE_PARTNER`, it will return `PARTNER_USER`.
    - `terminated_by_user_id` string — The `User` ID of the user who initiated the termination of the `Merchant` account.
  - `unreferenced_refund_manual_entry_enabled` boolean — Indicates if merchant is allowed to process unreferenced refunds initiated through manual card entry on Finix terminals.
  - `verification` string — ID of the `Verification` that was submitted to verify the `Merchant`.
  - `_links` object — For your convenience, every response includes several URLs which link to resources relevant to the request. You can use these `_links` to make your follow-up requests and quickly access relevant IDs.
    - `self` Self — Link to the resource that was used in the request.
      - `href` string
    - `identity` IdentityLink — Link to the `Identity` the request was made under.
      - `href` string
    - `verifications` Verifications — Link to the `Verification` the request was made under.
      - `href` string
    - `merchant_profiles` MerchantProfiles — Link to the `merchant_profile` the request was made under.
      - `href` string
    - `application` ApplicationLink — Link to the `Application` the request was made under.
      - `href` string

## Other responses

- `400` — Bad Request. The server cannot process the request due to malformed syntax or invalid data.
- `401` — Unauthorized. Authentication is required and has failed or has not been provided.
- `403` — Forbidden. The client is authenticated but does not have permission to access the resource.
- `404` — Not Found. The requested resource could not be found on the server.
- `406` — Not Acceptable. The server could accept the submitted request. Confirm how the request was formatted and submitted.

---

[API](https://skmtc.net/finix/apis/finix-api-reference.md) · [All operations](https://skmtc.net/finix/apis/finix-api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/finix/finix-api-reference/versions/5426f6f99c52/schema)