Skip to main content

Verify a Merchant

Overview​

Create a new Verification on a Merchant to complete the underwriting process and get them APPROVED to process payments or receive payouts. This endpoint initiates the verification process that reviews the Merchant's business information.

Resource Access​

  • User Permissions: Admin users only
  • Endpoint: POST /merchants/\{merchant_id}/verifications

Arguments​

ParameterTypeRequiredDescription
merchant_idstringYesThe unique ID of the Merchant to verify
Finix-VersionstringYesAPI version header (default: 2022-02-01)

Request Body: An empty JSON object {} is typically sent to trigger the verification process.

Example Request​

curl -X POST \
  'https://api.ahrvo.network/payments/na/merchants/MUmerchantExample123/verifications' \
  -u username:password \
  -H 'Content-Type: application/json' \
  -H 'Finix-Version: 2022-02-01' \
  -d '{}'

Example Response​

{
  "id": "VIverificationExample123",
  "state": "PENDING",
  "merchant": "MUmerchantExample123",
  "type": "MERCHANT",
  "created_at": "2023-06-15T11:00:00Z",
  "updated_at": "2023-06-15T11:00:00Z",
  "messages": [],
  "raw": null,
  "processor": "DUMMY_V1",
  "tags": {},
  "_links": {
    "self": {
      "href": "https://api.ahrvo.network/payments/na/verifications/VIverificationExample123"
    },
    "merchant": {
      "href": "https://api.ahrvo.network/payments/na/merchants/MUmerchantExample123"
    }
  }
}

Successful Verification Response​

After the verification completes successfully, fetching the Merchant will show:

{
  "id": "MUmerchantExample123",
  "onboarding_state": "APPROVED",
  "processing_enabled": true,
  "settlement_enabled": true,
  "mid": "987654321",
  ...
}

Failed Verification Response​

If verification fails, the Verification object will indicate the failure:

{
  "id": "VIverificationExample123",
  "state": "FAILED",
  "merchant": "MUmerchantExample123",
  "messages": [
    "Invalid tax identification number",
    "Business address could not be verified"
  ],
  ...
}

Additional Information​

  • Verification States:
    • PENDING: Verification is in progress
    • SUCCEEDED: Verification completed successfully, Merchant is APPROVED
    • FAILED: Verification failed, review messages for details
  • Approval Process:
    • In sandbox environments (DUMMY_V1), verifications typically succeed immediately
    • In production, verification can take minutes to hours depending on the processor
    • Some processors may require additional documentation or manual review
  • Merchant State Changes: When verification succeeds:
    • onboarding_state changes from PROVISIONING to APPROVED
    • processing_enabled is set to true
    • settlement_enabled is set to true
    • Processor assigns a mid (Merchant ID)
  • Failure Reasons: Common verification failures include:
    • Invalid or mismatched tax identification numbers
    • Business address cannot be verified
    • Prohibited business types or industries
    • Negative credit/background checks
    • Incomplete or inaccurate business information
  • Retry Policy: If verification fails, you may need to update the Identity with correct information before creating a new verification
  • Multiple Verifications: You can create multiple verifications if previous ones fail, but only after addressing the issues noted in the failure messages