The cardyay API

1. Apply to sell and wait for your business to be approved. The API answers 403 until then.
2. In your dashboard, open Developers and create an API key. The account owner does this. The key is shown once.
3. Call the API from your server. Start with the request below: it tells you which business the key belongs to and lists your cards.

curl https://cardyay.com/api/v1/me \
  -H "Authorization: Bearer cyk_your_key"

The base address is https://cardyay.com/api/v1. Every call is made over HTTPS from your server. Never put a key in a web page or a mobile app: anyone holding it can redeem your cards.

Send your key in the Authorization header as a Bearer token. Keys start with cyk_.

Authorization: Bearer cyk_your_key

• A key acts for one business and can only ever see that business’s cards, redemptions and pay requests.
• We store a fingerprint of the key, not the key. If you lose it, revoke it in your dashboard and create a new one.
• A missing, wrong or revoked key answers 401 unauthorized. A key of a business that is not approved answers 403 business_not_approved.

• Send and receive JSON. A request with a body needs Content-Type: application/json.
• Amounts are whole numbers in minor units: cents for USD, pence for GBP. 2500 is $25.00. Each amount comes with its currency.
• Times are ISO 8601 in UTC, such as 2026-11-12T10:15:00.000Z. Webhook timestamps are Unix seconds.
• A card’s code is never returned by the API and never sent in a webhook. A code is as good as money, so cards are named by their id and the last four characters of the code.
• Each key may make 120 requests a minute. Past that the API answers 429 rate_limited with a Retry-After header in seconds.
• Codes that match no card are counted: after 60 in ten minutes, lookups and redemptions with that key answer 429 too_many_misses until the ten minutes are over.
• No response is cacheable: every one carries Cache-Control: no-store.

Every error has the same shape, with a stable code for your program and a message for a person:

{
  "error": {
    "code": "insufficient",
    "message": "The card does not have enough balance for that amount."
  }
}

The card object appears in several answers and always reads the same:

{
  "id": "crd_4k8m2x9q7w3e5r6t1y0p8s2d",
  "last4": "QRTW",
  "status": "active",
  "currency": "USD",
  "initialMinor": 5000,
  "balanceMinor": 5000,
  "expiresAt": "2027-11-12T10:15:00.000Z",
  "brand": { "slug": "fernwood", "name": "Fernwood Tea" }
}

Sometimes your own checkout cannot take a customer’s money: their card is declined by your processor, you do not accept their payment method, or you do not take cards at all. Instead of losing the sale, hand the payment to cardyay. You get a link for that one customer and that one amount, send them to it, and we tell your server when it is paid.

This works best with a card set up as “The payment tops up something on our side” (mode: "credit"): no code is issued, the payment simply arrives with your reference attached. With a code card the customer is e-mailed a gift card code instead, which they then spend with you.

1. Your checkout fails. Keep the cart or order open on your side and note its id.
2. Create a pay request. Your server calls POST /requests with the card’s link name, the customer’s e-mail, the amount, your order id as reference, and a returnUrl on your own website.
3. Send the customer to the link. Redirect their browser to the url in the answer. The page shows your card and the amount; they pay by card.
4. We tell your server. As soon as the payment goes through we POST a signed card.sold event to your webhook. Its data.order.reference is your order id and data.order.requestId is the pay request’s id. Mark the order paid when you receive it.
5. The customer comes back. After paying they see a button that returns them to your returnUrl, exactly as you gave it. Do not treat that visit as proof of payment: rely on the webhook, or ask GET /requests/{id}.

curl -X POST https://cardyay.com/api/v1/requests \
  -H "Authorization: Bearer cyk_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "card": "kestrel-play",
    "email": "sam@example.com",
    "name": "Sam",
    "amount": 2000,
    "reference": "cart-58213",
    "message": "Top-up for player 88213",
    "returnUrl": "https://kestrelplay.example/checkout/58213/done"
  }'

