# 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.

Endpoint: POST /merchants/{merchant_id}/verifications
Security: BasicAuth

## Path parameters:

  - `merchant_id` (string, required)
    The Merchant ID.
    Example: "MUiV7ntxfY4eyJxp6E7cZvym"

## Header parameters:

  - `Finix-Version` (string)
    Specify the API version of your request. For more details, see Versioning.
    Example: "2022-02-01"

  - `Content-Type` (string)
    The data type being sent in the request body must be application/json.
    Example: "application/json"

## Response 201 fields (application/json):

  - `id` (string)
    The ID of the resource.

  - `created_at` (string)
    Timestamp of when the object was created.

  - `updated_at` (string)
    Timestamp of when the object was last updated.

  - `application` (string)
    ID of the Application the resource was created under.

  - `identity` (string,null)
    The ID of the Identity used to create the Merchant.

  - `merchant` (string)
    The ID of the Merchant sent for verification.

  - `merchant_identity` (string)
    The Identity ID associated with the Merchant.

  - `messages` (array)
    A codified list of reasons the verification request failed.

  - `outcome_summary` (string,null)
    A message providing additional context about why the verification request failed, available for SELLER merchants only.

  - `outcomes` (array,null)
    A codified list of reasons the verification request failed, available for SELLER merchants only.

  - `outcomes.outcome_code` (string)
    A code indicating the reason the verification request failed. Finix reserves the right to return enums that are not listed here.
    Enum: "BANK_STATEMENT_ONE_MONTH_REQUESTED", "BANK_STATEMENT_THREE_MONTHS_REQUESTED", "BUSINESS_ADDRESS_DOCUMENT_REQUESTED", "BUSINESS_INCORPORATION_DOCUMENT_REQUESTED", "BUSINESS_REGISTRATION_DOCUMENT_REQUESTED", "BUSINESS_TAX_EXEMPTION_STATUS_DOCUMENT_REQUESTED", "BUSINESS_TAX_ID_DOCUMENT_REQUESTED", "INVALID_BANK_STATEMENT_ONE_MONTH", "INVALID_BANK_STATEMENT_THREE_MONTHS", "INVALID_BUSINESS_ADDRESS", "INVALID_BUSINESS_ADDRESS_DOCUMENT", "INVALID_BUSINESS_DBA", "INVALID_BUSINESS_DESCRIPTION", "INVALID_BUSINESS_INCORPORATION_DATE", "INVALID_BUSINESS_INCORPORATION_DOCUMENT", "INVALID_BUSINESS_MCC", "INVALID_BUSINESS_NAME", "INVALID_BUSINESS_OWNERSHIP_TYPE", "INVALID_BUSINESS_PHONE", "INVALID_BUSINESS_REGISTRATION_DOCUMENT", "INVALID_BUSINESS_TAX_EXEMPTION_STATUS_DOCUMENT", "INVALID_BUSINESS_TAX_ID", "INVALID_BUSINESS_TAX_ID_DOCUMENT", "INVALID_BUSINESS_TYPE", "INVALID_BUSINESS_WEBSITE", "INVALID_OWNER_ADDRESS", "INVALID_OWNER_BIRTHDATE", "INVALID_OWNER_EMAIL", "INVALID_OWNER_FIRST_NAME", "INVALID_OWNER_GOVERNMENT_ISSUED_PHOTO_ID", "INVALID_OWNER_LAST_NAME", "INVALID_OWNER_PHONE", "INVALID_OWNER_TAX_ID", "INVALID_OWNER_TAX_ID_DOCUMENT", "INVALID_OWNER_TITLE", "INVALID_PAYMENT_INSTRUMENT_ACCOUNT_NUMBER", "INVALID_PAYMENT_INSTRUMENT_BANK_CODE", "INVALID_PAYMENT_INSTRUMENT_NAME", "OWNER_GOVERNMENT_ISSUED_PHOTO_ID_REQUESTED", "OWNER_TAX_ID_DOCUMENT_REQUESTED", "PROCESSING_STATEMENT_REQUESTED"

  - `outcomes.outcome_message` (string,null)
    An optional message from the Finix underwriting team providing additional context about the outcome code. Only visible to Applications, not submerchants.

  - `outcomes.remediation_details` (object,null)
    Details about the action required to remediate the verification failure.

  - `outcomes.remediation_details.entity_id` (string)
    The ID of the entity that needs to be updated.

  - `outcomes.remediation_details.entity_type` (string)
    The type of entity that needs to be updated.
    Enum: "IDENTITY"

  - `outcomes.remediation_details.field_name` (string,null)
    The name of the field that needs to be updated. Returned when type is FIELD_UPDATE.

  - `outcomes.remediation_details.file_type` (string,null)
    The type of file that needs to be uploaded. Returned when type is FILE_UPLOAD.
    Enum: "BANK_STATEMENT_ONE_MONTH", "BANK_STATEMENT_THREE_MONTHS", "BUSINESS_ADDRESS_DOCUMENT", "BUSINESS_INCORPORATION_DOCUMENT", "BUSINESS_REGISTRATION_DOCUMENT", "BUSINESS_TAX_EXEMPTION_STATUS_DOCUMENT", "BUSINESS_TAX_ID_DOCUMENT", "OWNER_GOVERNMENT_ISSUED_PHOTO_ID", "OWNER_TAX_ID_DOCUMENT", "PROCESSING_STATEMENT"

  - `outcomes.remediation_details.type` (string)
    The type of remediation action required.
    Enum: "FIELD_UPDATE", "FILE_UPLOAD"

  - `payment_instrument` (string,null)
    This field is not applicable to merchant verification.

  - `payment_instrument_verification_details` (object)
    This object is not applicable to merchant verification.

  - `payment_instrument_verification_details.pull_from_card_cross_border` (string,null)
    This object is not applicable to merchant verification.

  - `payment_instrument_verification_details.pull_from_card_domestic` (string,null)
    This object is not applicable to merchant verification.

  - `payment_instrument_verification_details.push_to_card_domestic` (string,null)
    This object is not applicable to merchant verification.

  - `payment_instrument_verification_details.push_to_card_cross_border` (string,null)
    This object is not applicable to merchant verification.

  - `payment_instrument_verification_details.card_type` (string,null)
    This object is not applicable to merchant verification.

  - `payment_instrument_verification_details.billing_currency` (string,null)
    This object is not applicable to merchant verification.

  - `payment_instrument_verification_details.issuer_country` (string,null)
    This object is not applicable to merchant verification.

  - `payment_instrument_verification_details.name_verification_results` (object,null)
    Details the results of verifying the cardholder's name. Not applicable to merchant verification.

  - `payment_instrument_verification_details.name_verification_results.first_name` (string)
    The result of verifying the cardholder's first name.
    Enum: "MATCH", "MATCHED", "NO_MATCH", "NOT_SUPPORTED", "PARTIAL_MATCH", "UNKNOWN"

  - `payment_instrument_verification_details.name_verification_results.last_name` (string)
    The result of verifying the cardholder's last name.
    Enum: "MATCH", "MATCHED", "NO_MATCH", "NOT_SUPPORTED", "PARTIAL_MATCH", "UNKNOWN"

  - `payment_instrument_verification_details.name_verification_results.middle_name` (string)
    The result of verifying the cardholder's middle name.
    Enum: "MATCH", "MATCHED", "NO_MATCH", "NOT_SUPPORTED", "PARTIAL_MATCH", "UNKNOWN"

  - `payment_instrument_verification_details.name_verification_results.name` (string)
    The result of verifying the cardholder's full name.
    Enum: "MATCH", "MATCHED", "NO_MATCH", "NOT_SUPPORTED", "PARTIAL_MATCH", "UNKNOWN"

  - `processor` (string)
    Name of the verification processor.
    Enum: "FINIX_V1", "DUMMY_V1"

  - `raw` (any)
    Raw response from the processor. For SELLER Merchants, please use the newer outcomes and outcome_summary fields.

  - `reverification_reason` (object,null)
    The reason the merchant was re-verified.

  - `reverification_reason.initiated_by` (string,null)
    The initiator of the re-verification.

  - `reverification_reason.reason_description` (string,null)
    A description of the reason for re-verification.

  - `reverification_reason.review_type` (string,null)
    The type of review.

  - `state` (string)
    The state of the verification request.
    Enum: "PENDING", "FAILED", "SUCCEEDED"

  - `tags` (object,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)

  - `trace_id` (string)
    An ID used for tracking the verification request.

  - `type` (string)
    Details the type of resource getting verified.
    Enum: "MERCHANT"

  - `sub_type` (string,null)
    Specifies the [Gateway Integration](/api/gateway-integrations) linked to the [Merchant](/api/merchants). If the merchant is not linked to a Gateway Integration, this field will be null. At this time, CYBERSOURCE is the only supported Gateway Integration.
    Enum: "CYBERSOURCE"

  - `_links` (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.

  - `_links.self` (object)
    Link to the Verification.

  - `_links.self.href` (string)

  - `_links.merchant` (object)
    Link to the Merchant sent in the verification request.

  - `_links.merchant.href` (string)

  - `_links.application` (object)
    Link to the Application associated with this resource.

  - `_links.application.href` (string)

## Response 400 fields (application/json):

  - `total` (integer, required)
    Total number of errors returned.

  - `_embedded` (object, required)
    Container for embedded error objects.

  - `_embedded.errors` (array)
    List of individual error objects.

  - `_embedded.errors.code` (string)
    The error code. The UNKNOWN error code is returned for a 401 Unauthorized or 403 Forbidden request.

  - `_embedded.errors.logref` (string)
    A log reference identifier for the error, useful for debugging and support purposes.

  - `_embedded.errors.message` (string)
    A human-friendly error message.

  - `_embedded.errors._links` (object)
    Links related to this error.

  - `_embedded.errors._links.self` (object)
    Link to the resource related to the error.

  - `_embedded.errors._links.self.href` (string)
    URL of the related resource.

## Response 401 fields (application/json):

  - `total` (integer, required)
    Total number of errors returned.

  - `_embedded` (object, required)
    Container for embedded error objects.

  - `_embedded.errors` (array)
    List of individual error objects.

  - `_embedded.errors.code` (string)
    The error code. The UNKNOWN error code is returned for a 401 Unauthorized or 403 Forbidden request.

  - `_embedded.errors.logref` (string)
    A log reference identifier for the error, useful for debugging and support purposes.

  - `_embedded.errors.message` (string)
    A human-friendly error message.

  - `_embedded.errors._links` (object)
    Links related to this error.

  - `_embedded.errors._links.self` (object)
    Link to the resource related to the error.

  - `_embedded.errors._links.self.href` (string)
    URL of the related resource.

## Response 403 fields (application/json):

  - `total` (integer, required)
    Total number of errors returned.

  - `_embedded` (object, required)
    Container for embedded error objects.

  - `_embedded.errors` (array)
    List of individual error objects.

  - `_embedded.errors.code` (string)
    The error code. The UNKNOWN error code is returned for a 401 Unauthorized or 403 Forbidden request.

  - `_embedded.errors.logref` (string)
    A log reference identifier for the error, useful for debugging and support purposes.

  - `_embedded.errors.message` (string)
    A human-friendly error message.

  - `_embedded.errors._links` (object)
    Links related to this error.

  - `_embedded.errors._links.self` (object)
    Link to the resource related to the error.

  - `_embedded.errors._links.self.href` (string)
    URL of the related resource.

## Response 406 fields (application/json):

  - `total` (integer, required)
    Total number of errors returned.

  - `_embedded` (object, required)
    Container for embedded error objects.

  - `_embedded.errors` (array)
    List of individual error objects.

  - `_embedded.errors.code` (string)
    The error code. The UNKNOWN error code is returned for a 401 Unauthorized or 403 Forbidden request.

  - `_embedded.errors.logref` (string)
    A log reference identifier for the error, useful for debugging and support purposes.

  - `_embedded.errors.message` (string)
    A human-friendly error message.

  - `_embedded.errors._links` (object)
    Links related to this error.

  - `_embedded.errors._links.self` (object)
    Link to the resource related to the error.

  - `_embedded.errors._links.self.href` (string)
    URL of the related resource.