Purchase intents

Once a listing is created, it is open to receive purchase intents from buyers. A purchase intent signals an intention to buy from a listing. Within the request, it must specify the listing ID, the payment provider the buyer plans to use, quantity to purchase, and recipient details.

Because a purchase intent is made against a listing, it must accept the listing's rules and policies. For example, it must use one of the payment providers prescribed by the listing, be bound by the max per user and max per transaction limit, and permitted by the listing's allowlist, if there is one. If a purchase intent is valid, the platform puts a "hold" on the items requested and awaits the payment.

If your purchase intent specifies Stripe as your payment provider, you must then provide a way for your buyer to complete the payment within the payment session duration as imposed by the listing. The platform uses webhooks to actively communicate with Stripe to detect any status changes. If the platform detects that a payment is successful, it moves on to fulfill the purchase intent and deliver the items. If not, and the session has passed, the platform marks the purchase intent expired and removes the "hold". You can also proactively cancel a purchase intent if the buyer does not plan to proceed with the purchase.

Depending on the recipient details you provide, the platform fulfills the sale by either an email claim, a mint voucher or a transfer on-chain. Specific payment providers may require specific recipient details be present. For example, if you use EMAIL_CLAIM as a payment provider, you must provide an email address. If you use MINT_VOUCHER, you must provide a valid ethereum address. When both email and ethereum address can be used and you provide both, the platform by default will send the items to the ethereum address.