Sending rewards

Find what you can send

Pull the catalog once (and cache it — it changes rarely):

curl "https://paybilt-rewards-api.fly.dev/v1/catalog?currency=USD&country=US" \
  -H "Authorization: Bearer $REWARDLY_KEY"

Each brand has a brandKey and a list of items. Items are either FIXED_VALUE (one faceValue) or VARIABLE_VALUE (a minValue–maxValue range). You need:

• an item's utid to send a FIXED reward
• brandKey values to restrict a CHOICE reward (optional)

Send a fixed reward

The recipient gets exactly the card you choose. valueCents must match the item's face value (or fall inside its range for variable items):

curl -X POST https://paybilt-rewards-api.fly.dev/v1/rewards \
  -H "Authorization: Bearer $REWARDLY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "FIXED",
    "utid": "U561593",
    "valueCents": 2500,
    "recipient": { "email": "casey@example.com", "firstName": "Casey" },
    "message": "Happy birthday!",
    "externalId": "user-8841-bday-2026"
  }'

The card is issued immediately — watch for the card.issued webhook or poll the reward until its card appears.

Send a choice reward

The recipient splits the value across any cards they like:

curl -X POST https://paybilt-rewards-api.fly.dev/v1/rewards \
  -H "Authorization: Bearer $REWARDLY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "CHOICE",
    "valueCents": 10000,
    "recipient": { "email": "casey@example.com", "firstName": "Casey" },
    "allowedBrandKeys": ["B916708"],
    "expiresAt": "2026-12-31T23:59:59Z"
  }'

Cards are issued as the recipient picks them; the reward becomes PARTIALLY_REDEEMED and finally REDEEMED when the value is used up.

Deliver the link yourself

The create response includes redemptionUrl. If you'd rather show the link in your own product (in-app inbox, SMS, chat), use it directly — the email still goes out, and you can re-trigger it any time with POST /v1/rewards/:id/resend.

Cancel a reward

Unredeemed value can be reclaimed at any time:

curl -X POST https://paybilt-rewards-api.fly.dev/v1/rewards/rw_123/cancel \
  -H "Authorization: Bearer $REWARDLY_KEY"

Whatever hasn't been turned into cards flows back to your wallet, and the recipient's link stops working for new picks. Cards already issued stay valid.