{
  "id": "req_2b4d6f8h0j1k3m5n7p9q2r4s",
  "url": "https://cardyay.com/r/req_2b4d6f8h0j1k3m5n7p9q2r4s?k=5f0c…",
  "expiresAt": "2026-11-26T10:15:00.000Z"
}

A link works until it is paid, cancelled or its expiresAt passes. It can be paid once. Without a webhook you can poll GET /requests/{id} until status is paid.

A webhook is a POST we make to your server when something happens to one of your cards. Set the endpoint for each card in your dashboard under Developers. It must be a public https:// address. When you save it we create a signing secret (it starts with whsec_) and show it once.

POST /webhooks/cardyay HTTP/1.1
Content-Type: application/json
User-Agent: cardyay-webhooks/1.0
X-Cardyay-Event: card.sold
X-Cardyay-Delivery: whd_7t5r3e1w9q8p6n4m2k0j8h6g
X-Cardyay-Signature: t=1794478767,v1=5d41402abc4b2a76b9719d911017c592…

• Answer with any 2xx status within 10 seconds to accept an event. Do the slow work after you have answered.
• Anything else, a timeout or a redirect counts as a failure. We try up to 8 times over about half an hour, waiting longer each time, then stop and mark the delivery as failed.
• The same event can arrive more than once. Its id (also in X-Cardyay-Delivery) is the same on every attempt: ignore an id you have already handled.
• Events can arrive out of order. The balance in the newest event you have for a card is the one to trust.
• Your dashboard lists recent deliveries with your server’s answers, and has a button that sends a test card.sold. Test events carry "test": true at the top level; real ones have no such field.

card.sold

A card was paid for. For a code card the buyer has been e-mailed a code and the card is active with its full balance:

{
  "id": "whd_7t5r3e1w9q8p6n4m2k0j8h6g",
  "event": "card.sold",
  "created": 1794478767,
  "data": {
    "card": {
      "id": "crd_4k8m2x9q7w3e5r6t1y0p8s2d",
      "last4": "QRTW",
      "amount": 5000,
      "currency": "USD",
      "balance": 5000,
      "status": "active"
    },
    "mode": "code",
    "order": {
      "number": "CY-7F3K-9QAM",
      "reference": null,
      "buyerEmail": "sam@example.com",
      "recipientEmail": "alex@example.com",
      "requestId": null
    }
  }
}

For a credit card there is no code. The payment is yours to apply now: credit data.card.amount to the account or order named in data.order.reference (what the buyer typed, or the reference of your pay request). The card arrives already redeemed with a balance of 0:

{
  "id": "whd_3s5u7w9y1a3c5e7g9j1m3p5r",
  "event": "card.sold",
  "created": 1794478767,
  "data": {
    "card": {
      "id": "crd_6n8q0s2v4x6z8b0d2f4h6k8m",
      "last4": null,
      "amount": 2000,
      "currency": "USD",
      "balance": 0,
      "status": "redeemed"
    },
    "mode": "credit",
    "order": {
      "number": "CY-AC4D-EF7G",
      "reference": "cart-58213",
      "buyerEmail": "sam@example.com",
      "recipientEmail": "sam@example.com",
      "requestId": "req_2b4d6f8h0j1k3m5n7p9q2r4s"
    }
  }
}

card.redeemed

Value was taken off a card, from your dashboard or through the API. data.card.balance is what is left; status becomes redeemed when it reaches 0.

{
  "id": "whd_5v7x9z1b3d5f7h9k1n3q5s7t",
  "event": "card.redeemed",
  "created": 1794482367,
  "data": {
    "card": {
      "id": "crd_4k8m2x9q7w3e5r6t1y0p8s2d",
      "last4": "QRTW",
      "currency": "USD",
      "balance": 3000,
      "status": "active"
    },
    "redemption": { "id": "evt_9h3n5v7b2c4x6z8m1k0j3g5f", "amount": 2000, "reference": "POS-1042" }
  }
}

