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
id
string

Filter by id.

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
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
limit
integer

The numbers of items to return.

Example: limit=10
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
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
{}