Developer Dashboard

Auctions

Paper supports holding and capturing payments in separate steps, enabling you to support escrow-less auctions! This includes auctions that allow both crypto and fiat bids.

📘

What is an escrow-less auction?

When a customer makes an auction bid, they pre-authorize their payment method to have funds taken but no funds are actually exchanged. When the auction ends, the auction platform captures the payment from the highest bidder and delivers the NFT to them. All other bidders' holds are cancelled.

Paper currently does not support escrowed auctions where funds are sent to the auction contract for each bid.

Prerequisites

  • Your backend keeps track of bids (user wallet, bid amount in crypto).
  • You register your contract with Paper.
  • Your contract has a method that follows the custom contract requirements. It must allow Paper to call a paid method to mint an NFT directly to a buyer's wallet.
  • Your auction must not last longer than 7 days. Many banks don't allow holds longer than this duration.

Integration

Let's walk through an example with an auction priced in ETH.

Accepting a bid

  1. On your auction page, collect the buyer's wallet and bid amount in ETH.
  2. On your backend, create an SDK Client Secret and set capturePaymentLater: true.
  3. Pass the SDK client secret to render the CheckoutWithCard component on your frontend.
    1. The buyer enters their card information.
    2. Upon confirming their bid, a hold for the bid amount + fees in USD equivalent is placed on their card. Their card will not be charged.
  4. Your backend should listen for the payment:hold_created webhook event and store these specific fields from the webhook response:
    1. result.id: The transaction ID of this bid. You'll need this capture or cancel the transaction hold later.
    2. result.valueInCurrency: The bid amount provided.
    3. result.metadata (optional): Any custom metadata provided when creating the Checkout SDK intent on step 2.

Settling the auction

  1. When the auction ends, determine if the winning bidder made their bid with Paper.
  2. If so, capture their transaction hold to complete their purchase.
    1. This step attempts to capture their payment. If the bank declines the payment, the API will return an error. You may decide to contact the bidder or attempt to charge the next highest bidder.
    2. Upon successful payment, Paper will mint and transfer the NFT to the buyer's wallet similar to a standard checkout flow.
  3. (Optional) Cancel other bidders' transaction holds to release the hold on their card. Any holds are automatically released after 7 days.

Tips