docs/api-guides/MERCHANT_API_EXAMPLES.md

Merchant API - cURL Examples

Base URL

BASE_URL="http://localhost:8001/api/v1"

1. Create Merchant (Draft)

curl -X POST "$BASE_URL/merchants" \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_type": "retail",
    "parent_merchant_id": "mch_parent_001",
    "merchant_code": "retail-MUM-001",
    "merchant_name": "Glamour retail Mumbai",
    "contact": {
      "phone": "+919876543210",
      "email": "contact@glamourretail.com",
      "address_line1": "123 Main Street",
      "city": "Mumbai",
      "state": "Maharashtra",
      "pincode": "400001",
      "country": "India"
    },
    "geo_location": {
      "lat": 19.0760,
      "lng": 72.8777
    },
    "status": "draft",
    "created_by": "admin_001"
  }'

2. View Merchant

curl -X GET "$BASE_URL/merchants/{merchant_id}"

3. Update Merchant

curl -X PUT "$BASE_URL/merchants/{merchant_id}" \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_name": "Updated retail Name",
    "status": "draft"
  }'

4. List Merchants (with projection)

curl -X POST "$BASE_URL/merchants/list" \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_type": "retail",
    "status": "active",
    "skip": 0,
    "limit": 100,
    "projection_list": ["merchant_id", "merchant_name", "merchant_type", "status"]
  }'

5. Upload KYC

curl -X POST "$BASE_URL/merchants/{merchant_id}/kyc" \
  -H "Content-Type: application/json" \
  -d '{
    "pan_number": "AAPFU0939F",
    "business_certificate_url": "https://storage.example.com/cert123.pdf"
  }'

6. Update KYC

curl -X PUT "$BASE_URL/merchants/{merchant_id}/kyc" \
  -H "Content-Type: application/json" \
  -d '{
    "gst_number": "27AAPFU0939F1ZV",
    "bank_account_number": "1234567890123",
    "bank_ifsc": "HDFC0001234",
    "cancelled_cheque_url": "https://storage.example.com/cheque123.jpg"
  }'

7. Submit for Verification

curl -X POST "$BASE_URL/merchants/{merchant_id}/submit"

8. Approve Merchant

curl -X POST "$BASE_URL/merchants/{merchant_id}/approve" \
  -H "Content-Type: application/json" \
  -d '{
    "approved_by": "admin_001",
    "reason": "All documents verified successfully"
  }'

9. Reject Merchant

curl -X POST "$BASE_URL/merchants/{merchant_id}/reject" \
  -H "Content-Type: application/json" \
  -d '{
    "rejected_by": "admin_001",
    "reason": "Incomplete documentation"
  }'

10. Bulk Upload Merchants

curl -X POST "$BASE_URL/merchants/bulk-upload" \
  -H "Content-Type: application/json" \
  -d '{
    "merchants": [
      {
        "merchant_type": "retail",
        "parent_merchant_id": "mch_parent_001",
        "merchant_code": "retail-MUM-001",
        "merchant_name": "retail 1",
        "contact": {
          "phone": "+919876543210",
          "email": "retail1@example.com",
          "address_line1": "123 Street",
          "city": "Mumbai",
          "state": "Maharashtra",
          "pincode": "400001",
          "country": "India"
        },
        "geo_location": {
          "lat": 19.0760,
          "lng": 72.8777
        },
        "kyc": {
          "pan_number": "AAPFU0939F"
        },
        "created_by": "admin_001"
      },
      {
        "merchant_type": "retail",
        "parent_merchant_id": "mch_parent_001",
        "merchant_code": "retail-MUM-002",
        "merchant_name": "retail 2",
        "contact": {
          "phone": "+919876543211",
          "email": "retail2@example.com",
          "address_line1": "456 Street",
          "city": "Mumbai",
          "state": "Maharashtra",
          "pincode": "400001",
          "country": "India"
        },
        "geo_location": {
          "lat": 19.0760,
          "lng": 72.8777
        },
        "kyc": {
          "pan_number": "BBBFU0939F"
        },
        "created_by": "admin_001"
      }
    ],
    "skip_errors": true
  }'

11. Get Merchant Children

curl -X GET "$BASE_URL/merchants/{merchant_id}/children?status=active&skip=0&limit=100"

12. Get Merchant Hierarchy

curl -X GET "$BASE_URL/merchants/{merchant_id}/hierarchy"

13. Delete Merchant (Soft Delete)

curl -X DELETE "$BASE_URL/merchants/{merchant_id}"

Complete Workflow Example

# Step 1: Create merchant
MERCHANT_ID=$(curl -s -X POST "$BASE_URL/merchants" \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_type": "retail",
    "parent_merchant_id": "mch_parent_001",
    "merchant_code": "WORKFLOW-TEST-001",
    "merchant_name": "Workflow Test retail",
    "contact": {
      "phone": "+919876543210",
      "email": "workflow@test.com",
      "address_line1": "123 Test Street",
      "city": "Mumbai",
      "state": "Maharashtra",
      "pincode": "400001",
      "country": "India"
    },
    "geo_location": {
      "lat": 19.0760,
      "lng": 72.8777
    },
    "status": "draft",
    "created_by": "admin_001"
  }' | jq -r '.merchant_id')

echo "Created merchant: $MERCHANT_ID"

# Step 2: Upload KYC
curl -s -X POST "$BASE_URL/merchants/$MERCHANT_ID/kyc" \
  -H "Content-Type: application/json" \
  -d '{
    "pan_number": "AAPFU0939F"
  }' | jq '.kyc'

# Step 3: Submit for verification
curl -s -X POST "$BASE_URL/merchants/$MERCHANT_ID/submit" | jq '.status'

# Step 4: Approve
curl -s -X POST "$BASE_URL/merchants/$MERCHANT_ID/approve" \
  -H "Content-Type: application/json" \
  -d '{
    "approved_by": "admin_001",
    "reason": "Verified successfully"
  }' | jq '{merchant_id, status, metadata}'

Using jq for Pretty Output

All examples can be piped through jq for formatted JSON output:

curl -X GET "$BASE_URL/merchants/{merchant_id}" | jq '.'

Error Handling Examples

Missing Required KYC

# This will fail if PAN is not provided for retail
curl -X POST "$BASE_URL/merchants/{merchant_id}/submit"
# Response: {"detail": "Missing required KYC field for retail: pan_number"}

Invalid Status Transition

# This will fail if merchant is not in submitted status
curl -X POST "$BASE_URL/merchants/{merchant_id}/approve"
# Response: {"detail": "Can only approve merchants in submitted status. Current status: draft"}

Duplicate Merchant Code

# This will fail if merchant_code already exists
curl -X POST "$BASE_URL/merchants" -d '{"merchant_code": "EXISTING-CODE", ...}'
# Response: {"detail": "merchant_code already exists within the parent scope"}