Prize redemption
Optional wallet-based shipping for winners who want their physical items.
You can send winners to Verity to redeem, or offer shipping from your own storefront. If you build it yourself, the buyer connects the wallet holding their prize and approves the redemption transaction.
Connect the buyer's wallet
Redemption uses a separate API base URL and authentication:
| Environment | Wallet API base URL |
|---|---|
| Staging | https://api-staging.theverity.xyz/api/v1/redeem |
| Production | https://api.theverity.xyz/api/v1/redeem |
Register your storefront origin with Verity first so browser requests are allowed.
- Call
POST /auth/noncewithwallet,platform(your slug),domain, anduri. - Ask the wallet to sign the returned
messageexactly as received. - Call
POST /auth/verifywithwallet,message, and the base58signature. - Use the returned
accessTokenasAuthorization: Bearer <accessToken>for redemption calls.
Your partner API key is not used in this flow. If the wallet session expires, sign in again and resume the existing order.
Select items and show a quote
Call GET /prizes and let the holder choose items where redeemable is true. A request accepts either prizeId or prizeIds containing 1–50 distinct IDs.
POST /shipping-groups can preview the packaging groups for a selection. Then call POST /quote with the selected items and the buyer's address. Use the options returned by the quote rather than calculating shipping yourself.
| Quote field | Display |
|---|---|
packages | Boxes in this shipment |
insuredValueUsd | Total insured value |
shippingFeeUsd | Shipping, including insurance |
insuranceFeeUsd | Insurance portion already included in shipping; do not add it twice |
redemptionFeeUsd | Redemption fee |
totalFeeUsd | Amount payable at checkout |
estDutiesTaxesUsd | Separate estimated customs charges; null means unavailable, not zero |
Display customs estimates separately from the total. Suggested copy:
Estimated based on shipment value, shipping, insurance, and applicable taxes. Actual charges may vary and are NOT INCLUDED in the total above. DHL will collect any applicable charges separately during customs clearance.
Render the returned estimate for every destination. Do not hardcode tax rates or exemption thresholds in your storefront.
Preserve the full address
Keep the building, apartment/unit number and street in addressLine1 and addressLine2. Put city, state, postal code and country in their own fields. Country is a two-letter code such as MY.
The API checks whether the street can fit DHL's address lines without dropping information. If validation fails, show the returned message and let the buyer correct the address. Do not silently truncate it. An available shipping quote is not proof that a particular apartment or recipient exists.
See the quote reference for exact field limits.
Prepare, approve, submit
Prepare the selected option
Call POST /prepare with the same items and address, productCode, and shownShippingFeeUsd from the selected quote. If the rate increased, RATE_CHANGED requires a new quote and buyer confirmation.
Save data.redemption.id before opening the wallet.
Request wallet approval
Ask the buyer to sign data.transaction unchanged. Then send its base64 signed value as signedTransaction to POST /{redemptionId}/submit.
Do not edit the prepared transaction. Follow its validity limits and use the same order for recovery.
Show order progress
Poll GET /redemptions/{redemptionId}. The order is in data.redemption. Payment confirmation does not mean the package has shipped; display the returned shipment and tracking state.
Multiple approvals and interrupted orders
Large selections can require multiple wallet approvals. Show payment_confirmed_steps / payment_step_count and payment_paid_usd.
Call POST /{redemptionId}/next-transaction to continue. If next is null, poll the order to distinguish a pending confirmation from completed payment. Otherwise sign next.transaction and submit it to the same order.
Keep a Resume redemption action after reload. Confirmed steps are not repeated, and a partially paid order must not be described as uncharged. Never prepare a replacement order while an existing one is unresolved.
Polling and limits
Use one status request at a time and back off while waiting. Wallet reads allow 30 requests per minute; writes allow 60 per hour. Quote and prepare also share a 30-per-hour allowance. Respect Retry-After on 429 RATE_LIMITED.