Getting Started with Connect

This guide walks through the end-to-end happy path: provision your marketplace, onboard a single sub-merchant, accept a payment on their behalf, and pay them out.

1. Request Connect access

Send Inflow ops:

the production-mode business email of your Inflow account
your intended fee model (rate + fixed) — see Fees and Payouts
the redirect URL you want to use after KYC completes (can be overridden per call)

Once approved, your account is upgraded to a marketplace and seeded with sensible defaults (24h payout window, 2.5% take rate, USDC + EURC enabled, etc.). You can tune those at any time — see Marketplace Settings.

You'll authenticate to Connect with the same X-Inflow-Api-Key: <inflow_apikey> header you use for the standard API. See Authentication & API Keys for the full key reference.

2. Verify access

curl https://api.inflowpay.xyz/api/connect/status \
  -H "X-Inflow-Api-Key: $INFLOW_API_KEY"

{ "ok": true, "marketplaceUserId": "usr_…", "onBehalfOf": null }

If you get 403 ON_BEHALF_FORBIDDEN_CALLER_TYPE or 403 Only marketplace accounts can access Connect API routes, your account isn't yet a marketplace — go back to step 1.

If you get 403 MARKETPLACE_PAUSED or 403 CONNECT_DISABLED, your access has been frozen; contact support.

3. Read your settings

curl https://api.inflowpay.xyz/api/connect/settings \
  -H "X-Inflow-Api-Key: $INFLOW_API_KEY"

You'll get back your current settings. Tune them with PATCH /api/connect/settings if needed — see Marketplace Settings for what's editable and what isn't.

4. Create your first sub-merchant

curl -X POST https://api.inflowpay.xyz/api/connect/accounts \
  -H "X-Inflow-Api-Key: $INFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "merchantName": "Acme Coffee",
    "bridgeCustomerType": "individual",
    "firstName": "Jane",
    "lastName": "Doe",
    "redirectUrlKyc": "https://marketplace.example.com/connect/kyc-complete"
  }'

The response includes id (the sub-merchant user id — use this as $SUB in X-On-Behalf-Of), kycStatus: "pending", and a unified nextUrl + nextSteps contract describing how to drive KYC forward. See Sub-merchant Onboarding for details.

5. Drive KYC to completion

Redirect the seller to nextUrl. They'll complete KYC (for individuals) or KYB (for businesses).

While they verify, poll:

curl "https://api.inflowpay.xyz/api/connect/accounts/$SUB/kyc/status" \
  -H "X-Inflow-Api-Key: $INFLOW_API_KEY"

When kycReady is true on the KYC status response (and walletId is set), the sub-merchant is fully operable and ready to transact. See KYC Flow for the full state machine.

6. Accept a payment on the sub-merchant's behalf

Once kycReady is true, the sub-merchant can transact. The marketplace adds the X-On-Behalf-Of header on every merchant-scoped call:

curl -X POST https://api.inflowpay.xyz/api/payment \
  -H "X-Inflow-Api-Key: $INFLOW_API_KEY" \
  -H "X-On-Behalf-Of: $SUB" \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "EUR",
    "successUrl": "https://shop.example.com/success",
    "cancelUrl":  "https://shop.example.com/cancel",
    "products": [
      { "name": "Subscription Plan", "price": 5000, "quantity": 1 }
    ]
  }'

Product price is in cents; the total amount is computed as the sum of price * quantity across products. The response is { paymentId, purchaseUrl }; redirect the buyer to purchaseUrl (or embed the SDK iframe with paymentId).

The customer pays through Inflow's hosted checkout. On success, Inflow:

Credits the sub-merchant's balance (net of fees).
Routes your marketplace fee to your marketplace balance.
Settles Inflow's own fees.

See Fees and Payouts for the math and timing.

7. Pay the sub-merchant out

When the sub-merchant requests withdrawal, route through the existing payout API with the same header:

curl -X POST https://api.inflowpay.xyz/api/payout \
  -H "X-Inflow-Api-Key: $INFLOW_API_KEY" \
  -H "X-On-Behalf-Of: $SUB" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId":     "bank_1234567890abcdef",
    "amountInCents": 50000,
    "currency":      "USDC",
    "network":       "base"
  }'

accountId references a payout destination (bank or wallet) that already belongs to the sub-merchant. currency is one of USDC or EURC. network is required only when the destination is a crypto wallet (avalanche, base, polygon, ethereum, solana, arbitrum).

Available balance is the sub-merchant's balance, minus any payins still inside the payout window. See Fees and Payouts for the window semantics.