Gift vouchers online

This is the other direction from Gift vouchers: there your shop took the money and recorded a paid voucher. Here Shyni opens the payment at the studio's own gateway, and the voucher becomes active once the gateway reports it.

You need a key with vouchers:write and a studio on the Pro subscription. A publishable key (shyni_pk_...) works too, so the buyer can start from the browser.

BASE_URL="https://api.shyni.io"
API_KEY="shyni_sk_REPLACE_ME"

1. Open the purchaseCopy Anchor Link

POST /api/v1/gift-vouchers/purchases needs an Idempotency-Key (see Idempotency). value is in minor units of the studio's currency, from 10000 to 10000000 (100 to 100,000 CZK). value, buyer and motif are required (a missing one is 400 INVALID_INPUT naming the field); billing is optional. motif is the voucher design: CLASSIC, INK, LINES or CLEAN. There is no return URL.

curl -sS -X POST "$BASE_URL/api/v1/gift-vouchers/purchases" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: cart-4471-voucher" \
  -d '{
    "value": 150000,
    "buyer": { "name": "Jana Novakova", "email": "jana@example.cz" },
    "motif": "CLASSIC"
  }'

{
  "id": "7c0b3f1e-2f5a-4c1b-9d0e-5a8f2b6c4d10",
  "state": "CREATED",
  "value": 150000,
  "currency": "CZK",
  "motif": "CLASSIC",
  "buyer": { "name": "Jana Novakova", "email": "jana@example.cz" },
  "paymentUrl": "https://gate.gopay.cz/gw/v3/3000000001",
  "createdAt": "2026-10-26T09:15:00Z"
}

A replay with the same key returns the first answer and opens no second payment. The same key with a different body is 422 IDEMPOTENCY_KEY_MISMATCH.

2. Redirect the buyerCopy Anchor Link

Send the buyer to paymentUrl, the studio's payment gateway page. After paying, the gateway returns the buyer to the studio's voucher status page on its Shyni storefront; you cannot supply a return URL.

window.location.assign(purchase.paymentUrl);

3. Wait for the webhookCopy Anchor Link

The response never carries the voucher code: the code is a bearer instrument, so it is withheld until the money has landed, and until then there is nothing to read by code. Once the gateway reports the payment, the voucher becomes ACTIVE, the buyer gets the delivery mail and the gift_voucher.sold webhook fires. Its payload is the voucher (see gift_voucher.sold), and afterwards you can read it with Get a gift voucher using its code. A purchase still unpaid an hour after it was opened is written off by Shyni, so the payment link works for about an hour.

ErrorsCopy Anchor Link

• 409 CONFLICT: the studio has no online payment gateway connected (or the payment could not be opened), so nothing is payable. Vouchers cannot be sold online there; fall back to your own flow from Gift vouchers or hide the button.
• 409 STUDIO_NOT_PUBLISHED: the studio is not published (a test studio is always sellable). Both are 409, so branch on code.
• 400 INVALID_INPUT with field: a value outside the allowed range or a bad buyer e-mail.
• 403 PLAN_REQUIRED: the studio is below the Pro subscription.
• 429 RATE_LIMITED: the calls share the storefront's rate limits per IP and per studio. A publishable key is limited on the browser's IP; a secret key may name the end customer's address in the optional Shyni-Customer-IP header (an invalid value is 400 INVALID_INPUT). See Rate limits.

Reference: Sell a gift voucher online.