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

The server understood the request but could not process it.

401

Authentication information is missing or invalid

403

Forbidden

404

Object does not exist

406

Not Acceptable

422

The server understood the request but could not process it.

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
The server understood the request but could not process it.


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
The server understood the request but could not process it.


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