Create a checkout for an end-customer

curl --request POST \
  --url https://api.wizzgift.com/retailer/v1/checkouts \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "customerEmail": "jsmith@example.com",
  "items": [
    {
      "productId": "<string>",
      "skuId": "<string>",
      "amount": 50,
      "quantity": 5000,
      "requiredFields": {}
    }
  ],
  "paymentCurrency": "USD",
  "customerCountry": "DE",
  "externalRef": "<string>",
  "callbackUrl": "<string>",
  "markupPercent": 1,
  "sealCards": false
}
'

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    customerEmail: 'jsmith@example.com',
    items: [
      {
        productId: '<string>',
        skuId: '<string>',
        amount: 50,
        quantity: 5000,
        requiredFields: {}
      }
    ],
    paymentCurrency: 'USD',
    customerCountry: 'DE',
    externalRef: '<string>',
    callbackUrl: '<string>',
    markupPercent: 1,
    sealCards: false
  })
};

fetch('https://api.wizzgift.com/retailer/v1/checkouts', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.wizzgift.com/retailer/v1/checkouts"

payload = {
    "customerEmail": "jsmith@example.com",
    "items": [
        {
            "productId": "<string>",
            "skuId": "<string>",
            "amount": 50,
            "quantity": 5000,
            "requiredFields": {}
        }
    ],
    "paymentCurrency": "USD",
    "customerCountry": "DE",
    "externalRef": "<string>",
    "callbackUrl": "<string>",
    "markupPercent": 1,
    "sealCards": False
}
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.wizzgift.com/retailer/v1/checkouts",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'customerEmail' => 'jsmith@example.com',
    'items' => [
        [
                'productId' => '<string>',
                'skuId' => '<string>',
                'amount' => 50,
                'quantity' => 5000,
                'requiredFields' => [
                                
                ]
        ]
    ],
    'paymentCurrency' => 'USD',
    'customerCountry' => 'DE',
    'externalRef' => '<string>',
    'callbackUrl' => '<string>',
    'markupPercent' => 1,
    'sealCards' => false
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

{
  "checkoutId": "<string>",
  "customerEmail": "<string>",
  "status": "pending",
  "totalAmount": 123,
  "paymentCurrency": "<string>",
  "items": [
    {
      "id": "<string>",
      "productId": "<string>",
      "productName": "<string>",
      "skuId": "<string>",
      "unitAmount": 123,
      "unitPrice": 123,
      "quantity": 123,
      "status": "pending",
      "checkoutId": "<string>",
      "productImageUrl": "<string>",
      "productBrandColor": "<string>",
      "unitMarkup": 123,
      "requiredFields": {},
      "fulfillments": [
        {
          "index": 123,
          "status": "<string>",
          "sealed": true,
          "giftCardId": "<string>",
          "cardCode": "<string>",
          "cardPin": "<string>",
          "cardUrl": "<string>",
          "vendorOrderId": "<string>",
          "TxId": "<string>",
          "expiresAt": 1753142400000,
          "errorMessage": "<string>",
          "fulfilledAt": 1753142400000
        }
      ],
      "createdAt": 1753142400000,
      "updatedAt": 1753142400000
    }
  ],
  "createdAt": 1753142400000,
  "availablePaymentMethods": [
    {
      "id": "<string>",
      "name": "Bitcoin",
      "type": "<string>",
      "status": "active",
      "eligible": true,
      "description": "<string>",
      "instructions": "<string>",
      "imageUrl": "<string>",
      "ranking": 123,
      "feeInfo": "<string>",
      "minAmountUSD": 123,
      "tag": "Recommended",
      "tagColor": "<string>",
      "tagTextColor": "<string>",
      "network": "Bitcoin",
      "identifier": "<string>",
      "symbol": "BTC",
      "coinImageUrl": "<string>",
      "memoRequired": true,
      "refundable": true,
      "minRefundAmountUSD": 123,
      "refundDescription": "<string>",
      "refundNotes": "<string>"
    }
  ],
  "links": {
    "hostedPaymentUrl": "https://www.wizzgift.com/checkout/chkr_abc123"
  },
  "externalRef": "<string>",
  "markupTotal": 123,
  "sealCards": true,
  "callbackUrl": "<string>",
  "country": "<string>",
  "completedAt": 1753142400000,
  "expiredAt": 1753142400000,
  "updatedAt": 1753142400000,
  "payment": {
    "paymentMethodId": "<string>",
    "status": "pending",
    "paymentId": "<string>",
    "appliedAmount": 123,
    "appliedCurrency": "<string>",
    "providerAmount": 123,
    "providerCurrency": "<string>",
    "providerPaymentId": "<string>",
    "paymentUrl": "<string>",
    "paymentAddress": "<string>",
    "memo": "<string>",
    "destinationTag": "<string>",
    "amount": "<string>",
    "currency": "<string>",
    "network": "Bitcoin",
    "exchangeRate": "<string>",
    "expiresAt": 1753142400000,
    "qr": {
      "withAmount": "<string>",
      "withoutAmount": "<string>"
    },
    "fee": {
      "percentage": 123,
      "fixed": 123,
      "recommended": true,
      "feeUnit": "sat/vB"
    },
    "errorMessage": "<string>"
  }
}

{
  "checkoutId": "<string>",
  "customerEmail": "<string>",
  "status": "pending",
  "totalAmount": 123,
  "paymentCurrency": "<string>",
  "items": [
    {
      "id": "<string>",
      "productId": "<string>",
      "productName": "<string>",
      "skuId": "<string>",
      "unitAmount": 123,
      "unitPrice": 123,
      "quantity": 123,
      "status": "pending",
      "checkoutId": "<string>",
      "productImageUrl": "<string>",
      "productBrandColor": "<string>",
      "unitMarkup": 123,
      "requiredFields": {},
      "fulfillments": [
        {
          "index": 123,
          "status": "<string>",
          "sealed": true,
          "giftCardId": "<string>",
          "cardCode": "<string>",
          "cardPin": "<string>",
          "cardUrl": "<string>",
          "vendorOrderId": "<string>",
          "TxId": "<string>",
          "expiresAt": 1753142400000,
          "errorMessage": "<string>",
          "fulfilledAt": 1753142400000
        }
      ],
      "createdAt": 1753142400000,
      "updatedAt": 1753142400000
    }
  ],
  "createdAt": 1753142400000,
  "availablePaymentMethods": [
    {
      "id": "<string>",
      "name": "Bitcoin",
      "type": "<string>",
      "status": "active",
      "eligible": true,
      "description": "<string>",
      "instructions": "<string>",
      "imageUrl": "<string>",
      "ranking": 123,
      "feeInfo": "<string>",
      "minAmountUSD": 123,
      "tag": "Recommended",
      "tagColor": "<string>",
      "tagTextColor": "<string>",
      "network": "Bitcoin",
      "identifier": "<string>",
      "symbol": "BTC",
      "coinImageUrl": "<string>",
      "memoRequired": true,
      "refundable": true,
      "minRefundAmountUSD": 123,
      "refundDescription": "<string>",
      "refundNotes": "<string>"
    }
  ],
  "links": {
    "hostedPaymentUrl": "https://www.wizzgift.com/checkout/chkr_abc123"
  },
  "externalRef": "<string>",
  "markupTotal": 123,
  "sealCards": true,
  "callbackUrl": "<string>",
  "country": "<string>",
  "completedAt": 1753142400000,
  "expiredAt": 1753142400000,
  "updatedAt": 1753142400000,
  "payment": {
    "paymentMethodId": "<string>",
    "status": "pending",
    "paymentId": "<string>",
    "appliedAmount": 123,
    "appliedCurrency": "<string>",
    "providerAmount": 123,
    "providerCurrency": "<string>",
    "providerPaymentId": "<string>",
    "paymentUrl": "<string>",
    "paymentAddress": "<string>",
    "memo": "<string>",
    "destinationTag": "<string>",
    "amount": "<string>",
    "currency": "<string>",
    "network": "Bitcoin",
    "exchangeRate": "<string>",
    "expiresAt": 1753142400000,
    "qr": {
      "withAmount": "<string>",
      "withoutAmount": "<string>"
    },
    "fee": {
      "percentage": 123,
      "fixed": 123,
      "recommended": true,
      "feeUnit": "sat/vB"
    },
    "errorMessage": "<string>"
  }
}

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input"
  },
  "requestId": "req_8f3k2"
}

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or expired API key"
  },
  "requestId": "req_8f3k2"
}

