Aggregate Merchant Provisioner

The aggregate merchant provisioner accepts merchant payloads, applies the partnership-PSP preset for the merchant’s region / cohort, and persists the merchant with PSP configuration already wired. This eliminates the historical 3-step dance (create merchant → write PSP config → flip KYB flag) that operators used to walk by hand.

All admin endpoints below require:

JWT with role = SUPER_ADMIN
IpAllowlistGuard — caller IP must be in the operator allowlist
GeoBlockGuard — caller geo must be permitted

Calls that miss any of the three return 403.

Partnership-PSP preset

Each merchant payload includes a partnership field. The provisioner reads the partnership registry and applies the matching preset:

Partnership	PSPs wired	Default MoR
`shopsadiq-telr-gcc`	Telr	Shopsadiq
`mcredit-bonum-mn`	Bonum	MCredit
`stripe-direct-us`	Stripe	Merchant
`paypal-direct-eu`	PayPal	Merchant
`aggregator-shopsadiq`	Stripe + PayPal + Telr	Shopsadiq
`aggregator-droplinked`	Stripe + PayPal	Droplinked

If partnership is omitted, the provisioner falls back to the region default (documented in the PSP × MoR cohort taxonomy).

POST /admin/aggregate-merchant-provisioner/single

Provisions one merchant.

Authentication

Guard	Requirement
JWT	Required, `role = SUPER_ADMIN`
IP allowlist	Caller IP in `ADMIN_IP_ALLOWLIST`
Geo	Country in `ADMIN_GEO_ALLOWLIST`

Request body

{
  "email": "founder@unstoppable.example",
  "shopName": "Unstoppable",
  "region": "GCC",
  "partnership": "shopsadiq-telr-gcc",
  "kybCohort": "A-MoR-Shopsadiq-via-Telr",
  "contact": {
    "fullName": "Test Operator",
    "phone": "+9715XXXXXXXX"
  },
  "options": {
    "skipKybVerification": false,
    "seedDemoProducts": true
  }
}

Field	Type	Required	Description
`email`	string	Yes	Merchant primary email; becomes the JWT `sub` for the owner
`shopName`	string	Yes	Storefront name; subdomain auto-generated from this
`region`	enum (`US` \| `EU` \| `GCC` \| `MN` \| `OTHER`)	Yes	Drives PSP defaults and FX rounding
`partnership`	string	No	Partnership preset key; falls back to region default
`kybCohort`	string	No	One of the 8 cohort enums; defaults to `A-Connect`
`contact.fullName`	string	Yes	Real name of the merchant contact
`contact.phone`	string	No	E.164 phone
`options.skipKybVerification`	boolean	No	Defaults `false`; only set `true` for internal test merchants
`options.seedDemoProducts`	boolean	No	Defaults `false`; seeds 3 demo SKUs for walkthrough demos

Response — 201 Created

{
  "merchantId": "65f8a1b2c3d4e5f6a7b8c9aa",
  "shopId": "65f8a1b2c3d4e5f6a7b8c9bb",
  "subdomain": "unstoppable",
  "ownerUserId": "65f8a1b2c3d4e5f6a7b8c9cc",
  "partnership": "shopsadiq-telr-gcc",
  "kybCohort": "A-MoR-Shopsadiq-via-Telr",
  "pspsProvisioned": ["telr"],
  "kybStatus": "PENDING",
  "seededProducts": 3,
  "invitationEmailSent": true
}

Error responses

Status	When
`400`	Missing/invalid field; unknown `partnership` key; unknown `kybCohort`
`403`	JWT / IP / geo guard failed
`409`	A merchant already exists at this email or subdomain

Example

curl -X POST \
  https://apiv3.droplinked.com/admin/aggregate-merchant-provisioner/single \
  -H "Authorization: Bearer <SUPER_ADMIN_JWT>" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "founder@unstoppable.example",
    "shopName": "Unstoppable",
    "region": "GCC",
    "partnership": "shopsadiq-telr-gcc",
    "kybCohort": "A-MoR-Shopsadiq-via-Telr",
    "contact": { "fullName": "Test Operator" }
  }'

POST /admin/aggregate-merchant-provisioner/bulk

Provisions an array of merchants. Each entry is attempted independently — a failure on one does not abort the batch. The response partitions results into successful and failed.

Request body

{
  "merchants": [
    { "email": "a@example.com", "shopName": "A", "region": "GCC", "partnership": "shopsadiq-telr-gcc", "contact": { "fullName": "A" } },
    { "email": "b@example.com", "shopName": "B", "region": "MN", "partnership": "mcredit-bonum-mn",   "contact": { "fullName": "B" } }
  ]
}

