v1

latestOpenAPI 3.0.22026-08-061303782.1 MB

Merchants

Create a Merchant

Create a Merchant to start the underwriting (also called provisioning) process for your seller. Merchants must be created under an Identity.

A bank account must be associated with the previously created Identity before a Merchant can be successfully onboarded and verified.

post/identities/{identity_id}/merchants

Headers

Finix-Versionstring

Example:2022-02-01

Specify the API version of your request. For more details, see Versioning.

Content-Typestring

Example:application/json

The data type being sent in the request body must be application/json.

Request body

default_partial_authorization_enabledboolean

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.

loan_repaymentboolean

Set to true to enable the Merchant to process debt loan repayment. Only MCCs 6012 and 6051 are eligible.

processor'DUMMY_V1' | 'FINIX_V1' required

Set the acquiring processor. Use DUMMY_V1 or null for your Sandbox. For more details on which processor to use, reach out to your Finix point of contact or email Finix Support.

refunds_disabledboolean

A value of true disables refunds for the Merchant, including both referenced and unreferenced refunds.

tagsTags 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)

Response

Single Merchant object

idstring

The ID of the resource.

created_atstring date-time

Timestamp of when the object was created.

updated_atstring date-time

Timestamp of when the object was last updated.

applicationstring

ID of the Application associated with the resource.

card_cvv_requiredboolean

Set to true to require the card's CVV code.

card_expiration_date_requiredboolean

Set to true to require the card's expiration date.

card_network_detailsobject nullable

convenience_charges_enabledboolean

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_enabledboolean

Set to true to automatically create Transfers once settlement reports get generated.

currenciesCurrency[] nullable

ISO 4217 3-letter currency code.

default_partial_authorization_enabledboolean

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_enabledboolean

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_enabledboolean

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_atstring 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_enabledboolean

Set to true to enable gross settlements.

identitystring

The ID of the Identity resource associated with the Merchant.

instant_payouts_card_push_enabledboolean

Set to true if you want to allow the merchant to be enabled for settlement instant payouts.

is_terminatedboolean

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_enabledboolean

Set to true to enable the Merchant for Level 2 and Level 3 processing. Default value is false.

loan_repaymentboolean

Whether the merchant is able to support loan repayment on the card networks.

mccstring nullable

The Merchant Category Code (MCC) that this merchant will be classified under. For a list of approved MCCs, see Approved Merchant Category Codes.

merchant_namestring

The legal name saved in the Merchant resource.

merchant_profilestring

Details if a merchant's info was submitted to third-party processors for provisioning.

midstring nullable

MID of the Merchant.

onboarding_state'APPROVED' | 'PROVISIONING' | 'REJECTED' | 'UPDATE_REQUESTED'

Details the state of the Merchant's onboarding.

processing_enabledboolean

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.

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_disabledboolean

A value of true disables refunds for the Merchant, including both referenced and unreferenced refunds.

rent_surcharges_enabledboolean

Set to true if you want to enable a Merchant to accept rent charges.

settlement_enabledboolean

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_enabledboolean

Set to true if you want to enable a Merchant to accept surcharge fees. For more details, see Buyer Charges.

tagsTags 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)

unreferenced_refund_manual_entry_enabledboolean

Indicates if merchant is allowed to process unreferenced refunds initiated through manual card entry on Finix terminals.

verificationstring

ID of the Verification that was submitted to verify the Merchant.

Example response

{
  "termination_details": {
    "terminated_at": "2024-09-16T13:11:36.72Z"
  }
}