{
  "error": {
    "code": "FORBIDDEN",
    "message": "Retailer API access is disabled for this account"
  },
  "requestId": "req_8f3k2"
}

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Checkout not found"
  },
  "requestId": "req_8f3k2"
}

{
  "error": {
    "code": "CONFLICT",
    "message": "externalRef already used on another API surface"
  },
  "requestId": "req_8f3k2"
}

{
  "error": {
    "code": "B2B_LIMIT_EXCEEDED",
    "message": "Daily spend cap exceeded",
    "details": {
      "limit": "dailySpendCapUSD",
      "limitValue": 5000,
      "current": 4800,
      "requested": 400,
      "window": "day",
      "tier": "starter"
    }
  },
  "requestId": "req_8f3k2"
}

{
  "error": "Too many requests",
  "message": "<string>"
}

Retailer · Checkouts

Create a checkout for an end-customer

Creates an order on behalf of your end-customer. Idempotent via externalRef (same-surface replay → 200; used on B2B → 409).

customerCountry is the end-customer’s country (never inferred from your server’s IP) — blocked-country rules apply when present.
markupPercent overrides your account default; both are capped by your tier’s maxMarkupPercent.
Include payment.paymentMethodId for a one-call invoice; the balance method prepays from your own balance instead (must confirm instantly or the call fails with 400).
Tier caps on open checkouts and daily creations → 422.

