# Onboard a merchant

Allows platforms to onboard a new merchant onto Glomo.

Endpoint: POST /platform/merchants
Version: 1.0.0
Security: JWT

## Security:

  - `JWT` (unknown)
    http bearer JWT

## Request fields (application/json):

  - `name` (string, required)
    Name of the merchant business
    Example: Child Business Name

  - `address_line1` (string, required)
    Primary address line
    Example: 456 Commerce Street

  - `address_line2` (string)
    Secondary address line (optional)
    Example: Suite 101

  - `city` (string, required)
    City name
    Example: Mumbai

  - `state` (string, required)
    State or province
    Example: Maharashtra

  - `pincode` (string, required)
    Postal/ZIP code
    Example: 400001

  - `registration_number` (string, required)
    Business registration number
    Example: REG123456

  - `registration_country` (string, required)
    Country where the business is registered (ISO 3166-1 alpha-3)
    Example: IND

  - `category` (string, required)
    Merchant business category
    Enum: "Agricultural Services", "Contracted Services", "Transportation Services", "Telecommunications", "Utilities", "Retail and Goods", "Financial Services", "Business Services", "Professional Services", "Government Services"

  - `sub_category` (string, required)
    Merchant business sub-category (must be paired with correct category, check examples)
    Enum: "Veterinary Services", "Agricultural Cooperatives", "Horticultural and Landscaping Services", "General Contractors—Residential and Commercial", "Air Conditioning Heating and Plumbing Contractors", "Electrical Contractors", "Insulation Masonry Plastering Stonework and Tile Setting Contractors", "Carpentry Contractors", "Roofing and Siding Sheet Metal Work Contractors", "Concrete Work Contractors", "Contractors Special Trade—not elsewhere classified", "Miscellaneous Publishing and Printing", "Typesetting Plate Making and Related Services", "Sanitation Polishing and Specialty Cleaning Preparations", "Railroads—Freight", "Transportation—Suburban and Local Commuter Passenger including Ferries", "Passenger Railways", "Ambulance Services", "Limousines and Taxicabs", "Bus Lines", "Motor Freight Carriers Trucking—Local/Long Distance Moving and Storage Companies Local Delivery", "Courier Services—Air and Ground Freight Forwarders", "Public Warehousing—Farm Products Refrigerated Goods Household Goods Storage", "Cruise Lines", "Boat Leases and Boat Rentals", "Marinas Marine Service/Supplies", "Air Carriers Airlines—Not Elsewhere Classified", "Airports Airport Terminals Flying Fields", "Travel Agencies and Tour Operators", "Bridge and Road Fees Tolls", "Transportation Services—not elsewhere classified", "Telecommunication Equipment Including Telephone Sales", "Key-entry Telecom Merchant providing single local and long-distance phone calls using a central access number in a non-face-to-face environment using key entry", "Telecommunication Services including but not limited to prepaid phone services and recurring phone services", "Computer Network/Information Services", "Telegraph Services", "Money Transfer", "Cable Satellite and Other Pay Television and Radio Services", "Utilities—Electric Gas Heating Oil Sanitary Water", "Motor Vehicle Supplies and New Parts", "Office and Commercial Furniture", "Construction Materials—not elsewhere classified", "Office Photographic Photocopy and Microfilm Equipment", "Computers Computer Peripheral Equipment Software", "Commercial Equipment—not elsewhere classified", "Dental/Laboratory/Medical/Ophthalmic Hospital Equipment and Supplies", "Metal Service Centers and Offices", "Electrical Parts and Equipment", "Hardware Equipment and Supplies", "Plumbing and Heating Equipment", "Industrial Supplies—not elsewhere classified", "Precious Stones and Metals Watches and Jewelry", "Durable Goods—not elsewhere classified", "Stationery Office Supplies Printing and Writing Paper", "Drugs Drug Proprietors and Druggists Sundries", "Piece Goods Notions and Other Dry Goods", "Men's Women's and Children's Uniforms and Commercial Clothing", "Commercial Footwear", "Chemicals and Allied Products—not elsewhere classified", "Petroleum and Petroleum Products", "Books Periodicals and Newspapers", "Florists Supplies Nursery Stock and Flowers", "Paints Varnishes and Supplies", "Nondurable Goods—not elsewhere classified", "Home Supply Warehouse Stores", "Building Materials Lumber Stores", "Glass Paint Wallpaper Stores", "Hardware Stores", "Lawn and Garden Supply Stores", "Mobile Home Dealers", "Wholesale Clubs", "Duty Free Stores", "Discount Stores", "Department Stores", "Variety Stores", "Miscellaneous General Merchandise Stores", "Grocery Stores Supermarkets", "Freezer Locker Meat Provisioners", "Candy Nut Confectionery Stores", "Dairy Products Stores", "Bakeries", "Miscellaneous Food Stores—Convenience Stores Markets Specialty Stores", "Automobile and Truck Dealers—Sales Service Repairs Parts and Leasing", "Automobile and Truck Dealers—(Used Only)—Sales", "Auto Store Home Supply Stores", "Automotive Tire Stores", "Automotive Parts Accessories Stores", "Service Stations (with or without Ancillary Services)", "Fuel Dispenser Automated", "Boat Dealers", "Camper Dealers Recreational and Utility Trailers", "Motorcycle Shops and Dealers", "Motor Home Dealers", "Snowmobile Dealers", "Miscellaneous Automotive Aircraft and Farm Equipment Dealers—not elsewhere classified", "Men's and Boys' Clothing and Accessories Stores", "Women's Ready to Wear Stores", "Women's Accessory and Specialty Stores", "Children's and Infants' Wear Stores", "Family Clothing Stores", "Sports Apparel Riding Apparel Stores", "Shoe Stores", "Furriers and Fur Shops", "Men's and Women's Clothing Stores", "Alterations Mending Seamstresses Tailors", "Wig and Toupee Shops", "Accessory and Apparel Stores—Miscellaneous", "Equipment Furniture and Home Furnishings Stores (except Appliances)", "Floor Covering Stores", "Drapery Upholstery and Window Coverings Stores", "Fireplace Fireplace Screens and Accessories Stores", "Miscellaneous House Furnishing Specialty Shops", "Household Appliance Stores", "Electronic Sales", "Music Stores—Musical Instruments Pianos Sheet Music", "Computer Software Stores", "Record Shops", "Caterers", "Eating Places Restaurants", "Bars Cocktail Lounges Discotheques Nightclubs and Taverns—Drinking Places (Alcoholic Beverages)", "Fast Food Restaurants", "Digital Goods—Audiovisual Media Including Books Movies and Music", "Digital Goods—Games", "Digital Goods—Software Applications (Excluding Games)", "Digital Goods—Multi-Category", "Drug Stores Pharmacies", "Package Stores Beer Wine and Liquor", "Second Hand Stores Used Merchandise Stores", "Antique Shops—Sales Repairs and Restoration Services", "Pawn Shops", "Salvage and Wrecking Yards", "Antique Reproduction Stores", "Bicycle Shops—Sales and Service", "Sporting Goods Stores", "Book Stores", "Office School Supply and Stationery Stores", "Clock Jewelry Watch and Silverware Store", "Game Toy and Hobby Shops", "Camera and Photographic Supply Stores", "Card Gift Novelty and Souvenir Shops", "Leather Goods and Luggage Stores", "Fabric Needlework Piece Goods and Sewing Stores", "Crystal and Glassware Stores", "Direct Marketing—Insurance Services", "Direct Marketing—Travel-Related Arrangement Services", "Door-to-Door Sales", "Direct Marketing—Catalog Merchants", "Direct Marketing—Combination Catalog and Retail Merchants", "Direct Marketing—Outbound Telemarketing Merchants", "Direct Marketing—Inbound Telemarketing Merchants", "Direct Marketing—Continuity/Subscription Merchants", "Direct Marketing—Other Direct Marketers—not elsewhere classified", "Artist Supply Stores Craft Shops", "Art Dealers and Galleries", "Stamp and Coin Stores—Philatelic and Numismatic Supplies", "Religious Goods Stores", "Hearing Aids—Sales Service Supply Stores", "Orthopedic Goods—Artificial Limb Stores", "Cosmetic Stores", "Typewriter Stores—Rentals Sales Service", "Fuel Dealers—Coal Fuel Oil Liquefied Petroleum Wood", "Florists", "Cigar Stores and Stands", "News Dealers and Newsstands", "Pet Shops—Pet Food and Supplies", "Swimming Pools—Sales and Supplies", "Electric Razor Stores—Sales and Service", "Tent and Awning Shops", "Miscellaneous and Specialty Retail Stores", "Manual Cash Disbursements—Customer Financial Institution", "Automated Cash Disbursements—Customer Financial Institution", "Merchandise and Services—Customer Financial Institution", "Quasi Cash—Customer Financial Institution", "Quasi Cash—Merchant", "Securities—Brokers/Dealers", "Insurance Sales Underwriting and Premiums", "Real Estate Agents and Managers—Rentals", "Payment Transaction—Customer Financial Institution", "Payment Transaction—Merchant", "MoneySend Intracountry", "MoneySend Intercountry", "MoneySend Funding", "POI Funding Transactions (Excluding MoneySend)", "Lodging—Hotels Motels Resorts—not elsewhere classified", "Timeshares", "Recreational and Sporting Camps", "Campgrounds and Trailer Parks", "Cleaning Garment and Laundry Services", "Laundry Services—Family and Commercial", "Dry Cleaners", "Carpet and Upholstery Cleaning", "Photographic Studios", "Barber and Beauty Shops", "Hat Cleaning Shops Shoe Repair Shops Shoe Shine Parlors", "Funeral Service and Crematories", "Dating Services", "Tax Preparation Service", "Debt Marriage Personal—Counseling Service", "Buying/Shopping Clubs Services", "Clothing Rental—Costumes Uniforms and Formal Wear", "Massage Parlors", "Health and Beauty Spas", "Other Services—not elsewhere classified", "Advertising Services", "Consumer Credit Reporting Agencies", "Commercial Art Graphics Photography", "Quick Copy Reproduction and Blueprinting Services", "Stenographic and Secretarial Support Services", "Exterminating and Disinfecting Services", "Cleaning and Maintenance Janitorial Services", "Employment Agencies Temporary Help Services", "Computer Programming Data Processing and Integrated Systems Design Services", "Information Retrieval Services", "Computer Maintenance Repair and Services—not elsewhere classified", "Consulting Management and Public Relations Services", "Detective Agencies Protective Agencies Security Services including Armored Cars Guard Dogs", "Equipment Rental and Leasing Services Furniture Rental Tool Rental", "Photo Developing Photofinishing Laboratories", "Business Services—not elsewhere classified", "Automobile Rental Agency—not elsewhere classified", "Truck Rental", "Motor Home and Recreational Vehicle Rental", "Automobile Parking Lots and Garages", "Automotive Body Repair Shops", "Tire Retreading and Repair Shops", "Automotive Paint Shops", "Automotive Service Shops", "Car Washes", "Towing Services", "Electronic Repair Shops", "Air Conditioning and Refrigeration Repair Shops", "Appliance Repair Shops Electrical and Small", "Clock Jewelry and Watch Repair Shops", "Furniture—Reupholstery and Repair Refinishing", "Welding Repair", "Miscellaneous Repair Shops and Related Services", "Government Owned Lottery (U.S. Region Only)", "Internet Gambling (U.S. Region Only)", "Government Licensed Horse/Dog Racing (U.S. Region Only)", "Motion Picture and Video Tape Production and Distribution", "Motion Picture Theaters", "Video Entertainment Rental Stores", "Dance Halls Schools and Studios", "Theatrical Producers (except Motion Pictures) Ticket Agencies", "Bands Orchestras and Miscellaneous Entertainers—not elsewhere classified", "Pool and Billiard Establishments", "Bowling Alleys", "Athletic Fields Commercial Sports Professional Sports Clubs Sports Promoters", "Tourist Attractions and Exhibits", "Golf Courses Public", "Video Amusement Game Supplies", "Video Game Arcades/Establishments", "Gambling Transactions", "Amusement Parks Carnivals Circuses Fortune Tellers", "Clubs—Country Clubs Membership (Athletic Recreation Sports) Private Golf Courses", "Aquariums Dolphinariums Zoos and Seaquariums", "Recreation Services—not elsewhere classified", "Doctors—not elsewhere classified", "Dentists Orthodontists", "Osteopathic Physicians", "Chiropractors", "Optometrists Ophthalmologists", "Opticians Optical Goods and Eyeglasses", "Chiropodists Podiatrists", "Nursing and Personal Care Facilities", "Hospitals", "Dental and Medical Laboratories", "Health Practitioners Medical Services—not elsewhere classified", "Attorneys Legal Services", "Schools Elementary and Secondary", "Colleges Universities Professional Schools and Junior Colleges", "Schools Correspondence", "Schools Business and Secretarial", "Schools Trade and Vocational", "Schools and Educational Services—not elsewhere classified", "Child Care Services", "Organizations Charitable and Social Service", "Associations—Civic Social and Fraternal", "Organizations Political", "Organizations Religious", "Automobile Associations", "Organizations Membership—not elsewhere classified", "Testing Laboratories (Non-Medical)", "Architectural Engineering and Surveying Services", "Accounting Auditing and Bookkeeping Services", "Professional Services—not elsewhere classified", "Court Costs including Alimony and Child Support", "Fines", "Bail and Bond Payments", "Tax Payments", "Government Services—not elsewhere classified", "Postal Services—Government Only", "Intra-Government Purchases—Government Only", "Government-owned Lottery (Specific Countries)"

  - `operation_countries` (array, required)
    List of countries where the merchant operates
    Example: ["IND","USA"]

  - `entity_type` (string, required)
    Type of entity
    Enum: "individual"

  - `date_of_birth` (string, required)
    Date of birth. Format YYYY-MM-DD
    Example: 2001-08-04

  - `gender` (string, required)
    Gender
    Enum: "male", "female", "undefined"

  - `passport` (object, required)
    Passport identification

  - `passport.number` (string, required)
    Passport number
    Example: P1234567

  - `passport.expiry_date` (string, required)
    Passport expiry date. Must be a future date. Format YYYY-MM-DD
    Example: 2030-06-01

  - `passport.country_of_issuance` (string, required)
    Country that issued the passport (ISO 3166-1 alpha-3)
    Example: IND

  - `registration_date` (string, required)
    Business registration/incorporation date. Must be a past date. Format YYYY-MM-DD
    Example: 2020-06-01

  - `dba_name` (string, required)
    Trading (doing-business-as) name, if it differs from the registered name
    Example: Acme Retail

  - `business_type` (string, required)
    Legal type of the registered entity
    Enum: "corporation", "foreign_entity", "foundation", "government_entity", "huf", "llp", "non_profit_organization", "one_person_company", "partnership", "private_limited", "public_limited", "society", "sole_proprietorship", "trust", "unincorporated_association"

  - `registration_document_id` (string, required)
    ID of a document you previously uploaded via [Create a document](/api-reference/openapi/document/createdocument), used as the merchant's certificate of incorporation
    Example: doc_nYUqLpuYQ0M8

  - `website` (string, required)
    Public website of the merchant
    Example: https://acme.example.com

  - `annual_turnover` (string, required)
    Annual business turnover band, in USD
    Enum: "below_100k", "100k_to_1m", "1m_to_5m", "above_5m"

  - `ubos` (array, required)
    Ultimate beneficial owners of the merchant. `ownership_percentage` across all entries must not sum above 100.
    Example: [{"name":"Jane Doe","type":"individual","ownership_percentage":60,"country":"IND"},{"name":"Doe Holdings Pte Ltd","type":"company","ownership_percentage":40,"country":"SGP"}]

  - `ubos.name` (string, required)
    Full name of the individual, or legal name of the company
    Example: Jane Doe

  - `ubos.type` (string, required)
    Whether this owner is a natural person or a legal entity
    Enum: "individual", "company"

  - `ubos.ownership_percentage` (number, required)
    Share of the merchant held by this owner. Greater than 0 and at most 100.
    Example: 60

  - `ubos.country` (string, required)
    Nationality of the individual, or country of incorporation of the company (ISO 3166-1 alpha-3)
    Example: IND

