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.

header Parameters
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
Request Body schema: application/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" "DATACAP_V1"
default_partial_authorization_enabled
boolean
Default: false
  • Set to true if you want to enable partial authorizations for a specific Merchant.
  • Partial authorizations enables 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.
processor
required
string

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.

Enum: "DUMMY_V1" "FINIX_V1" "LITLE_V1" "MASTERCARD_V1" "NMI_V1" … 2 more
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. (For example, order_number: 25, item_type: produce, department: sales)
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/json
{}
List Merchants
Retrieve a list of Merchants.


For details on how to query endpoints using the available parameters, see Query Parameters.      


Request 
query Parameters
after_cursor
string
Return every resource created after the cursor value.


 
 Example:  after_cursor=TRnasXQ5AmjsLnPMwnme7TL4
before_cursor
string
Return every resource created before the cursor value.


 
 Example:  before_cursor=TRnasXQ5AmjsLnPMwnme7TL4
limit
integer
The numbers of items to return.


 
 Example:  limit=10
application_id
string
Filter by the Merchant's application.


 
 Example:  application_id=APgPDQrLD52TYvqazjHJJchM
country
string
Filter by the Merchant's country (ISO 3166 alpha-3).


 Enum: "USA" "CAN"  
 Example:  country=USA
created_at.gte
string <date-time> 
Filter where created_at is after the given date.


 
 Example:  created_at.gte=2022-09-27T11:21:23
created_at.lte
string <date-time> 
Filter where created_at is before the given date.


 
 Example:  created_at.lte=2022-09-27T11:21:23
currency
string
Filter by the Merchant's currencies (ISO 4217).


 Enum: "USD" "CAD"  
 Example:  currency=USD
id
string
Filter by id.


 
identity_business_name
string
Filter by the business_name of the Merchant's identity (exact match).


 
 Example:  identity_business_name=finix%20flowers
identity_business_name.like
string
Filter by the business_name of the Merchant's identity (partial match).


 
 Example:  identity_business_name.like=finix
identity_doing_business_as
string
Filter by the doing_business_as of the Merchant's identity (exact match).


 
 Example:  identity_doing_business_as=finix%20flowers
identity_doing_business_as.like
string
Filter by the doing_business_as of the Merchant's identity (partial match).


 
 Example:  identity_doing_business_as.like=finix
identity_first_name
string
Filter by the first_name of the Merchant's identity (exact match).


 
 Example:  identity_first_name=jonathan
identity_first_name.like
string
Filter by the first_name of the Merchant's identity (partial match).


 
 Example:  identity_first_name.like=jon
identity_id
string
Filter by the Merchant's identity.


 
 Example:  identity_id=ID6ZC4KedcaCwECQcWr7SM4m
identity_last_name
string
Filter by the last_name of the Merchant's identity (exact match).


 
 Example:  identity_last_name=williams
identity_last_name.like
string
Filter by the last_name of the Merchant's identity (partial match).


 
 Example:  identity_last_name.like=will
identity_role
string
Filter by the identity_roles of the Merchant's identity.


 Enum: "APPLICATION_OWNER" "RECIPIENT" "SELLER"  
 Example:  identity_role=SELLER
mcc
string
Filter by the Merchant's mcc.


 
 Example:  mcc=4900
merchant_name
string
Filter by the Merchant's merchant_name (exact match).


 
 Example:  merchant_name=finix%20flowers
merchant_name.like
string
Filter by the Merchant's merchant_name (partial match).


 
 Example:  merchant_name.like=finix
processing_enabled
boolean
Filter by whether the Merchant's processing is enabled (processing_enabled).


 
 Example:  processing_enabled=true
processor_type
string
Filter by the Merchant's processor.


 Enum: "FINIX_V1" "LITLE_V1" "VANTIV_V1" "DUMMY_V1"  
 Example:  processor_type=DUMMY_V1
settlement_enabled
boolean
Filter by whether the Merchant's settlements are enabled (settlement_enabled).


 
 Example:  settlement_enabled=true
updated_at.gte
string <date-time> 
Filter where updated_at is after the given date.


 
 Example:  updated_at.gte=2022-09-27T11:21:23
updated_at.lte
string <date-time> 
Filter where updated_at is before the given date.


 
 Example:  updated_at.lte=2023-01-21T10:17:22
verification_id
string
Filter by the Merchant's verification.


 
 Example:  verification_id=VI7jopNSiaVMXWKkhxt6dJm7
header Parameters
Accept
string
 Default:  application/hal+json
Body Header


 
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 "Finix-Version: 2022-02-01" \
  -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e

Response samples 
application/json
{}
Fetch a Merchant
Retrieve the details of a Merchant.


Request 
path Parameters
merchant_id
required
string
ID of Merchant.


 
header Parameters
Accept
string
 Default:  application/hal+json
 
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/json" \
  -H "Finix-Version: 2022-02-01" \
  -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e

Response samples 
application/json
{}
Update a Merchant
Update a Merchant to: 


    

  • Change the Identity information saved with the underlying processor
    • 

  • Enable Level 2/3 processing
    • 

  • Enable 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.
    • 



Request 
path Parameters
merchant_id
required
string
ID of Merchant.


 
header Parameters
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
Request Body schema: application/json
Any of:
processing_enabled
required
boolean
Details if transaction processing is enabled for the Merchant. ROLE_PARTNER can only set this value to false.


 
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.
(For example, order_number: 25, item_type: produce, department: sales)
    • 



 
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 
Response samples 
application/json
{}
Verify a Merchant
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.


Request 
path Parameters
merchant_id
required
string
ID of Merchant object.


 
header Parameters
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
Request Body schema: application/json
object
 
Responses 
201
Pending Merchant Verification


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