POST

retailer

checkouts

Create a checkout for an end-customer

curl --request POST \
  --url https://api.wizzgift.com/retailer/v1/checkouts \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "customerEmail": "jsmith@example.com",
  "items": [
    {
      "productId": "<string>",
      "skuId": "<string>",
      "amount": 50,
      "quantity": 5000,
      "requiredFields": {}
    }
  ],
  "paymentCurrency": "USD",
  "customerCountry": "DE",
  "externalRef": "<string>",
  "callbackUrl": "<string>",
  "markupPercent": 1,
  "sealCards": false
}
'

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    customerEmail: 'jsmith@example.com',
    items: [
      {
        productId: '<string>',
        skuId: '<string>',
        amount: 50,
        quantity: 5000,
        requiredFields: {}
      }
    ],
    paymentCurrency: 'USD',
    customerCountry: 'DE',
    externalRef: '<string>',
    callbackUrl: '<string>',
    markupPercent: 1,
    sealCards: false
  })
};

fetch('https://api.wizzgift.com/retailer/v1/checkouts', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.wizzgift.com/retailer/v1/checkouts"

payload = {
    "customerEmail": "jsmith@example.com",
    "items": [
        {
            "productId": "<string>",
            "skuId": "<string>",
            "amount": 50,
            "quantity": 5000,
            "requiredFields": {}
        }
    ],
    "paymentCurrency": "USD",
    "customerCountry": "DE",
    "externalRef": "<string>",
    "callbackUrl": "<string>",
    "markupPercent": 1,
    "sealCards": False
}
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.wizzgift.com/retailer/v1/checkouts",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'customerEmail' => 'jsmith@example.com',
    'items' => [
        [
                'productId' => '<string>',
                'skuId' => '<string>',
                'amount' => 50,
                'quantity' => 5000,
                'requiredFields' => [
                                
                ]
        ]
    ],
    'paymentCurrency' => 'USD',
    'customerCountry' => 'DE',
    'externalRef' => '<string>',
    'callbackUrl' => '<string>',
    'markupPercent' => 1,
    'sealCards' => false
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

{
  "checkoutId": "<string>",
  "customerEmail": "<string>",
  "status": "pending",
  "totalAmount": 123,
  "paymentCurrency": "<string>",
  "items": [
    {
      "id": "<string>",
      "productId": "<string>",
      "productName": "<string>",
      "skuId": "<string>",
      "unitAmount": 123,
      "unitPrice": 123,
      "quantity": 123,
      "status": "pending",
      "checkoutId": "<string>",
      "productImageUrl": "<string>",
      "productBrandColor": "<string>",
      "unitMarkup": 123,
      "requiredFields": {},
      "fulfillments": [
        {
          "index": 123,
          "status": "<string>",
          "sealed": true,
          "giftCardId": "<string>",
          "cardCode": "<string>",
          "cardPin": "<string>",
          "cardUrl": "<string>",
          "vendorOrderId": "<string>",
          "TxId": "<string>",
          "expiresAt": 1753142400000,
          "errorMessage": "<string>",
          "fulfilledAt": 1753142400000
        }
      ],
      "createdAt": 1753142400000,
      "updatedAt": 1753142400000
    }
  ],
  "createdAt": 1753142400000,
  "availablePaymentMethods": [
    {
      "id": "<string>",
      "name": "Bitcoin",
      "type": "<string>",
      "status": "active",
      "eligible": true,
      "description": "<string>",
      "instructions": "<string>",
      "imageUrl": "<string>",
      "ranking": 123,
      "feeInfo": "<string>",
      "minAmountUSD": 123,
      "tag": "Recommended",
      "tagColor": "<string>",
      "tagTextColor": "<string>",
      "network": "Bitcoin",
      "identifier": "<string>",
      "symbol": "BTC",
      "coinImageUrl": "<string>",
      "memoRequired": true,
      "refundable": true,
      "minRefundAmountUSD": 123,
      "refundDescription": "<string>",
      "refundNotes": "<string>"
    }
  ],
  "links": {
    "hostedPaymentUrl": "https://www.wizzgift.com/checkout/chkr_abc123"
  },
  "externalRef": "<string>",
  "markupTotal": 123,
  "sealCards": true,
  "callbackUrl": "<string>",
  "country": "<string>",
  "completedAt": 1753142400000,
  "expiredAt": 1753142400000,
  "updatedAt": 1753142400000,
  "payment": {
    "paymentMethodId": "<string>",
    "status": "pending",
    "paymentId": "<string>",
    "appliedAmount": 123,
    "appliedCurrency": "<string>",
    "providerAmount": 123,
    "providerCurrency": "<string>",
    "providerPaymentId": "<string>",
    "paymentUrl": "<string>",
    "paymentAddress": "<string>",
    "memo": "<string>",
    "destinationTag": "<string>",
    "amount": "<string>",
    "currency": "<string>",
    "network": "Bitcoin",
    "exchangeRate": "<string>",
    "expiresAt": 1753142400000,
    "qr": {
      "withAmount": "<string>",
      "withoutAmount": "<string>"
    },
    "fee": {
      "percentage": 123,
      "fixed": 123,
      "recommended": true,
      "feeUnit": "sat/vB"
    },
    "errorMessage": "<string>"
  }
}

{
  "checkoutId": "<string>",
  "customerEmail": "<string>",
  "status": "pending",
  "totalAmount": 123,
  "paymentCurrency": "<string>",
  "items": [
    {
      "id": "<string>",
      "productId": "<string>",
      "productName": "<string>",
      "skuId": "<string>",
      "unitAmount": 123,
      "unitPrice": 123,
      "quantity": 123,
      "status": "pending",
      "checkoutId": "<string>",
      "productImageUrl": "<string>",
      "productBrandColor": "<string>",
      "unitMarkup": 123,
      "requiredFields": {},
      "fulfillments": [
        {
          "index": 123,
          "status": "<string>",
          "sealed": true,
          "giftCardId": "<string>",
          "cardCode": "<string>",
          "cardPin": "<string>",
          "cardUrl": "<string>",
          "vendorOrderId": "<string>",
          "TxId": "<string>",
          "expiresAt": 1753142400000,
          "errorMessage": "<string>",
          "fulfilledAt": 1753142400000
        }
      ],
      "createdAt": 1753142400000,
      "updatedAt": 1753142400000
    }
  ],
  "createdAt": 1753142400000,
  "availablePaymentMethods": [
    {
      "id": "<string>",
      "name": "Bitcoin",
      "type": "<string>",
      "status": "active",
      "eligible": true,
      "description": "<string>",
      "instructions": "<string>",
      "imageUrl": "<string>",
      "ranking": 123,
      "feeInfo": "<string>",
      "minAmountUSD": 123,
      "tag": "Recommended",
      "tagColor": "<string>",
      "tagTextColor": "<string>",
      "network": "Bitcoin",
      "identifier": "<string>",
      "symbol": "BTC",
      "coinImageUrl": "<string>",
      "memoRequired": true,
      "refundable": true,
      "minRefundAmountUSD": 123,
      "refundDescription": "<string>",
      "refundNotes": "<string>"
    }
  ],
  "links": {
    "hostedPaymentUrl": "https://www.wizzgift.com/checkout/chkr_abc123"
  },
  "externalRef": "<string>",
  "markupTotal": 123,
  "sealCards": true,
  "callbackUrl": "<string>",
  "country": "<string>",
  "completedAt": 1753142400000,
  "expiredAt": 1753142400000,
  "updatedAt": 1753142400000,
  "payment": {
    "paymentMethodId": "<string>",
    "status": "pending",
    "paymentId": "<string>",
    "appliedAmount": 123,
    "appliedCurrency": "<string>",
    "providerAmount": 123,
    "providerCurrency": "<string>",
    "providerPaymentId": "<string>",
    "paymentUrl": "<string>",
    "paymentAddress": "<string>",
    "memo": "<string>",
    "destinationTag": "<string>",
    "amount": "<string>",
    "currency": "<string>",
    "network": "Bitcoin",
    "exchangeRate": "<string>",
    "expiresAt": 1753142400000,
    "qr": {
      "withAmount": "<string>",
      "withoutAmount": "<string>"
    },
    "fee": {
      "percentage": 123,
      "fixed": 123,
      "recommended": true,
      "feeUnit": "sat/vB"
    },
    "errorMessage": "<string>"
  }
}

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input"
  },
  "requestId": "req_8f3k2"
}

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or expired API key"
  },
  "requestId": "req_8f3k2"
}

