Integration overview
What to build, where each request runs, and how the buyer journey fits together.
Build a storefront that lists Verity raffles, takes ticket payments, and shows tickets and prizes. You can also let prize holders sell back eligible items and arrange delivery from your storefront.
These guides use Verity-collected payments with an external Solana wallet. Your buyer pays the checkout's USDC amount directly to Verity. Partner-collected payments require a separate agreement and recipient/fulfilment setup; do not switch modes by changing the sample requests. Existing payment-first clients have a separate compatibility guide.
Three parts of the integration
| Part | Responsibilities |
|---|---|
| Your frontend | Display raffles, connect the buyer's wallet, request approvals, and show purchase and prize progress |
| Your server | Authenticate your users, call the partner API with your secret key, save purchase references, and verify webhooks |
| Verity | Reserve and confirm entries, provide results, deliver prizes, and process supported sellbacks and shipping orders |
For ticket purchases: browser → your authenticated server → partner API. Your server returns only the public checkout details to the browser. Restrict your proxy to the endpoints your app needs; do not expose an arbitrary authenticated Verity proxy.
For collection actions: browser → wallet API, using a separate signed wallet session and a registered storefront origin. Your partner API key is never sent to the browser.
Build one buyer journey
Follow Alex, your signed-in buyer with the stable reference buyer_123:
- Set up access: choose the environment, obtain your partner key and register your origin.
- Display raffles: Alex opens a live raffle that allows new sales.
- Reserve tickets: your server saves a purchase key and creates a checkout for Alex.
- Approve payment: Alex's wallet signs the exact quoted transfer. Your app saves it before broadcasting.
- Recover and confirm: a reload resumes the same purchase; only
completedshows confirmed tickets. - Show the collection: after a win is delivered, check the current holder's wallet before offering actions.
- Sell back or request delivery: the holder approves the chosen action. Neither action requires minting another NFT.
Use webhooks to keep your server records current even when Alex closes the browser.
Who signs and broadcasts?
| Action | Builds the transaction | Signs | Broadcasts |
|---|---|---|---|
| Buy tickets | Your app, from checkout payment details | Paying wallet | Your app, after saving signed bytes and signature |
| Sell back | Verity | Current NFT holder | Verity, after your app submits the signed transaction |
| Redeem for delivery | Verity | Current NFT holder | Verity, after your app submits the signed transaction |
Sellback and redemption require sign-only wallet support. Do not use signAndSendTransaction for those prepared transactions.
Choose your launch scope
Ticket checkout, recovery, and clear ticket/results history form the core integration. Sellback and shipping can be added independently. If you omit either, do not show a button that cannot complete the flow. There is no documented automatic website handoff in this guide; agree any hosted fulfilment journey with Verity before advertising it.
Start with Your first integration, then use the sample integration guide and launch checklist.