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 Authorization: Bearer <inflow_apikey> header you use for the standard API.

2. Verify access

curl https://api.inflowpay.xyz/api/connect/status \
  -H "Authorization: Bearer $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 "Authorization: Bearer $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 "Authorization: Bearer $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 subMerchantId, 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 "Authorization: Bearer $INFLOW_API_KEY"

When kycStatus = "approved", 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 kycStatus = "approved", 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/checkout/payment \
  -H "Authorization: Bearer $INFLOW_API_KEY" \
  -H "X-On-Behalf-Of: $SUB" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 5000,
    "currency": "EUR",
    "successUrl": "https://shop.example.com/success",
    "cancelUrl":  "https://shop.example.com/cancel"
  }'

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/withdraw/... \
  -H "Authorization: Bearer $INFLOW_API_KEY" \
  -H "X-On-Behalf-Of: $SUB" \
  -d '{ … }'

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