{
  "error": {
    "code": "FORBIDDEN",
    "message": "Retailer API access is disabled for this account"
  },
  "requestId": "req_8f3k2"
}

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Checkout not found"
  },
  "requestId": "req_8f3k2"
}

{
  "error": {
    "code": "CONFLICT",
    "message": "externalRef already used on another API surface"
  },
  "requestId": "req_8f3k2"
}

{
  "error": {
    "code": "B2B_LIMIT_EXCEEDED",
    "message": "Daily spend cap exceeded",
    "details": {
      "limit": "dailySpendCapUSD",
      "limitValue": 5000,
      "current": 4800,
      "requested": 400,
      "window": "day",
      "tier": "starter"
    }
  },
  "requestId": "req_8f3k2"
}

{
  "error": "Too many requests",
  "message": "<string>"
}

Authorizations

X-API-Key

string

header

required

API key (wg_live_…) created in the dashboard (Account → API Keys). Shown once at creation; only a hash is stored server-side.

Body

application/json

customerEmail

string<email>

required

Your END-CUSTOMER's email (used for delivery/refund identity).

items

object[]

required

Required array length: 1 - 50 elements

Show child attributes

paymentCurrency

string

default:USD

customerCountry

string

The END-CUSTOMER's ISO 3166-1 alpha-2 country (never inferred from your server's IP). When present, blocked-country rules apply.

