Gift Card Issuing API

1. 1

   Open the Issuing tokens tab

   Sign in, go to the "Gift cards & direct top-up" page, switch to the "Issuing tokens" tab and click "New issuing token".

2. 2

   Name it and set optional limits

   The name can be up to 60 characters, such as "Card-key storefront". The IP allowlist and the daily limit are optional; leave them empty for no limit. The platform sets no defaults.

3. 3

   Save the token right away

   The token starts with wkt_ and is shown only once. If you lose it, revoke it and create a new one. Creating a token sends an in-app notification and an email.

Base URL

https://wokey.ai/api/issuer/v1

Authentication

Send Authorization: Bearer wkt_… with every request. A signed-in website session cannot call these endpoints, and an issuing token cannot call any other endpoint.

Requests & responses

Bodies are JSON. Amounts in responses are strings with two decimals (for example "10.00"); times are ISO 8601 in UTC.

curl -X POST https://wokey.ai/api/issuer/v1/codes \
  -H "Authorization: Bearer wkt_YOUR_ISSUING_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-20261017-0001" \
  -d '{ "sourceType": "provider", "amountUsd": 10, "count": 1, "label": "order-20261017-0001" }'

{
  "batch": {
    "id": "icb_…",
    "sourceType": "provider",
    "amountUsd": "10.00",
    "count": 1,
    "totalUsd": "10.00",
    "label": "order-20261017-0001",
    "createdAt": "2026-10-17T08:00:00.000Z"
  },
  "replayed": false,
  "codes": [
    {
      "id": "ic_…",
      "batchId": "icb_…",
      "kind": "code",
      "sourceType": "provider",
      "amountUsd": "10.00",
      "codeHint": "7K2M",
      "status": "active",
      "label": "order-20261017-0001",
      "createdAt": "2026-10-17T08:00:00.000Z",
      "redeemedAt": null,
      "redeemedByMaskedEmail": null,
      "voidRequestedAt": null,
      "voidEffectiveAt": null,
      "voidedAt": null,
      "frozenAt": null,
      "code": "WK-4F9Q-T3XA-8HRB-7K2M",
      "redeemUrl": "https://wokey.ai/redeem#WK-4F9Q-T3XA-8HRB-7K2M"
    }
  ]
}

code is the redemption code and redeemUrl is the redemption link; send either to the buyer. The buyer redeems it after signing in to Wokey, and the face value goes to their API credits.

• Creating gift cards and direct top-ups both require an idempotency key. Your order ID is a good choice.
• Keys are unique per account and shared between the website and the issuing API, regardless of which token sent the request.
• Repeating a request with the same key and the same parameters charges nothing and returns the first result with replayed set to true; a replayed create returns the same codes again.
• The same key with different parameters (sourceType, amountUsd, count, and the recipient for direct top-ups) returns 409 idempotency_key_conflict.
• After a network timeout or a 5xx response, retry with the same key; you will not be charged twice.

• Creating gift cards and direct top-ups: at most 60 per minute per account (website and issuing API combined).
• Reading gift card details (with the code): at most 120 per minute per account.
• At most 500 cards per batch; face value from 1 to 1,000,000 USD per card.
• At most 20 unrevoked issuing tokens per account, and at most 20 IPs in each token's allowlist.

Security recommendations

• Keep the token on the server side (your storefront backend or your own server). Never put it in web front-end code, an app, or a public repository.
• If you have a fixed outbound IP, set an IP allowlist. Entries match single IPs exactly; ranges are not supported.
• Set a daily limit to cap the loss if the token leaks. The limit counts gift cards plus direct top-ups per UTC day.
• Changing your password or signing out of all sessions does not revoke issuing tokens. If you suspect a leak, revoke the token on the "Issuing tokens" tab; it stops working immediately.
• The "Issuing tokens" tab shows when and from which IP each token was last used. Check it from time to time.