Create a Merchant

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

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

Request
path Parameters
identity_id
required
string

ID of Identity to fetch.

Request Body schema: application/hal+json
gateway
string

Name of the gateway that processes the Merchant's card present transactions. Use gateway only to enable a merchantto accept card present transactions.

Enum: "TRIPOS_CLOUD_V1" "TRIPOS_MOBILE_V1" "EXPRESS_V1"
processor
required
string or null

Set the acquiring processor. Avalible values include:

  • DUMMY_V1
  • LITLE_V1
  • MASTERCARD_V1
  • VISA_V1
  • NMI_V1
  • VANTIV_V1
Use DUMMY_V1 or null to use your sandbox. For more details on which processor to use, reach out to your Finix point of contact or email Finix Support.

object

Key value pair for annotating custom meta data (e.g. order numbers).

Responses
201

Single Merchant object

Response Schema: application/hal+json
id
string

The ID of the Merchant 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 the Merchant was created under.

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.

creating_transfer_from_report_enabled
boolean

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

convenience_charges_enabled
boolean

Set to true if you want to enable the Merchant to accept convenience fees and/or service fees.

fee_ready_to_settle_upon
string

Details how the Merchant settles fees.

gross_settlement_enabled
boolean

Set to true to enable gross settlements.

identity
string

The ID of the Identity resource associated with the Merchant.

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.

mcc
string or null

The Merchant Category Code (MCC) that this merchant will be classified under.

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 or null

MID of the Merchant.

onboarding_state
string

Details the state of the Merchant's onboarding.

Enum: "PROVISIONING" "APPROVED" "REJECTED"
processor
string

Name of the transaction processor.

object

Additional details specific to the processor.

processing_enabled
boolean

Details if transaction processing is enabled for the Merchant.

ready_to_settle_upon
string

Details how Authorizations captured by the Merchant are settled.

rent_surcharges_enabled
boolean

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

settlement_enabled
boolean

Details if settlement processing is enabled for the Merchant.

settlement_funding_identifier
string

Include addtional information (like the MID) when submitting funding Tranfers to processors.

object

Key value pair for annotating custom meta data (e.g. order numbers).

verification
string

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

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.

400

Error

401

Authentication information is missing or invalid

403

Forbidden

404

Object does not exist

406

Not Acceptable

422

Error

post/identities/{identity_id}/merchants
Request samples
Response samples
application/hal+json
{}

List Merchants

Retrieve a list of Merchants.

Request
query Parameters
id
string

Filter by id.

created_at.gte
string

Filter where created_at is after the given date.

Example: created_at.gte=created_at.gte=2019-06-15
created_at.lte
string

Filter where created_at is before the given date.

Example: created_at.lte=created_at.lte=2019-06-15
after_cursor
string

Return every resource created after the cursor value.

before_cursor
string

Return every resource created before the cursor value.

limit
integer

The numbers of items to return.

Example: limit=10
sort
string

Specify key to be used for sorting the collection.

Responses
200

List of Merchants objects

Response Schema: application/hal+json
object

Details the page that's returned.

object

List of Merchant objects.

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.

400

Error

401

Authentication information is missing or invalid

403

Forbidden

404

Object does not exist

406

Not Acceptable

get/merchants
Request samples
curl https://finix.sandbox-payments-api.com/merchants \
  -H "Content-Type: application/vnd.json+api" \
  -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e
Response samples
application/hal+json
{}

Fetch a Merchant

Retrieve the details of a Merchant.

Request
path Parameters
merchant_id
required
string

ID of Merchant.

Responses
200

Single Merchant object

Response Schema: application/hal+json
id
string

The ID of the Merchant 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 the Merchant was created under.

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.

creating_transfer_from_report_enabled
boolean

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

convenience_charges_enabled
boolean

Set to true if you want to enable the Merchant to accept convenience fees and/or service fees.

fee_ready_to_settle_upon
string

Details how the Merchant settles fees.

gross_settlement_enabled
boolean

Set to true to enable gross settlements.

identity
string

The ID of the Identity resource associated with the Merchant.

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.

mcc
string or null

The Merchant Category Code (MCC) that this merchant will be classified under.

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 or null

MID of the Merchant.

onboarding_state
string

Details the state of the Merchant's onboarding.

Enum: "PROVISIONING" "APPROVED" "REJECTED"
processor
string

Name of the transaction processor.

object

Additional details specific to the processor.

processing_enabled
boolean

Details if transaction processing is enabled for the Merchant.

ready_to_settle_upon
string

Details how Authorizations captured by the Merchant are settled.

rent_surcharges_enabled
boolean

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

settlement_enabled
boolean

Details if settlement processing is enabled for the Merchant.

settlement_funding_identifier
string

Include addtional information (like the MID) when submitting funding Tranfers to processors.

object

Key value pair for annotating custom meta data (e.g. order numbers).

verification
string

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

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.

