End-to-End API Flow

This guide maps the full Connect integration path in API call order. Use it when wiring a marketplace that acts on behalf of sub-merchants via X-On-Behalf-Of.

Sandbox: Inflow provides a sandbox environment (https://sandbox.api.inflowpay.com) for integration testing. Ask your Inflow contact to enable Connect on both your sandbox and production marketplace accounts.

Flow overview

┌─────────────────────────────────────────────────────────────────────────┐
│  MARKETPLACE (your API key — no X-On-Behalf-Of)                         │
├─────────────────────────────────────────────────────────────────────────┤
│  1. GET  /api/connect/status                                            │
│  2. GET  /api/connect/settings                                          │
│  3. POST /api/connect/accounts                    → create sub-merchant   │
│  4. GET  /api/connect/accounts/:subMerchantId/kyc/status  → drive KYC    │
└─────────────────────────────────────────────────────────────────────────┘
                                    │
                     kycReady = true │  (wallet provisioned)
                                    ▼
┌─────────────────────────────────────────────────────────────────────────┐
│  ON BEHALF OF SUB-MERCHANT (X-On-Behalf-Of: <subMerchantId>)            │
├─────────────────────────────────────────────────────────────────────────┤
│  5. POST /api/checkout/payment                  → collect payin           │
│  6. GET  /api/balance                           → check available funds   │
│  7. GET  /api/account/countries                 → supported countries   │
│  8. GET  /api/account/bank-form                 → dynamic form schema   │
│  9. POST /api/account/bank                      → register bank dest.    │
│     — or POST /api/account/wallet               → register wallet dest. │
│ 10. GET  /api/quote/:accountId                  → preview fees          │
│ 11. POST /api/payout                            → initiate withdrawal    │
└─────────────────────────────────────────────────────────────────────────┘

Steps	Phase	`X-On-Behalf-Of`	Read next
1–2	Marketplace setup	No	Getting Started · Marketplace Settings
3–4	Sub-merchant onboarding	No	Sub-merchant Onboarding · KYC Flow
↓	`kycReady = true`	—	Sub-merchant is operable
5–6	Payin	Yes	Acting on Behalf Of · Fees and Payouts
7–9	Register payout destination	Steps 7–8: No · Step 9: Yes	Bank path or wallet path below
10–11	Payout	Yes	Acting on Behalf Of

Every call from step 5 onward must include:

X-Inflow-Api-Key: <marketplace_api_key>
X-On-Behalf-Of: <subMerchantId>

Connect management routes (/api/connect/*) never take X-On-Behalf-Of.

Phase 1 — Marketplace setup

→ Getting Started · Marketplace Settings

Step 1 — Verify Connect access

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

Expected: { "ok": true, "marketplaceUserId": "usr_…" }

Step 2 — Read marketplace settings

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

Review fee rates, payout window, and enabled currencies before going live.

Phase 2 — Sub-merchant onboarding

→ Sub-merchant Onboarding · KYC Flow

Step 3 — Create a 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",
    "customerType": "business",
    "redirectUrlKyc": "https://marketplace.example.com/onboarding/done"
  }'

Save the returned id as $SUB. The response includes kycStatus, nextUrl, and nextSteps for the initial bootstrap.

Field	Values	Effect
`customerType`	`"individual"` \| `"business"`	`"individual"` → KYC, `"business"` → KYB

Step 4 — Drive KYC to completion

If nextUrl is present, redirect the sub-merchant there. Then poll:

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

Proceed to Phase 3 when kycReady is true and walletId is set.

Phase 3 — Payin on behalf of sub-merchant

→ Acting on Behalf Of · Fees and Payouts

Step 5 — Create a checkout payment

curl -X POST https://api.inflowpay.xyz/api/checkout/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": "Order #1234", "price": 10000, "quantity": 1 }
    ]
  }'

Redirect the buyer to purchaseUrl. On success, Inflow credits the sub-merchant balance (net of fees) and routes your marketplace fee.

Step 6 — Check available balance

curl https://api.inflowpay.xyz/api/balance \
  -H "X-Inflow-Api-Key: $INFLOW_API_KEY" \
  -H "X-On-Behalf-Of: $SUB"

Withdrawable amount may be lower than the total balance while payins are still inside the payout window.

Phase 4 — Register a payout destination

Before calling POST /api/payout, the sub-merchant needs a registered destination. Choose bank payout or wallet payout — most integrations use bank payout.

Bank payout

Step 7 — List supported countries

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

Returns which countries support INDIVIDUAL and/or BUSINESS bank payouts.

Step 8 — Fetch the dynamic form schema

Required fields vary by country. Always call this before POST /api/account/bank:

curl "https://api.inflowpay.xyz/api/account/bank-form?country=FR&type=BUSINESS" \
  -H "X-Inflow-Api-Key: $INFLOW_API_KEY"

Query param	Description
`country`	ISO-3166 alpha-2 code (e.g. `FR`, `DE`, `GB`)
`type`	`INDIVIDUAL` or `BUSINESS`

The response is an array of form blocks (bank, owner, address, …), each with typed fields and JSON Schema validation rules. Render these fields in your UI, then submit the collected values to step 9.

Step 9 — Register the bank account

curl -X POST https://api.inflowpay.xyz/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.

Wallet payout

Skip steps 7–8 and register a crypto wallet directly:

curl -X POST https://api.inflowpay.xyz/api/account/wallet \
  -H "X-Inflow-Api-Key: $INFLOW_API_KEY" \
  -H "X-On-Behalf-Of: $SUB" \
  -H "Content-Type: application/json" \
  -d '{ "address": "0x…" }'

The network is inferred from the wallet address. Save the returned id as $ACCOUNT_ID.

Phase 5 — Payout

→ Acting on Behalf Of

Step 10 — Get a quote (optional but recommended)

curl "https://api.inflowpay.xyz/api/quote/$ACCOUNT_ID?amount=50000&currency=USDC" \
  -H "X-Inflow-Api-Key: $INFLOW_API_KEY" \
  -H "X-On-Behalf-Of: $SUB"

Returns the net amount after fees and a fee breakdown. amount is in cents.

Step 11 — Initiate the payout

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":     "'"$ACCOUNT_ID"'",
    "amountInCents": 50000,
    "currency":      "USDC",
    "network":       "base"
  }'

Field	Notes
`accountId`	Bank or wallet destination registered in step 9
`amountInCents`	Withdrawal amount in cents
`currency`	`USDC` or `EURC`
`network`	Required for wallet destinations only (`base`, `polygon`, `ethereum`, `solana`, `arbitrum`, `avalanche`)

Quick reference

Step	Method	Route	`X-On-Behalf-Of`
1	GET	`/api/connect/status`	No
2	GET	`/api/connect/settings`	No
3	POST	`/api/connect/accounts`	No
4	GET	`/api/connect/accounts/:id/kyc/status`	No
5	POST	`/api/checkout/payment`	Yes
6	GET	`/api/balance`	Yes
7	GET	`/api/account/countries`	No*
8	GET	`/api/account/bank-form`	No*
9	POST	`/api/account/bank` or `/account/wallet`	Yes
10	GET	`/api/quote/:accountId`	Yes
11	POST	`/api/payout`	Yes

*Steps 7–8 are reference lookups and do not require X-On-Behalf-Of. Steps 9–11 register and pay out on behalf of the sub-merchant and do require it.