Required string length: 2

Example:

"DE"

externalRef

string

Your own order id — idempotency + reconciliation.

Required string length: 1 - 128

callbackUrl

string<uri>

Per-checkout webhook override — https, public hostname. Signed with your business webhook secret (an endpoint must be configured).

markupPercent

number

Your profit margin on top of our price for this checkout. Overrides your account default; capped by tier maxMarkupPercent.

Required range: x >= 0

payment

object

One-call convenience — also create the payment invoice.

Show child attributes

sealCards

boolean

default:false

Response

Idempotent replay — checkout with this externalRef already exists.

checkoutId

string

required

customerEmail

string

required

The end-customer's email.

status

enum<string>

required

Order lifecycle. partial = some items fulfilled, some failed. expired = never paid.

Available options:

pending,

processing,

completed,

partial,

failed,

expired

totalAmount

number

required

What the end-customer pays, in paymentCurrency (markup included).

paymentCurrency

string

required

items

object[]

required

Show child attributes

createdAt

integer<int64>

required

Unix timestamp in milliseconds (UTC).

Example:

1753142400000

availablePaymentMethods

object[]

required

Show child attributes

links

object

required

Show child attributes

externalRef

string | null

markupTotal

number

Your total markup on this checkout, in USD. Credited to your balance as items complete.

sealCards

boolean

callbackUrl

string | null

country

string | null

The customerCountry you supplied.

completedAt

integer<int64> | null

Unix timestamp in milliseconds (UTC).

Example:

1753142400000

expiredAt

integer<int64> | null

Unix timestamp in milliseconds (UTC).

Example:

1753142400000

updatedAt

integer<int64>

Unix timestamp in milliseconds (UTC).

Example:

1753142400000

payment

object

Present when the create call included payment.paymentMethodId.

Show child attributes

Overview

B2B · Orders

B2B · Products

B2B · Balance & account

B2B · Deposits

B2B · Refunds

Retailer · Catalog

Retailer · Checkouts

Retailer · Refunds

Retailer · Webhook management

Retailer · Account

Webhook payloads

Create a checkout for an end-customer

Authorizations

Body

Response