Field	Type	Required	Description
`merchants`	array (1-100)	Yes	Array of single-provisioner payloads

Response — 207 Multi-Status

{
  "submitted": 2,
  "successful": [
    {
      "index": 0,
      "email": "a@example.com",
      "merchantId": "65f8a1b2c3d4e5f6a7b8c9aa",
      "subdomain": "a"
    }
  ],
  "failed": [
    {
      "index": 1,
      "email": "b@example.com",
      "error": "Subdomain 'b' already taken",
      "code": "SUBDOMAIN_CONFLICT"
    }
  ]
}

Error responses

Status	When
`400`	Array empty, > 100 entries, or every entry is structurally invalid
`403`	JWT / IP / geo guard failed

The batch HTTP status is 207 Multi-Status whenever at least one entry succeeds and at least one fails; 201 when all succeed; 400 when all fail validation.

GET /admin/aggregate-merchant-provisioner/preview

Dry-run: validates payloads and resolves partnership presets, but does not write. Useful for “what would happen if I bulk-provisioned this CSV?” before committing. Accepts the same body shape as the bulk endpoint, sent via GET with the payload in the request body (Mintlify renders this — the backend reads JSON from the request body on this route specifically).

Response — 200 OK

{
  "submitted": 2,
  "wouldSucceed": [
    {
      "index": 0,
      "email": "a@example.com",
      "subdomain": "a",
      "pspsThatWouldProvision": ["telr"],
      "kybCohortResolved": "A-MoR-Shopsadiq-via-Telr"
    }
  ],
  "wouldFail": [
    {
      "index": 1,
      "email": "b@example.com",
      "error": "Subdomain 'b' already taken",
      "code": "SUBDOMAIN_CONFLICT"
    }
  ],
  "warnings": [
    "Merchant 'a@example.com' has no `kybCohort` — would default to `A-Connect` based on region GCC"
  ]
}

Example

curl -X GET \
  https://apiv3.droplinked.com/admin/aggregate-merchant-provisioner/preview \
  -H "Authorization: Bearer <SUPER_ADMIN_JWT>" \
  -H "Content-Type: application/json" \
  -d '{
    "merchants": [
      { "email": "a@example.com", "shopName": "A", "region": "GCC", "contact": { "fullName": "A" } }
    ]
  }'

Operational notes

Idempotency: the provisioner is not idempotent. Re-submitting the same email returns 409. Use the preview endpoint to scrub a CSV before running bulk.
Email invitations: the owner-user invitation email is sent synchronously on successful provision. If your operator workflow sends a custom welcome email, set options.skipInvitationEmail (boolean, default false).
Cohort routing: the kybCohort field flows downstream into the lending eligibility, cost-comparator, and affiliate-commission projections. Choose intentionally.

Bonum admin — per-merchant Bonum config (set after provisioning when partnership = mcredit-bonum-mn).
Telr admin — Telr reconcile for partnerships that wire Telr.
Network Health KPIs — track verified-shops + GMV growth after bulk provisioning.

OpenAPI Specification Bonum Admin

Overview

Admin API

Public API

Trust Fabric API

EAS Schemas (Trust Fabric)

Merchant API

AI Endpoints

Merchant

Customer

Shop

Product

Collection

SKU

Shipping

Gift Card

Blog

Cart

Order

Address Book

Partnership-PSP preset

POST /admin/aggregate-merchant-provisioner/single

Authentication

Request body

Response — 201 Created

Error responses

Example

POST /admin/aggregate-merchant-provisioner/bulk

Request body

Response — 207 Multi-Status

Error responses

GET /admin/aggregate-merchant-provisioner/preview

Response — 200 OK

Example

Operational notes

​Partnership-PSP preset

​POST /admin/aggregate-merchant-provisioner/single

​Authentication

​Request body

​Response — 201 Created

​Error responses

​Example

​POST /admin/aggregate-merchant-provisioner/bulk

​Request body

​Response — 207 Multi-Status

​Error responses

​GET /admin/aggregate-merchant-provisioner/preview

​Response — 200 OK

​Example

​Operational notes

​Related

Partnership-PSP preset

POST /admin/aggregate-merchant-provisioner/single

Authentication

Request body

Response — 201 Created

Error responses

Example

POST /admin/aggregate-merchant-provisioner/bulk

Request body

Response — 207 Multi-Status

Error responses

GET /admin/aggregate-merchant-provisioner/preview

Response — 200 OK

Example

Operational notes

Related