Retailer quickstart

This walkthrough integrates the Wizzgift catalog into your storefront. You need an API key and the retailer capability enabled on your account.

Load the catalog

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.

Create a checkout for your customer

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.

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

Take payment — pick one of three paths

Hosted page (zero code)
One-call invoice
Two-step invoice

Redirect your customer to links.hostedPaymentUrl:

https://www.wizzgift.com/checkout/chkr_ab12cd34

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

Include a payment object in the create call to get the invoice in the same response:

{
  "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.

Create the invoice after your customer picks a method:

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.

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.

Deliver the codes

Either poll, or configure signed webhooks and fetch when order.completed arrives. One endpoint returns everything — order status, payment state, and codes:

curl https://api.wizzgift.com/retailer/v1/checkouts/chkr_ab12cd34 \
  -H "X-API-Key: wg_live_..."

Response (200)

{
  "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 }
      ]
    }
  ]
}

Card codes are never included in webhook payloads — the webhook tells you when to fetch, this endpoint tells you what to deliver.

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.

Getting started

Quickstarts

Core concepts

Webhooks

Your margin

Next steps

Webhooks

Payments

​Your margin

​Next steps

Webhooks

Payments

Your margin

Next steps