Reserve tickets before collecting payment
Supported for both collection modes. Reuse the same Idempotency-Key on request retries. The response contains the immutable quote, payment_deadline and settlement_deadline. Verity-collected buyers must use the exact returned memo, which includes the checkout UUID. Never initiate payment after payment_deadline. The verified payer wallet is checked against the wallet limit before ticket confirmation; a paid checkout exceeding that limit is refunded. After settlement expires, inventory is released while unknown payments remain tracked. refund_pending/refunded includes refund_operation_id, which can be polled at GET /payments/{operationId} or acknowledged for partner-collected refunds. refund_only=true means a later successful payment will be refunded, not issued tickets. Keep polling; do not start a replacement payment.
PartnerApiKeyAuthorizationBearer <token>Authorization: Bearer <your_api_key>
Keep this credential on your server, never in browser or mobile app code.
A missing, invalid or disabled key returns 401 PLATFORM_KEY_INVALID.
Ask Verity to replace a lost or exposed key.
raffleId*integer1 <= valueIdempotency-Key*stringlength <= 200application/json- body
external_user_ref*string1 <= length <= 255display_name?|1 <= length <= 64qty*integer1 <= value <= 1000Checkout reserved, or the original checkout replayed. Inspect status; no payment is implied.
application/json- response
success*booleandata*curl -X POST 'https://api-staging.theverity.xyz/api/v1/platform/raffles/77/checkouts' \ -H 'Idempotency-Key: checkout-example-001' \ -H 'Authorization: Bearer <your_partner_api_key>' \ -H 'Content-Type: application/json' \ -d '{ "external_user_ref": "buyer_123", "display_name": "Alex", "qty": 2}'{ "success": true, "data": { "id": "a1765f38-8c06-46e4-bb5b-9913aa0c8ae9", "request_key": "checkout-example-001", "raffle_id": 77, "purchase_id": null, "status": "awaiting_payment", "qty": 2, "total_usd": 100, "payment_deadline": "2026-10-28T10:05:00Z", "settlement_deadline": "2026-10-28T10:15:00Z", "created_at": "2026-10-28T10:00:00Z", "tickets": [], "retry_allowed": false, "error": null, "refund_only": false, "refund_operation_id": null, "source_payment_signature": null, "payment": { "treasury_ata": "<destination token account from API>", "usdc_mint": "<token mint from API>", "decimals": 6, "memo_prefix": "your-platform:77", "memo": "your-platform:77:buyer_123:a1765f38-8c06-46e4-bb5b-9913aa0c8ae9" } }}