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

# B2B quickstart

> Fund your balance, place an order, and get the card codes.

This walkthrough takes you from an empty account to delivered card codes on the B2B surface. You need an [API key](/authentication) with the default scopes.

<Steps>
  <Step title="Fund your balance">
    Create a deposit. `amount` is the **USD value to credit**; `paymentCurrency` is what you pay in. Pass `paymentMethodId` to get the payment invoice in the same call (list method ids first with `GET /retailer/v1/payment-methods`, or omit the field and pick from the returned `availablePaymentMethods`).

    <CodeGroup>
      ```bash curl theme={null}
      curl -X POST https://api.wizzgift.com/b2b/deposits \
        -H "X-API-Key: wg_live_..." \
        -H "Content-Type: application/json" \
        -d '{
          "amount": 500,
          "paymentCurrency": "USDT",
          "paymentMethodId": "pm_usdt_trc20"
        }'
      ```

      ```javascript Node.js theme={null}
      const res = await fetch("https://api.wizzgift.com/b2b/deposits", {
        method: "POST",
        headers: {
          "X-API-Key": process.env.WIZZGIFT_API_KEY,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          amount: 500,
          paymentCurrency: "USDT",
          paymentMethodId: "pm_usdt_trc20",
        }),
      });
      const { deposit, paymentAmount, payment } = await res.json();
      ```

      ```python Python theme={null}
      import requests

      res = requests.post(
          "https://api.wizzgift.com/b2b/deposits",
          headers={"X-API-Key": WIZZGIFT_API_KEY},
          json={
              "amount": 500,
              "paymentCurrency": "USDT",
              "paymentMethodId": "pm_usdt_trc20",
          },
      )
      data = res.json()
      ```
    </CodeGroup>

    The response contains the invoice — send exactly `payment.amount` to `payment.paymentAddress` (or redirect to `payment.paymentUrl` for hosted providers):

    ```json Response (201) theme={null}
    {
      "deposit": {
        "depositId": "depb_a8Xk2mQ9pL1r",
        "amount": 500,
        "currency": "USD",
        "paymentCurrency": "USDT",
        "status": "pending",
        "expiresAt": 1753149600000
      },
      "paymentAmount": 500.75,
      "payment": {
        "paymentId": "pay_31xk...",
        "status": "pending",
        "paymentAddress": "TWd4...Ab12",
        "amount": "500.75",
        "currency": "USDT",
        "network": "Tron",
        "expiresAt": 1753149600000
      }
    }
    ```

    <Warning>
      Deposits expire after roughly 60 minutes unpaid. Each deposit is capped by your tier's `maxDepositUSD`.
    </Warning>
  </Step>

  <Step title="Wait for the credit">
    Poll the deposit until `deposit.status` is `confirmed`:

    ```bash theme={null}
    curl https://api.wizzgift.com/b2b/deposits/depb_a8Xk2mQ9pL1r \
      -H "X-API-Key: wg_live_..."
    ```

    Crypto payments pass through `confirming` (transaction seen, awaiting network confirmations) before `confirmed`. Once confirmed, `GET /b2b/balance` reflects the credit.
  </Step>

  <Step title="Browse the catalog">
    ```bash theme={null}
    curl https://api.wizzgift.com/b2b/products \
      -H "X-API-Key: wg_live_..."
    ```

    Each product carries `skus` with a denomination range (`min`, `max`, `changeStep`) and `minCost` — the price for the minimum denomination, before your account discount. Note the `productId` and the SKU `id` you want to order.
  </Step>

  <Step title="Place an order">
    One call creates the order **and pays it from your balance**. Always send an `externalRef` so retries are [idempotent](/guides/idempotency):

    ```bash theme={null}
    curl -X POST https://api.wizzgift.com/b2b/orders \
      -H "X-API-Key: wg_live_..." \
      -H "Content-Type: application/json" \
      -d '{
        "externalRef": "acme-order-1042",
        "items": [
          { "productId": "prod_amazon_us", "skuId": "sku_50_100", "amount": 50, "quantity": 3 }
        ]
      }'
    ```

    `amount` is the denomination the recipient gets (a 50 USD card), `quantity` is how many. A `201` means the balance payment confirmed and fulfillment started. Insufficient balance returns `400` with the reason in `error.details.reason`; tier caps return `422 B2B_LIMIT_EXCEEDED`.
  </Step>

  <Step title="Poll for codes">
    ```bash theme={null}
    curl https://api.wizzgift.com/b2b/orders/chkb_9f2k1m \
      -H "X-API-Key: wg_live_..."
    ```

    When `status` reaches `completed` (or `partial`), read the codes from each item's `fulfillments` array:

    ```json Response (200) theme={null}
    {
      "checkoutId": "chkb_9f2k1m",
      "externalRef": "acme-order-1042",
      "status": "completed",
      "items": [
        {
          "productName": "Amazon Gift Card (US)",
          "quantity": 3,
          "status": "completed",
          "fulfillments": [
            { "index": 0, "status": "completed", "cardCode": "AQ4X-...-9PLM", "cardPin": null, "fulfilledAt": 1753142400000 },
            { "index": 1, "status": "completed", "cardCode": "BX2N-...-4KJk", "cardPin": null, "fulfilledAt": 1753142401000 },
            { "index": 2, "status": "completed", "cardCode": "CM8V-...-2RTQ", "cardPin": null, "fulfilledAt": 1753142403000 }
          ]
        }
      ]
    }
    ```

    Poll every few seconds; most orders complete within a minute. If some units fail (`status: partial`), request a refund for the failed portion with `POST /b2b/refunds`.
  </Step>
</Steps>

## Next steps

<Columns cols={2}>
  <Card title="Order lifecycle" icon="git-branch" href="/guides/order-lifecycle">
    Statuses, partial fulfillment, and sealed cards.
  </Card>

  <Card title="Limits and tiers" icon="gauge" href="/guides/limits-and-tiers">
    Spend caps, order shape limits, and how to read your usage.
  </Card>
</Columns>