Create a Merchant

Overview

Create a Merchant resource under an existing Identity to begin the underwriting process. A Merchant represents a seller's payment processing account on a processor and must be APPROVED to process payments.

Resource Access

• User Permissions: Admin users only
• Endpoint: POST /identities/\{identity_id}/merchants

Arguments

Parameter	Type	Required	Description
identity_id	string	Yes	The unique ID of the Identity under which to create the Merchant
processor	string	Yes	The payment processor to use (e.g., DUMMY_V1, LITLE_V1)
gateway	string	No	Required for Card Present processing (e.g., DATACAP_V1, TRIPOS_CLOUD_V1)
loan_repayment	boolean	No	Enable Loan Repayment functionality
tags	object	No	Custom key-value metadata for the Merchant

Example Request

curl -X POST \
  'https://api.ahrvo.network/payments/na/identities/IDentityExample123/merchants' \
  -u username:password \
  -H 'Content-Type: application/json' \
  -d '{
    "processor": "DUMMY_V1",
    "gateway": "DATACAP_V1",
    "loan_repayment": true,
    "tags": {
      "business_type": "retail",
      "location": "downtown"
    }
  }'

Example Response

{
  "id": "MUmerchantExample123",
  "created_at": "2023-06-15T10:30:00Z",
  "updated_at": "2023-06-15T10:30:00Z",
  "application": "APapplicationExample123",
  "identity": "IDentityExample123",
  "processor": "DUMMY_V1",
  "gateway": "DATACAP_V1",
  "mid": null,
  "merchant_name": "Acme Retail Store",
  "mcc": "5411",
  "country": "USA",
  "currencies": ["USD"],
  "onboarding_state": "PROVISIONING",
  "processing_enabled": false,
  "settlement_enabled": false,
  "is_terminated": false,
  "loan_repayment": true,
  "level_two_level_three_data_enabled": false,
  "convenience_charges_enabled": false,
  "settlement_queue_mode": "UNSET",
  "tags": {
    "business_type": "retail",
    "location": "downtown"
  },
  "termination_details": null,
  "_links": {
    "self": {
      "href": "https://api.ahrvo.network/payments/na/merchants/MUmerchantExample123"
    },
    "identity": {
      "href": "https://api.ahrvo.network/payments/na/identities/IDentityExample123"
    },
    "verifications": {
      "href": "https://api.ahrvo.network/payments/na/merchants/MUmerchantExample123/verifications"
    }
  }
}

Additional Information

• Onboarding States:
  • PROVISIONING: Initial state after creation
  • APPROVED: Merchant has been verified and can process payments
  • FAILED: Underwriting verification failed
• Processor Selection: The processor must be supported by your Application. Common processors include DUMMY_V1 (sandbox), LITLE_V1, and others
• Card Present Processing: If you plan to process in-person card payments, you must specify a gateway (e.g., DATACAP_V1 or TRIPOS_CLOUD_V1)
• Verification Required: After creating a Merchant, you must create a Verification to complete underwriting and enable payment processing
• Identity Association: The Merchant inherits business details (name, address, tax ID) from the associated Identity
• Merchant Category Code (MCC): Automatically assigned based on the business information in the Identity