> ## Documentation Index
> Fetch the complete documentation index at: https://docs.yabetoopay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> From activation to the first payout, in six calls.

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

<Info>
  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.
</Info>

<Steps>
  <Step title="Activate Connect and choose your mode">
    Activation happens in your [dashboard](https://app.yabetoo.com/dashboard/connect),
    under **Connect**. Choose **marketplace** or **platform**.

    <Warning>
      This choice is **final**: the mode cannot be changed afterwards. Read
      [Commissions](/en/connect/pricing) before you confirm.
    </Warning>

    Your integration can check the state at any time:

    ```bash theme={null}
    curl https://pay.sandbox.yabetoopay.com/v1/connect/activations \
      -H "Authorization: Bearer sk_test_..."
    ```

    ```json 200 theme={null}
    { "id": "acct_...", "object": "connect_activation", "connect_mode": "marketplace" }
    ```
  </Step>

  <Step title="Create a vendor">
    The `Idempotency-Key` header is **required**: creation is irreversible.

    ```bash theme={null}
    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"
      }'
    ```

    ```json 201 theme={null}
    {
      "id": "acct_01HZVENDOR0000000000000000",
      "object": "connect_account",
      "status": "active",
      "fee_payer": "controller"
    }
    ```

    Keep this `id`: it identifies the vendor in every subsequent call.
  </Step>

  <Step title="Send them their verification link">
    ```bash theme={null}
    curl -X POST \
      https://pay.sandbox.yabetoopay.com/v1/connect/accounts/acct_01HZVENDOR0000000000000000/onboarding_links \
      -H "Authorization: Bearer sk_test_..."
    ```

    ```json 201 theme={null}
    {
      "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.
  </Step>

  <Step title="Collect on their behalf">
    Two fields are added to your usual intent creation.

    ```bash theme={null}
    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**.

    <Note>
      You do not know the vendor yet at the time of the sale? Collect normally, then distribute
      with an [allocation](/en/connect/payments/allocations).
    </Note>
  </Step>

  <Step title="Wait for maturation">
    The vendor's funds land as a **pending balance** and become available after the delay
    (7 days by default).

    ```bash theme={null}
    curl https://pay.sandbox.yabetoopay.com/v1/connect/accounts/acct_01HZVENDOR0000000000000000 \
      -H "Authorization: Bearer sk_test_..."
    ```

    ```json theme={null}
    {
      "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.
  </Step>

  <Step title="Pay out their balance">
    **Empty** body: a Connect withdrawal transfers the entire available balance.

    ```bash theme={null}
    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"
    ```

    ```json 201 theme={null}
    {
      "id": "wd_...",
      "object": "connect_withdrawal",
      "amount": 8975,
      "currency": "xaf",
      "destination": "24****4567",
      "status": "succeeded"
    }
    ```

    <Warning>
      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.
    </Warning>
  </Step>
</Steps>

## 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](/en/connect/pricing) |
| `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                    |

## Next

<CardGroup cols={2}>
  <Card title="Commissions" icon="percent" href="/en/connect/pricing">
    The two modes, the floors, and why a commission can be refused.
  </Card>

  <Card title="Webhooks" icon="bell" href="/en/connect/webhooks">
    The seven `connect.*` events.
  </Card>

  <Card title="Refunds" icon="rotate-left" href="/en/connect/refunds">
    The clawback cascade and the `402` refusal.
  </Card>

  <Card title="Deferred mode" icon="arrows-split-up-and-left" href="/en/connect/payments/allocations">
    Collect first, distribute later.
  </Card>
</CardGroup>