card.reversed

A redemption was undone and its amount is back on the card. data.redemption.id is the redemption that was undone.

{
  "id": "whd_8a0c2e4g6j8m0p2r4t6w8y0b",
  "event": "card.reversed",
  "created": 1794482967,
  "data": {
    "card": {
      "id": "crd_4k8m2x9q7w3e5r6t1y0p8s2d",
      "last4": "QRTW",
      "currency": "USD",
      "balance": 5000,
      "status": "active"
    },
    "redemption": { "id": "evt_9h3n5v7b2c4x6z8m1k0j3g5f", "amount": 2000 }
  }
}

card.voided

A card was cancelled because its order was refunded. It can no longer be redeemed. If you had already credited something for it, take that back.

{
  "id": "whd_1d3f5h7k9n1q3s5v7x9z1b3d",
  "event": "card.voided",
  "created": 1794565167,
  "data": {
    "card": {
      "id": "crd_4k8m2x9q7w3e5r6t1y0p8s2d",
      "last4": "QRTW",
      "amount": 5000,
      "currency": "USD"
    },
    "order": { "number": "CY-7F3K-9QAM", "reference": null }
  }
}

Anyone can POST to a public address, so check that an event really came from us before acting on it. Every delivery carries an X-Cardyay-Signature header:

X-Cardyay-Signature: t=<unix>,v1=<hex hmac-sha256 of "<t>.<raw body>">

1. Split the header on commas to get t (when we signed it, in Unix seconds) and v1 (the signature).
2. Refuse the event if t is more than 5 minutes away from your server’s clock. That stops an old, captured request from being replayed.
3. Compute HMAC-SHA256 of the text <t>.<raw body> with your signing secret as the key, in lowercase hex. Use the body exactly as it arrived, before any JSON parsing.
4. Compare your result with v1 using a constant-time comparison. If they differ, answer 400 and do nothing.

In Node.js, with Express:

import crypto from 'node:crypto'
import express from 'express'

const SECRET = process.env.CARDYAY_WEBHOOK_SECRET // whsec_...
const TOLERANCE_SECONDS = 300

function verify(rawBody, header) {
  // Header: t=<unix seconds>,v1=<hex hmac-sha256 of "<t>.<raw body>">
  const parts = Object.fromEntries(
    String(header ?? '').split(',').map((part) => part.trim().split('='))
  )
  const timestamp = Number(parts.t)
  if (!Number.isFinite(timestamp) || !parts.v1) return false
  if (Math.abs(Date.now() / 1000 - timestamp) > TOLERANCE_SECONDS) return false

  const expected = crypto
    .createHmac('sha256', SECRET)
    .update(`${parts.t}.${rawBody}`)
    .digest('hex')
  const a = Buffer.from(expected)
  const b = Buffer.from(parts.v1)
  return a.length === b.length && crypto.timingSafeEqual(a, b)
}

const app = express()

// Keep the body exactly as it was sent: the signature covers the raw bytes.
app.post('/webhooks/cardyay', express.raw({ type: 'application/json' }), (req, res) => {
  const rawBody = req.body.toString('utf8')
  if (!verify(rawBody, req.get('X-Cardyay-Signature'))) return res.sendStatus(400)

  const event = JSON.parse(rawBody)
  if (event.test) return res.sendStatus(200) // sent from "Send a test event"

  // event.id is the same on every retry: skip an id you have already handled.
  if (event.event === 'card.sold') {
    // credit the account in event.data.order.reference with event.data.card.amount
  }
  res.sendStatus(200)
})

Rotating the secret in your dashboard replaces it at once: deploy the new secret to your server straight after you rotate, or events signed in between will fail your check and be retried.

The HTTP status tells you the kind of problem; error.code tells you which one. Codes do not change; messages may be reworded.

Something here does not match what you see? Contact us through the help centre and include the X-Cardyay-Delivery id or the time of the call.