## Request examples:

  - `Individual merchant` (unknown)

  - `Business merchant` (unknown)

## Response 201:

  - `201` (unknown)
    Merchant onboarded successfully

## Response 201 fields (application/json):

  - `message` (string)
    Success message
    Example: Merchant created successfully!

  - `data` (object)

  - `data.owner_merchant_id` (string, required)
    The ID of the platform/owner merchant
    Example: merch_68511919RVuf6

  - `data.merchant_id` (string, required)
    Unique identifier for the merchant
    Example: merch_68c777fcOOMpl

  - `data.status` (string, required)
    Current merchant status
    Enum: "created", "success", "action_required", "pending", "failed", "offboarded"

  - `data.name` (string, required)
    Name of the merchant
    Example: John Doe

  - `data.category` (string)
    Business category
    Example: Agricultural Services

  - `data.entity_type` (string)
    Type of merchant entity
    Enum: "individual", "business"

  - `data.sub_category` (string)
    Business sub-category (must be paired with correct category)
    Example: Veterinary Services

  - `data.gender` (string)
    Gender (only required for individual entity_type)
    Enum: "male", "female", "undefined"

  - `data.date_of_birth` (string)
    Date of birth (only required for individual entity_type)
    Example: 2001-08-04

  - `data.registration_number` (string, required)
    Business registration number or individual ID
    Example: REG123456

  - `data.registration_country` (string, required)
    Country where the merchant is registered (ISO 3166-1 alpha-3)
    Example: IND

  - `data.address` (object, required)
    Merchant address

  - `data.address.address_line1` (string, required)
    Primary address line
    Example: 123 Main St

  - `data.address.address_line2` (string)
    Secondary address line (optional)

  - `data.address.city` (string, required)
    City name
    Example: Bangalore

  - `data.address.state` (string, required)
    State or province
    Example: Karnataka

  - `data.address.pincode` (string, required)
    Postal/ZIP code
    Example: 560060

  - `data.address.country` (string, required)
    Country code (ISO 3166-1 alpha-3)
    Example: IND

  - `data.operation_countries` (array, required)
    List of countries where the merchant operates
    Example: ["IND"]

  - `data.created_at` (string, required)
    Timestamp when the merchant was created
    Example: 2025-10-07T06:11:47Z

  - `data.updated_at` (string, required)
    Timestamp when the merchant was last updated
    Example: 2025-10-07T06:11:47Z

  - `data.jwt_token` (string, required)
    JWT token for the merchant
    Example: child_merchant_JWT

  - `data.public_key` (string)
    public key for the merchant
    Example: live_6889e287VfqrPVPg

