Skip to main content
Redeem lets the owner of a vaulted card request physical delivery. Every /v2/redeem request requires your backend’s builder key and a wallet session for the same EOA. GET routes use redeem:read. Other methods use redeem:write. Checkout also requires the wallet’s signature.

Vault regions and redemption batches

List vault regions to get the wallet’s eligible card count in each region. Once the user chooses a region, list its redeemable cards with countryCode, for example HK. Each card has a regionCountryCode and vaultDisplayName. Group up to 50 distinct token IDs from one vault region per checkout. For example, two Hong Kong cards can share a quote. A Malaysia card needs a separate quote and checkout even if all three cards are going to the same recipient. Set the delivery country separately in address.countryCode.

From card to delivery

  1. Validate the destination. Send countryCode, addressLine1, city and postalCode as top-level fields to Validate a delivery address. Include addressLine2 and state as applicable. Check status and detail before continuing.
  2. Get a shipping quote. Send the selected tokenIds and the destination in an address object to Quote shipping. Save quoteId and expiresAt. Show the available couriers, insurance and the quoted handlingFeeInUsd, including zero when a waiver applies. Your app supplies the country list for the form.
  3. Prepare checkout. Send quoteId, courierId, recipient and insurance to Prepare checkout. Save preparationId. Show the cards, recipient, destination and total. List estimated duties and taxes separately.

Keep the reviewed intent

Completing redemption permanently burns the selected NFTs. Before requesting the wallet signature:
  • Match the wallet, chain, token IDs, recipient, address, courier and totalFeeInUsdt to the order the user reviewed.
  • Check the trusted token and contracts, expiry, balance and allowance. If the wallet needs to approve USDT to Permit2, wait for confirmation.
  • Verify that the witness in permitTypedData matches the hash of the batch in redemptionTypedData. Have the wallet sign the permit. If anything changes, return to review.
Submit checkout once with preparationId and signature. Save the returned requestId to track the order.

Expiry and recovery

Shipping quotes expire after ten minutes. A preparation inherits its quote’s deadline. If either expires before submission, request a fresh quote and have the user review the price again. If you lose the checkout response, read GET /checkout/{preparationId} before sending another payment. Checkout status is retained for 24 hours. If the wallet session expires, verify the same wallet again to resume. Keep pending IDs per wallet and chain. Keep signatures, tokens and shipping details out of recovery logs.

Orders and tracking

List orders for a summary or get one order with its requestId. If a new order has yet to appear in the list, use checkout status or the order detail. Refresh courier tracking when you need a shipping update. Display shipmentStatus, trackingNumber, trackingUrl and trackingLastSyncedAt when available. On deployments that expose trackingStage, it distinguishes processing, vault release, transit and delivery. Order creation and update times alone do not establish dispatch. Check your deployment’s HTTP reference for the hasCancelledToken order filter and total count. Where available, hasCancelledToken=true selects orders with at least one owner-cancelled card. total counts matching orders across pages.