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.

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 merchant to 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.

tags
object or null

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.

(e.g., order number: 25, item_type: produce, department: sales, etc.)

Responses
201

Single Merchant object

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=2022-09-27T11:21:23
created_at.lte
string
Filter where created_at is before the given date.


 
 Example:  created_at.lte=2022-09-27T11:21:23
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.


 
tags.key
string
Filter by the key of a Tag.


 
tags.value
string
Filter by the value of a Tag.


 
Responses 
200
List of Merchants objects


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.api+json" \
  -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


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.api+json" \
  -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 transactions 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
 Default:  "UNSET"
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.


 Enum: "UNSET" "MID_AND_DATE" "MID_AND_MERCHANT_NAME"  
tags
object or null
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.
    • 



(e.g., order number: 25, item_type: produce, department: sales, etc.)


 
Responses 
200
Single Merchant object


401
Authentication information is missing or invalid


403
Forbidden


404
Object does not exist


406
Not Acceptable


put/merchants/{merchant_id}
Request samples 
curl https://finix.sandbox-payments-api.com/merchants/MUeDVrf2ahuKc9Eg5TeZugvs \
  -H "Content-Type: application/vnd.api+json" \
  -u UStxEci4vXxGDWLQhNvao7YY:25038781-2369-4113-8187-34780e91052e \
  -X PUT \
  -d '
  {
        "level_two_level_three_data_enabled": true
    }'
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
Any of:
merchant
required
string
The ID of the Merchant.


 
processor
string
 Default:  "DUMMY_V1"
Set the acquiring processor. Avalible values include: 
  • DUMMY_V1
  • MASTERCARD_V1
  • VISA_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.


 Enum: "DUMMY_V1" "MASTERCARD_V1" "VISA_V1"  
security_code
required
string
The ID of the Merchant.


 
verify_payment_card
required
boolean
    

  • Set to true to verify card details with the card issuer.
    • 

  • Must be set to true to update the CVV or security code of a card.
    • 



 
tags
object or null
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.
    • 



(e.g., order number: 25, item_type: produce, department: sales, etc.)


 
Responses 
201
Single Verification object


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
{}