> ## 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.

# Retailer quickstart

> Create a checkout, let your customer pay, and deliver the codes.

This walkthrough integrates the Wizzgift catalog into your storefront. You need an [API key](/authentication) and the **retailer** capability enabled on your account.

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

    Prices are what *you* pay before your markup. Render them in your store with your margin applied — the API adds your `markupPercent` on top when you create the checkout.
  </Step>

  <Step title="Create a checkout for your customer">
    ```bash theme={null}
    curl -X POST https://api.wizzgift.com/retailer/v1/checkouts \
      -H "X-API-Key: wg_live_..." \
      -H "Content-Type: application/json" \
      -d '{
        "customerEmail": "buyer@example.com",
        "externalRef": "shop-order-889",
        "customerCountry": "DE",
        "markupPercent": 5,
        "items": [
          { "productId": "prod_psn_de", "skuId": "sku_25", "amount": 25, "quantity": 1 }
        ]
      }'
    ```

    Key fields:

    * `customerEmail` — your **end-customer's** email, used for delivery identity and refunds.
    * `customerCountry` — the end-customer's country, never inferred from your server's IP. Blocked-country rules apply when present.
    * `markupPercent` — your profit on this checkout. Overrides your account default; capped by your tier's `maxMarkupPercent`.
    * `externalRef` — your own order id, for [idempotent retries](/guides/idempotency).

    The `201` response includes the priced checkout (`totalAmount` includes your markup), `availablePaymentMethods` with per-method `eligible` flags, and `links.hostedPaymentUrl`.
  </Step>

  <Step title="Take payment — pick one of three paths">
    <Tabs>
      <Tab title="Hosted page (zero code)">
        Redirect your customer to `links.hostedPaymentUrl`:

        ```text theme={null}
        https://www.wizzgift.com/checkout/chkr_ab12cd34
        ```

        Our hosted checkout handles payment method selection, invoices, and payment UI. Nothing else to build.
      </Tab>

      <Tab title="One-call invoice">
        Include a `payment` object in the create call to get the invoice in the same response:

        ```json theme={null}
        {
          "customerEmail": "buyer@example.com",
          "items": [{ "productId": "prod_psn_de", "skuId": "sku_25", "amount": 25, "quantity": 1 }],
          "payment": { "paymentMethodId": "pm_btc" }
        }
        ```

        Render `payment.paymentAddress`, `payment.amount`, `payment.currency`, and the `payment.qr` strings in your own payment UI.
      </Tab>

      <Tab title="Two-step invoice">
        Create the invoice after your customer picks a method:

        ```bash theme={null}
        curl -X POST https://api.wizzgift.com/retailer/v1/checkouts/chkr_ab12cd34/payment \
          -H "X-API-Key: wg_live_..." \
          -H "Content-Type: application/json" \
          -d '{ "paymentMethodId": "pm_btc" }'
        ```

        Call it again with the same method to refresh an expired invoice — the provider deduplicates and returns the same invoice with fresh data.
      </Tab>
    </Tabs>

    <Tip>
      **Prepaid mode:** pass the *balance* payment method id and the total is deducted from your business balance instantly — no customer invoice at all. Useful when you collect payment on your own side.
    </Tip>
  </Step>

  <Step title="Deliver the codes">
    Either poll, or configure [signed webhooks](/webhooks/overview) and fetch when `order.completed` arrives. One endpoint returns everything — order status, payment state, and codes:

    ```bash theme={null}
    curl https://api.wizzgift.com/retailer/v1/checkouts/chkr_ab12cd34 \
      -H "X-API-Key: wg_live_..."
    ```

    ```json Response (200) theme={null}
    {
      "checkoutId": "chkr_ab12cd34",
      "customerEmail": "buyer@example.com",
      "status": "completed",
      "totalAmount": 27.3,
      "paymentCurrency": "USD",
      "markupTotal": 1.3,
      "payment": { "state": "confirmed", "confirmedAmount": 27.3, "totalAmount": 27.3, "currency": "USD" },
      "items": [
        {
          "productName": "PlayStation Store 25 EUR (DE)",
          "unitPrice": 27.3,
          "unitMarkup": 1.3,
          "quantity": 1,
          "status": "completed",
          "fulfillments": [
            { "index": 0, "status": "completed", "sealed": false, "cardCode": "9XKD-...-PL2M", "fulfilledAt": 1753142400000 }
          ]
        }
      ]
    }
    ```

    <Note>
      Card codes are never included in webhook payloads — the webhook tells you *when* to fetch, this endpoint tells you *what* to deliver.
    </Note>
  </Step>
</Steps>

## Your margin

Markup is your profit: `unitMarkup` is baked into each item's `unitPrice`, and the checkout's `markupTotal` (USD) is **credited to your business balance** as items complete. Track lifetime earnings under `markupEarnings` on `GET /retailer/v1/account`, and set an account-wide default with `PATCH /retailer/v1/account`.

## Next steps

<Columns cols={2}>
  <Card title="Webhooks" icon="webhook" href="/webhooks/overview">
    Get notified on payment and fulfillment instead of polling.
  </Card>

  <Card title="Payments" icon="credit-card" href="/guides/payments">
    Invoice fields, payment states, and partial crypto payments.
  </Card>
</Columns>