Connect Quickstart

In this guide you'll provision your marketplace, onboard a single sub-merchant, accept a payment on their behalf, register their bank account, and pay them out.

📘

Testing. Every call below works identically in the sandbox (https://sandbox.api.inflowpay.com) with sandbox keys. See Sandbox Environment.

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.com/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.com/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.com/api/connect/accounts \
  -H "X-Inflow-Api-Key: $INFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "merchantName": "Acme Coffee",
    "customerType": "individual",
    "firstName": "Jane",
    "lastName": "Doe",
    "redirectUrlKyc": "https://marketplace.example.com/connect/kyc-complete"
  }'

The response includes id (the sub-merchant user id, used 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.com/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.com/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:

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

See Fees and Payouts for the math and timing.

7. Register a payout destination

Before a payout, the sub-merchant needs a registered bank account. Required fields vary by country, so fetch the dynamic form first:

# Which countries are supported, and for which account types
curl https://api.inflowpay.com/api/account/countries \
  -H "X-Inflow-Api-Key: $INFLOW_API_KEY" \
  -H "X-On-Behalf-Of: $SUB"

# The required fields for the chosen country
curl "https://api.inflowpay.com/api/account/bank-form?country=FR&type=INDIVIDUAL" \
  -H "X-Inflow-Api-Key: $INFLOW_API_KEY" \
  -H "X-On-Behalf-Of: $SUB"

# Register the bank account with the collected values
curl -X POST https://api.inflowpay.com/api/account/bank \
  -H "X-Inflow-Api-Key: $INFLOW_API_KEY" \
  -H "X-On-Behalf-Of: $SUB" \
  -H "Content-Type: application/json" \
  -d '{ ... fields from bank-form ... }'

Save the returned account id as $ACCOUNT_ID. For crypto wallet destinations and the full form schema, see the Integration Guide.

8. Pay the sub-merchant out

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

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

accountId references the payout destination registered in step 7. currency is the settlement currency to draw from (EURC or USDC; see How Connect Works). For crypto wallet destinations, also pass network (base, polygon, ethereum, solana, arbitrum, avalanche).

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

What to read next

• Marketplace Settings
• Sub-merchant Onboarding
• KYC Flow
• Acting on Behalf Of: every error code you'll hit
• Suspension and Lifecycle