## Response 202:

  - `202` (unknown)
    Merchant has been created and submitted for KYB review. It is not active until the review is approved.

## Response 202 fields (application/json):

  - `message` (string)
    Review-pending message. The merchant is created in `created` status and stays there until the KYB review completes.
    Example: Merchant created and submitted for review. You will be notified once it is approved.

  - `data` (object)

  - `data.owner_merchant_id` (string, required)
    The ID of the platform/owner merchant
    Example: merch_68511919RVuf6

  - `data.merchant_id` (string, required)
    Unique identifier for the merchant
    Example: merch_68c777fcOOMpl

  - `data.status` (string, required)
    Status of the merchant onboarding. `created` while the KYB review is pending.
    Enum: "created"

  - `data.name` (string, required)
    Name of the merchant
    Example: John Doe

  - `data.category` (string)
    Business category
    Example: Agricultural Services

  - `data.entity_type` (string)
    Type of merchant entity
    Enum: "individual", "business"

  - `data.sub_category` (string)
    Business sub-category (must be paired with correct category)
    Example: Veterinary Services

  - `data.gender` (string)
    Gender (only required for individual entity_type)
    Enum: "male", "female", "undefined"

  - `data.date_of_birth` (string)
    Date of birth (only required for individual entity_type)
    Example: 2001-08-04

  - `data.registration_number` (string, required)
    Business registration number or individual ID
    Example: REG123456

  - `data.registration_country` (string, required)
    Country where the merchant is registered (ISO 3166-1 alpha-3)
    Example: IND

  - `data.address` (object, required)
    Merchant address

  - `data.address.address_line1` (string, required)
    Primary address line
    Example: 123 Main St

  - `data.address.address_line2` (string)
    Secondary address line (optional)

  - `data.address.city` (string, required)
    City name
    Example: Bangalore

  - `data.address.state` (string, required)
    State or province
    Example: Karnataka

  - `data.address.pincode` (string, required)
    Postal/ZIP code
    Example: 560060

  - `data.address.country` (string, required)
    Country code (ISO 3166-1 alpha-3)
    Example: IND

  - `data.operation_countries` (array, required)
    List of countries where the merchant operates
    Example: ["IND"]

  - `data.created_at` (string, required)
    Timestamp when the merchant was created
    Example: 2025-10-07T06:11:47Z

  - `data.updated_at` (string, required)
    Timestamp when the merchant was last updated
    Example: 2025-10-07T06:11:47Z

## Response 400:

  - `400` (unknown)
    Bad Request

## Response 400 fields (application/json):

  - `error` (string)
    Example: Bad Request

  - `message` (string)
    Example: Invalid request data

## Response 401:

  - `401` (unknown)
    Unauthorized

## Response 401 fields (application/json):

  - `error` (string)
    Example: Unauthorized

  - `message` (string)
    Example: Invalid or missing authentication token