Quickstart

This walkthrough takes you from a blank account to a paid vendor.

Use an sk_test_ key throughout this guide. A key’s environment is inherited by the vendors it creates: a test key can only produce test vendors, and can never target a live vendor.

Activate Connect and choose your mode

Activation happens in your dashboard, under Connect. Choose marketplace or platform.

This choice is final: the mode cannot be changed afterwards. Read Commissions before you confirm.

Your integration can check the state at any time:

curl https://pay.sandbox.yabetoopay.com/v1/connect/activations \
  -H "Authorization: Bearer sk_test_..."

200

{ "id": "acct_...", "object": "connect_activation", "connect_mode": "marketplace" }

Create a vendor

The Idempotency-Key header is required: creation is irreversible.

curl -X POST https://pay.sandbox.yabetoopay.com/v1/connect/accounts \
  -H "Authorization: Bearer sk_test_..." \
  -H "Idempotency-Key: vendor-ada-001" \
  -H "Content-Type: application/json" \
  -d '{
    "country": "cg",
    "currency": "xaf",
    "name": "Boutique Ada",
    "email": "ada@example.com"
  }'

201

{
  "id": "acct_01HZVENDOR0000000000000000",
  "object": "connect_account",
  "status": "active",
  "fee_payer": "controller"
}

Keep this id: it identifies the vendor in every subsequent call.

Send them their verification link

curl -X POST \
  https://pay.sandbox.yabetoopay.com/v1/connect/accounts/acct_01HZVENDOR0000000000000000/onboarding_links \
  -H "Authorization: Bearer sk_test_..."

201

{
  "object": "connect_onboarding_link",
  "url": "https://verify.yabetoo.com/flow?token=vsess_...",
  "expires_at": "2026-09-06T10:00:00.000Z"
}

The vendor submits their documents and their payout destination there. Without this step, no withdrawal can go out.

Collect on their behalf

Two fields are added to your usual intent creation.

curl -X POST https://pay.sandbox.yabetoopay.com/v1/payment-intents \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 10000,
    "currency": "xaf",
    "on_behalf_of": "acct_01HZVENDOR0000000000000000",
    "application_fee_rate": 10
  }'

Confirm the intent as usual. At capture, on 10,000 XAF: the vendor receives 8,975 as pending balance, you keep 550, Yabetoo takes 475.

You do not know the vendor yet at the time of the sale? Collect normally, then distribute with an allocation.

Wait for maturation

The vendor’s funds land as a pending balance and become available after the delay (7 days by default).

curl https://pay.sandbox.yabetoopay.com/v1/connect/accounts/acct_01HZVENDOR0000000000000000 \
  -H "Authorization: Bearer sk_test_..."

{
  "balances": [
    { "currency": "xaf", "balance": 0, "pending_balance": 8975,
      "held_balance": 0, "next_maturity_at": "2026-09-11T00:00:00.000Z" }
  ]
}

Subscribe to connect.funds.available to be notified instead of polling.

Pay out their balance

Empty body: a Connect withdrawal transfers the entire available balance.

curl -X POST \
  https://pay.sandbox.yabetoopay.com/v1/connect/accounts/acct_01HZVENDOR0000000000000000/withdrawals \
  -H "Authorization: Bearer sk_test_..." \
  -H "Idempotency-Key: payout-ada-2026-09-11"

201

{
  "id": "wd_...",
  "object": "connect_withdrawal",
  "amount": 8975,
  "currency": "xaf",
  "destination": "24****4567",
  "status": "succeeded"
}

The call waits for the operator and returns the final state. An operator refusal returns 201 with status: "failed". Always read the status, not just the HTTP code.

Day-one errors

Symptom	Cause	Fix
`422 connect.controller_mode_unset` when creating a vendor	Connect is not activated	Do step 1
`422` on `phone`, `type` or `fee_payer`	These fields are refused, not ignored	Remove them from the body
`422` on `Idempotency-Key`	Header missing	Required at creation and at withdrawal
`403` on a vendor you just created	Test key targeting a `live` vendor, or the reverse	Use the key for the right environment
`400 connect.application_fee_too_low`	Your rate does not cover the Yabetoo fees	See Commissions
`422 E_CONNECT_VENDOR_PAYOUT_METHOD_UNAVAILABLE` at withdrawal	The vendor has not completed onboarding	Send them their link again
`422 E_CONNECT_VENDOR_EMPTY_BALANCE`	Available balance is empty: the funds are still pending	Wait for maturation

Commissions

The two modes, the floors, and why a commission can be refused.

Webhooks

The seven connect.* events.

Refunds

The clawback cascade and the 402 refusal.

Deferred mode

Collect first, distribute later.

Get started

Connected accounts

Accept payments

Pay out

Resources

Day-one errors

Next

Commissions

Webhooks

Refunds

Deferred mode

​Day-one errors

​Next

Commissions

Webhooks

Refunds

Deferred mode

Day-one errors

Next