Skip to main content

Reward link

Give one gift card from your pool to one person by sharing a single link — no account, no login, nothing for the recipient to install.

A reward link is how an individual gift card leaves your pool and reaches a customer. When you want to hand someone a card, you generate a reward link: Paylode reserves one card of the denomination you ask for, binds it to a fresh single-use link, and gives you back a URL you can drop into an email, a text, a chat message, or a page. The recipient opens it, reveals the card, and redeems it. The link carries the card; there's nothing else to authenticate.

This is deliberately anonymous. You decide who to send the link to; whoever opens it and reveals the card gets it. That makes reward links easy to distribute, and it's why the security guidance below matters.

How it works​

A reward link has three states over its life:

  • RESERVED — the link exists and a card is set aside for it, but no one has revealed the card yet. This is the state at generation. The card is held out of your available inventory while the link is reserved.
  • REVEALED — the recipient has opened the link and revealed the card. This state is terminal and reload-safe: if the recipient reloads the page or comes back next week, they see the same card again. Revealing doesn't consume the link a second time.
  • EXPIRED — the link's expiry passed before anyone revealed it. This state is terminal too, and the reserved card is returned to your pool so it can be handed out again.

You set the expiry when you generate the link. Until the recipient reveals the card, an unrevealed link is a soft hold on inventory — let it expire and you get the card back.

The Allocation Page​

Recipients don't call an API. Each reward link points at a Paylode-hosted Allocation Page at rewards.paylode.com that renders the card: the brand, the denomination, and a reveal action. Before reveal, the page shows the card's presentation but not its code; after reveal, it shows the redeemable code. If the link has expired, the page renders that state instead. You share the link; the page does the rest.

Security for integrators​

The link is the bearer instrument. Anyone who has the full URL can reveal the card, so treat a reward link like a secret:

  • The token is part of the link itself — anyone holding the full URL can reveal the card. Treat the whole link as the secret: don't shorten, rewrite, or repackage it in a way that exposes it, and don't post it anywhere public or scrapable.
  • Keep reward-link URLs out of your own application logs, analytics events, and error reports.
  • Send each link to exactly one recipient over a private channel.

In the API​

The recipient's flow is anonymous and drives two operations on the gift service: view the link (to render the page) and reveal the card. Both authenticate with the link's token in the X-Reward-Token header — there's no API key and no user account.

curl "https://gift.paylode.com/reward" \
  -H "X-Reward-Token: sk_example_reward_9d2fac81b0e34c17"
const res = await fetch("https://gift.paylode.com/reward", {
  headers: { "X-Reward-Token": "sk_example_reward_9d2fac81b0e34c17" }
});
const view = await res.json();

While the link is still reserved, the view carries the card's presentation and state, but not the code (trimmed to the display fields that matter here):

{
  "state": "RESERVED",
  "gift": {
    "title": "Example Coffee Co.",
    "denomination": 50,
    "currency": "USD",
    "country": "US"
  }
}

Revealing the card returns the same view shape with the redeemable reward populated (the code, and any PIN the brand issues). Once revealed, the view keeps returning that code on reload. For the exact view and reveal schemas and error responses, see getRewardLink and revealRewardLink on developers.paylode.com.

Generating a link from a pool (the step you run) and distributing links at scale are covered in Share gift-card reward links.

  • Gift Cards overview — what the product does and how this page fits it.
  • Gift card — the inventory a reward link draws from.
  • Boost — reward journeys can deliver a card as a reward.