401

Authentication information is missing or invalid

403

Forbidden

404

Object does not exist

406

Not Acceptable

get/merchants/{merchant_id}
Request samples
curl https://finix.sandbox-payments-api.com/merchants/MUmUL7aBsHkxVLQawJxEXw6N \
  -H "Content-Type: application/vnd.json+api" \
  -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e
Response samples
application/hal+json
{}

Update a Merchant

Update a Merchant to:

Request
path Parameters
merchant_id
required
string

ID of Merchant.

Request Body schema: application/hal+json
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.

convenience_charges_enabled
boolean

Set to true if you want to enable the Merchant to accept convenience fees and/or service fees.

creating_transfer_from_report_enabled
boolean

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

fee_ready_to_settle_upon
string

Details how the Merchant settles fees.

gross_settlement_enabled
boolean

Set to true to enable gross settlements.

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.

merchant_name
string

The legal name saved in the Merchant resource.

processing_enabled
boolean

Details if transaction processing is enabled for the Merchant.

ready_to_settle_upon
string

Details how Authorizations captured by the Merchant are settled.

rent_surcharges_enabled
boolean

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

settlement_enabled
boolean

Details if settlement processing is enabled for the Merchant.

settlement_funding_identifier
string

Include addtional information (like the MID) when submitting funding Tranfers to processors.

object

Key value pair for annotating custom meta data (e.g. order numbers).

Responses
200

Single Merchant object

Response Schema: application/hal+json
id
string

The ID of the Merchant 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 the Merchant was created under.

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.

creating_transfer_from_report_enabled
boolean

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

convenience_charges_enabled
boolean

Set to true if you want to enable the Merchant to accept convenience fees and/or service fees.

fee_ready_to_settle_upon
string

Details how the Merchant settles fees.

gross_settlement_enabled
boolean

Set to true to enable gross settlements.

identity
string

The ID of the Identity resource associated with the Merchant.

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.

mcc
string or null

The Merchant Category Code (MCC) that this merchant will be classified under.

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 or null

MID of the Merchant.

onboarding_state
string

Details the state of the Merchant's onboarding.

Enum: "PROVISIONING" "APPROVED" "REJECTED"
processor
string

Name of the transaction processor.

object

Additional details specific to the processor.

processing_enabled
boolean

Details if transaction processing is enabled for the Merchant.

ready_to_settle_upon
string

Details how Authorizations captured by the Merchant are settled.

rent_surcharges_enabled
boolean

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

settlement_enabled
boolean

Details if settlement processing is enabled for the Merchant.

settlement_funding_identifier
string

Include addtional information (like the MID) when submitting funding Tranfers to processors.

object

Key value pair for annotating custom meta data (e.g. order numbers).

verification
string

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

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.

401

Authentication information is missing or invalid

403

Forbidden

404

Object does not exist

406

Not Acceptable

put/merchants/{merchant_id}
Request samples
Response samples
application/hal+json
{}

Verify a Merchant

Verify a Merchant if the onboarding_state for a Merchant returns FAILED, or if the correct the seller needs to update the saved in their information Identity.

Related Guides: Onboarding Process

Request
path Parameters
merchant_id
required
string

ID of Merchant object.

Request Body schema: application/hal+json
identity
string

ID of the Identity resource associated with the Merchant.

merchant
string

The ID of the Merchant.

processor
string or null

Set the acquiring processor. Avalible values include:

  • DUMMY_V1
  • LITLE_V1
  • MASTERCARD_V1
  • VISA_V1
  • NMI_V1
  • VANTIV_V1
Use DUMMY_V1 or null to use your sandbox. For more details on which processor to use, reach out to your Finix point of contact or email Finix Support.

object

Key value pair for annotating custom meta data (e.g. order numbers).

Responses
201

Single Verification object

Response Schema: application/hal+json
id
string

The ID of the Verification attempt (begins with VIXXX).

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 the Merchant was created under.

identity
string or null

ID of the Identity that created the Merchant.

merchant
string or null

ID of the Merchant resource.

merchant_identity
string or null

ID of the Identity associated with the Merchant.

messages
Array of objects

Provides additional details about the verification (e.g why it failed). This field is usually null.

payment_instrument
string or null

The Payment Instrument that'll be used to settle the Merchant's processed funds.

processor
string

Name of the verification processor.

(Raw (object or null)) or (Raw (string or null))

Raw response from the processor.

state
string

The status of the Verification request.

Enum: "PENDING" "SUCCEEDED" "FAILED"
object

Key value pair for annotating custom meta data (e.g. order numbers).

trace_id
string

Trace ID of the Verification. The processor sends back the trace_id so you can track the verification end-to-end.

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.

400

Error

401

Authentication information is missing or invalid

403

Forbidden

404

Object does not exist

406

Not Acceptable

post/merchants/{merchant_id}/verifications
Request samples
Response samples
application/hal+json
{}