A Merchant
resource represents the entity's merchant account on a processor.
You need to create and successfully validate a Merchant
before processing any payments for your merchant.
Related Guides: Getting Started, Onboarding
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.
Accept | string Default: application/hal+json |
Finix-Version | string Default: 2018-01-01 Specify the API version of your request. For more details, see Versioning. Example: 2022-02-01 |
gateway | string Name of the gateway that processes the |
default_partial_authorization_enabled | boolean Default: false
|
processor required | string Set the acquiring processor. Use |
object or null Include up to 50
|
Single Merchant object
Error
Authentication information is missing or invalid
Forbidden
Object does not exist
Not Acceptable
Error
{- "id": "MUeTBamsYxqr1KSnT4U2x9SP",
- "created_at": "2024-08-16T13:11:36.72Z",
- "updated_at": "2024-08-16T13:11:36.72Z",
- "application": "APgPDQrLD52TYvqazjHJJchM",
- "card_cvv_required": false,
- "card_expiration_date_required": true,
- "card_network_details": null,
- "convenience_charges_enabled": false,
- "country": "USA",
- "creating_transfer_from_report_enabled": true,
- "currencies": [
- "USD"
], - "default_partial_authorization_enabled": false,
- "disbursements_ach_pull_enabled": false,
- "disbursements_ach_push_enabled": false,
- "disbursements_card_pull_enabled": false,
- "disbursements_card_push_enabled": false,
- "disbursements_same_day_ach_pull_enabled": false,
- "disbursements_same_day_ach_push_enabled": false,
- "fee_ready_to_settle_upon": "RECONCILIATION",
- "gateway": null,
- "gross_settlement_enabled": false,
- "identity": "ID6ZC4KedcaCwECQcWr7SM4m",
- "level_two_level_three_data_enabled": false,
- "loan_repayment": null,
- "mcc": "4900",
- "merchant_name": "Finix Flowers",
- "merchant_profile": "MP8aC84QAtA69Qhv6BJSyvHr",
- "mid": null,
- "onboarding_state": "PROVISIONING",
- "processing_enabled": false,
- "processor": "DUMMY_V1",
- "processor_details": { },
- "ready_to_settle_upon": "RECONCILIATION",
- "ready_to_settle_upon_delay_alignment": "NONE",
- "rent_surcharges_enabled": false,
- "settlement_enabled": false,
- "settlement_funding_identifier": "UNSET",
- "surcharges_enabled": false,
- "tags": {
- "key_2": "value_2"
}, - "verification": "VI7jopNSiaVMXWKkhxt6dJm7",
- "_links": {
- "verifications": {
}, - "merchant_profile": {
}, - "application": {
}, - "verification": {
}
}
}
Retrieve a list of Merchants
.
For details on how to query endpoints using the available parameters, see Query Parameters.
List of Merchants objects
Error
Authentication information is missing or invalid
Forbidden
Object does not exist
Not Acceptable
curl "https://finix.sandbox-payments-api.com/merchants" \ -H "Finix-Version: 2022-02-01" \ -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e
{- "_embedded": {
- "merchants": [
- {
- "id": "MUk3936kZweevCrjyHLN1vsu",
- "created_at": "2022-10-10T05:20:18.12Z",
- "updated_at": "2022-10-10T05:21:01.42Z",
- "application": "APgPDQrLD52TYvqazjHJJchM",
- "card_cvv_required": false,
- "card_expiration_date_required": true,
- "convenience_charges_enabled": false,
- "creating_transfer_from_report_enabled": true,
- "default_partial_authorization_enabled": false,
- "fee_ready_to_settle_upon": "RECONCILIATION",
- "gross_settlement_enabled": false,
- "identity": "IDx2ZETjYiWkbitkYdFt1yLF",
- "level_two_level_three_data_enabled": false,
- "mcc": "4900",
- "merchant_name": "Finix Flowers",
- "merchant_profile": "MPnXB4UBGtSUfxwA41z2Hqid",
- "mid": "FNXqeJt93ojP2cn1VUYtXANCF",
- "onboarding_state": "APPROVED",
- "processing_enabled": true,
- "processor": "DUMMY_V1",
- "processor_details": {
- "mid": "FNXqeJt93ojP2cn1VUYtXANCF",
- "api_key": "secretValue"
}, - "ready_to_settle_upon": "RECONCILIATION",
- "rent_surcharges_enabled": false,
- "settlement_enabled": true,
- "settlement_funding_identifier": "UNSET",
- "surcharges_enabled": false,
- "tags": {
- "key_2": "value_2"
}, - "verification": "VItUgbe9V8vpgSaJAriLDxER",
- "_links": {
- "verifications": {
}, - "merchant_profile": {
}, - "application": {
}, - "verification": {
}
}
}, - {
- "id": "MU951dfkbH7nqVm4G91yb2au",
- "created_at": "2022-09-21T17:46:06.29Z",
- "updated_at": "2022-09-21T17:46:09.45Z",
- "application": "APgPDQrLD52TYvqazjHJJchM",
- "card_cvv_required": false,
- "card_expiration_date_required": true,
- "convenience_charges_enabled": false,
- "creating_transfer_from_report_enabled": true,
- "default_partial_authorization_enabled": false,
- "fee_ready_to_settle_upon": "RECONCILIATION",
- "gross_settlement_enabled": false,
- "identity": "ID4YPdRriet29ZhaiVa6qhJ5",
- "level_two_level_three_data_enabled": false,
- "mcc": "4900",
- "merchant_name": "Petes Coffee",
- "merchant_profile": "MPo85BavSYVrkDn57BLh1JTs",
- "mid": "FNXkitpwdmgMJ8Vz9FxKBCSza",
- "onboarding_state": "APPROVED",
- "processing_enabled": true,
- "processor": "DUMMY_V1",
- "processor_details": {
- "mid": "FNXkitpwdmgMJ8Vz9FxKBCSza",
- "api_key": "secretValue"
}, - "ready_to_settle_upon": "RECONCILIATION",
- "rent_surcharges_enabled": false,
- "settlement_enabled": true,
- "settlement_funding_identifier": "UNSET",
- "surcharges_enabled": false,
- "tags": {
- "key": "value_2"
}, - "verification": "VIrjCZHf8v8arhbgPTikKmpp",
- "_links": {
- "verifications": {
}, - "merchant_profile": {
}, - "application": {
}, - "verification": {
}
}
}
]
}, - "_links": {
}, - "page": {
- "offset": 0,
- "limit": 20,
- "count": 1669
}
}
Retrieve the details of a Merchant
.
Single Merchant object
Authentication information is missing or invalid
Forbidden
Object does not exist
Not Acceptable
curl "https://finix.sandbox-payments-api.com/merchants/MUmUL7aBsHkxVLQawJxEXw6N" \ -H "Content-Type: application/json" \ -H "Finix-Version: 2022-02-01" \ -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e
{- "id": "MUeTBamsYxqr1KSnT4U2x9SP",
- "created_at": "2024-08-16T13:11:36.72Z",
- "updated_at": "2024-08-16T13:11:36.72Z",
- "application": "APgPDQrLD52TYvqazjHJJchM",
- "card_cvv_required": false,
- "card_expiration_date_required": true,
- "card_network_details": null,
- "convenience_charges_enabled": false,
- "country": "USA",
- "creating_transfer_from_report_enabled": true,
- "currencies": [
- "USD"
], - "default_partial_authorization_enabled": false,
- "disbursements_ach_pull_enabled": false,
- "disbursements_ach_push_enabled": false,
- "disbursements_card_pull_enabled": false,
- "disbursements_card_push_enabled": false,
- "disbursements_same_day_ach_pull_enabled": false,
- "disbursements_same_day_ach_push_enabled": false,
- "fee_ready_to_settle_upon": "RECONCILIATION",
- "gateway": null,
- "gross_settlement_enabled": false,
- "identity": "ID6ZC4KedcaCwECQcWr7SM4m",
- "level_two_level_three_data_enabled": false,
- "loan_repayment": null,
- "mcc": "4900",
- "merchant_name": "Finix Flowers",
- "merchant_profile": "MP8aC84QAtA69Qhv6BJSyvHr",
- "mid": null,
- "onboarding_state": "PROVISIONING",
- "processing_enabled": false,
- "processor": "DUMMY_V1",
- "processor_details": { },
- "ready_to_settle_upon": "RECONCILIATION",
- "ready_to_settle_upon_delay_alignment": "NONE",
- "rent_surcharges_enabled": false,
- "settlement_enabled": false,
- "settlement_funding_identifier": "UNSET",
- "surcharges_enabled": false,
- "tags": {
- "key_2": "value_2"
}, - "verification": "VI7jopNSiaVMXWKkhxt6dJm7",
- "_links": {
- "verifications": {
}, - "merchant_profile": {
}, - "application": {
}, - "verification": {
}
}
}
Update a Merchant
to:
Identity
information saved with the underlying processorMerchant
so the seller can't create new Transfers
and Authorizations
Merchant
so their Settlements
cannot be approved.Accept | string Default: application/hal+json |
Finix-Version | string Default: 2018-01-01 Specify the API version of your request. For more details, see Versioning. Example: 2022-02-01 |
Single Merchant object
Authentication information is missing or invalid
Forbidden
Object does not exist
Not Acceptable
{- "id": "MUmUL7aBsHkxVLQawJxEXw6N",
- "created_at": "2022-08-17T20:33:34.04Z",
- "updated_at": "2024-08-16T13:52:37.98Z",
- "application": "APgPDQrLD52TYvqazjHJJchM",
- "card_cvv_required": false,
- "card_expiration_date_required": true,
- "card_network_details": null,
- "convenience_charges_enabled": false,
- "country": null,
- "creating_transfer_from_report_enabled": true,
- "currencies": null,
- "default_partial_authorization_enabled": false,
- "disbursements_ach_pull_enabled": false,
- "disbursements_ach_push_enabled": false,
- "disbursements_card_pull_enabled": false,
- "disbursements_card_push_enabled": false,
- "disbursements_same_day_ach_pull_enabled": false,
- "disbursements_same_day_ach_push_enabled": false,
- "fee_ready_to_settle_upon": "RECONCILIATION",
- "gateway": null,
- "gross_settlement_enabled": false,
- "identity": "IDrH4G2VTfNjn1VFkvhcyMYj",
- "level_two_level_three_data_enabled": true,
- "loan_repayment": null,
- "mcc": null,
- "merchant_name": "John Smith",
- "merchant_profile": "MPjBZguwk8oJ9H5ouJo3jaG4",
- "mid": "FNX6ugoYdmmmRkDAEn59nhEai",
- "onboarding_state": "APPROVED",
- "processing_enabled": false,
- "processor": "DUMMY_V1",
- "processor_details": {
- "mid": "FNX6ugoYdmmmRkDAEn59nhEai",
- "api_key": "secretValue"
}, - "ready_to_settle_upon": "RECONCILIATION",
- "ready_to_settle_upon_delay_alignment": "NONE",
- "rent_surcharges_enabled": false,
- "settlement_enabled": true,
- "settlement_funding_identifier": "UNSET",
- "surcharges_enabled": false,
- "tags": {
- "key_2": "value_2"
}, - "verification": "VIn6CKA39fArkcyJF6V4yrGv",
- "_links": {
- "verifications": {
}, - "merchant_profile": {
}, - "application": {
}, - "verification": {
}
}
}
Create a Verification
on a Merchant to get them Approved. This request will create a new PENDING
Verification. Listen to updates and re-fetch the Verification when it is SUCCEEDED
or FAILED
.
For handling FAILED
Verifications, see Fetch a Verification. See also Onboarding Process for Seller Merchants and Verification Requirements for Payouts for Recipient Merchants.
Accept | string Default: application/hal+json |
Finix-Version | string Default: 2018-01-01 Specify the API version of your request. For more details, see Versioning. Example: 2022-02-01 |
Pending Merchant Verification
Error
Authentication information is missing or invalid
Forbidden
Object does not exist
Not Acceptable
{- "id": "VItpnRDSS7eMXEgbPFMKEmD3",
- "created_at": "2024-09-20T20:46:18.84Z",
- "updated_at": "2024-09-20T20:46:18.91Z",
- "application": "APgFebyumW1TVZK9sbZwAvbx",
- "identity": null,
- "merchant": "MU7F6JcADa47CT1cwoZAgLFM",
- "merchant_identity": "IDfqVY8AcjQCSdyZSFL4thMn",
- "messages": [ ],
- "outcome_summary": null,
- "outcomes": null,
- "payment_instrument": null,
- "payment_instrument_verification_details": {
- "push_to_card_domestic": null,
- "push_to_card_cross_border": null,
- "card_type": null,
- "billing_currency": null,
- "issuer_country": null
}, - "processor": "LITLE_V1",
- "raw": null,
- "state": "PENDING",
- "tags": { },
- "trace_id": "FNXmjmpf1PXHa52KDwFVEEPDy",
- "type": "MERCHANT",
- "_links": {
- "application": {
},
}
}