Your first integration
From your first API call to a confirmed raffle ticket.
This guide uses Verity-collected payments: your buyer pays USDC directly to Verity. Your server calls the partner API; your buyer approves the payment in their wallet.
Before you begin
Ask Verity to provision your partner account, invite your owner, and assign a staging raffle. Sign in to the partner workspace with the invited email and accept the invitation. Under Integration, find your platform ID and manage your API credentials. Owners and developers can replace credentials; new values are shown once, and replacement immediately invalidates the old value. Coordinate replacement with your server deployment.
You will also need a Solana wallet integration. Use the network and USDC mint confirmed for your test environment.
Keep the API key on your server
Your frontend calls your own server. Never put the partner API key in browser code or a NEXT_PUBLIC_ environment variable.
Fetch your raffles
Run this from your server or terminal, using your staging key:
export VERITY_BASE_URL="https://api-staging.theverity.xyz/api/v1/platform"
# Set VERITY_API_KEY in your server environment.
curl "$VERITY_BASE_URL/raffles?limit=10" \
-H "Authorization: Bearer $VERITY_API_KEY"The response contains data.items and data.total. Choose a raffle whose status is live. An empty list means no raffles are currently attached to your platform; contact Verity.
Reserve the buyer's tickets
Create a checkout before opening the wallet. Save one unique purchase key and reuse it if the request needs to be retried.
curl "$VERITY_BASE_URL/raffles/77/checkouts" \
-H "Authorization: Bearer $VERITY_API_KEY" \
-H "Idempotency-Key: checkout-example-001" \
-H "Content-Type: application/json" \
-d '{"external_user_ref":"buyer_123","qty":1}'Replace 77 with your raffle ID. Save data.id, data.total_usd, data.payment_deadline, and data.payment.
Have the buyer pay
Pass the public checkout details to your frontend. Build one USDC transfer using the returned destination and exact memo. Ask the buyer to sign and submit it before payment_deadline.
See Build the wallet payment for the transaction format.
Register the payment and confirm tickets
Send the transaction signature to your server, then to Verity:
curl "$VERITY_BASE_URL/raffles/77/checkouts/$CHECKOUT_ID/payment" \
-H "Authorization: Bearer $VERITY_API_KEY" \
-H "Content-Type: application/json" \
-d "{\"tx_signature\":\"$TX_SIGNATURE\"}"A 202 means verification has started. Poll GET /raffles/77/checkouts/{checkoutId}. Show tickets only when data.status is completed.
Do not wait for finalization before registering a checkout payment. Register it promptly after submission. A timeout is a reason to check the same purchase, not to pay again.