diff --git a/docs/onboarding/22 NFT Checkouts/0 Overview.mdx b/docs/onboarding/22 NFT Checkouts/0 Overview.mdx new file mode 100644 index 000000000..ed1b47311 --- /dev/null +++ b/docs/onboarding/22 NFT Checkouts/0 Overview.mdx @@ -0,0 +1,78 @@ +--- +slug: /checkouts +title: Overview +--- + +Checkouts delivers the easiest NFT payments experience for you and your buyers. Sell NFTs on any one of our supported EVM chains and allow your users to pay with +any supported payment option. You and your buyers can expect instant payouts and instant NFT processing - all done through your smart contract. + +![Checkouts overview](./assets/checkouts-overview.png) + +### Payment options for buyers + +| Payment Type | Supported Options | +| :----------- | :------------------------------------------ | +| Fiat | Credit & Debit Cards, Apple Pay, Google Pay | +| Crypto | ETH | + +Card and other fiat payments are accepted from all 50 US states and most countries. + +### Supported chains and currencies + +| Blockchain (Mainnet) | Supported Currencies | +| :------------------- | :------------------------------ | +| Arbitrum Nova | ETH | +| Arbitrum One | ETH, USDC.e\* | +| Avalanche | AVAX, USDC.e\* | +| Ethereum | ETH, USDC\* | +| Optimism | ETH, USDC\* | +| Polygon | MATIC, USDC\*, USDC.e\*, WETH\* | +| Zora | ETH | + +### + +| Blockchain (Testnet) | Supported Currencies | +| :------------------- | :------------------- | +| Arbitrum Sepolia | ETH | +| Avalanche Fuji | AVAX | +| Base Goerli | ETH | +| Goerli | ETH, USDC | +| Mumbai | MATIC, USDC | +| Optimism Goerli | ETH | +| Sepolia | ETH | +| Zora Testnet | ETH | + +\* - ERC-20 tokens are available for pro or enterprise customers only. + +### Fraud prevention & chargeback protection + +thirdweb deters bots and fraudulent activity by using multiple data points about the buyer's device, network, behavior, payment, and more. Only high-risk buyers will need to verify their identity with an ID and selfie. + +We protect you from these concerns by offering **full chargeback protection.** + +### Reliable NFT Delivery + +thirdweb manages a fleet of funded crypto wallets to handle blockchain transactions at scale. Queues are automated to monitor for stuck transactions, failed on-chain calls, and low funds. + +### Conversion-optimized UX + +Our checkout flow accounts for many cases to provide buyers a seamless experience with minimal steps: + +- Does the buyer need a crypto wallet or do they already have one? +- Do they exhibit bot-like or suspicious behavior? +- Do they have enough tokens to mint directly from their wallet? +- Is your user trying to purchase more than one NFT? +- Is your user allowlisted to purchase? +- Are there enough NFTs remaining to purchase? + +### Webhooks & custom metadata + +Configure webhooks to notify your backend when payments and transfers are completed. Webhooks allow you to unlock NFT-gated utilities, send customized emails, and more. + +Provide custom metadata to tag purchases with added information. + +### Analytics + +View purchases to your checkouts including breakdowns by payment method and wallet. Export your data with additional details including buyer location, transaction hash, conversion rate, and custom metadata. + +Get visibility into failed transactions to speed up debugging and resolve support questions. diff --git a/docs/onboarding/22 NFT Checkouts/1 Getting Started.mdx b/docs/onboarding/22 NFT Checkouts/1 Getting Started.mdx new file mode 100644 index 000000000..94768c28a --- /dev/null +++ b/docs/onboarding/22 NFT Checkouts/1 Getting Started.mdx @@ -0,0 +1,26 @@ +--- +slug: /checkouts/getting-started +title: Getting Started +--- + +Get an end-to-end NFT checkout experience up and running in a few steps! + +## Prerequisite: Deploy your smart contract + +You can create or deploy a smart contract on thirdweb using [Deploy](https://thirdweb.com/dashboard/contracts/deploy). + +## 1. Enable your contract for Payments + +Visit the Payments dashboard or use the API to enable your contract for Payments. Start with the first step of our integration guide, [Enable Contract for Payments](enable-contract). + +## 2. Create your Checkout Link + +Generate a complete, pre-built checkout experience by [creating a Checkout Link](checkout-link). + +Want a more branded checkout embedded in your app? Visit the guide on [Embedded Checkout Elements](elements) instead. + +## 3. Launch! + +Make sure to review the [Go Live Checklist](go-live-checklist) prior to launch to ensure your setup is launch-ready. + +**Important note: you must provide personal documents (KYC) and business documents (KYB) at least 48 hours prior to launching on mainnet.** diff --git a/docs/onboarding/22 NFT Checkouts/1a Integration/0 Register Contract.mdx b/docs/onboarding/22 NFT Checkouts/1a Integration/0 Register Contract.mdx new file mode 100644 index 000000000..a8b62b691 --- /dev/null +++ b/docs/onboarding/22 NFT Checkouts/1a Integration/0 Register Contract.mdx @@ -0,0 +1,27 @@ +--- +slug: /checkouts/enable-contract +title: 1. Enable Contract for Payments +--- + +Enabling your contract for Payments is required to unlock Checkouts functionality. This can be done on the thirdweb dashboard or with the Payments API. + +## Prerequisites + +Before you start, ensure your contract is set up properly for Checkouts. + +- Using a thirdweb contract? [Ensure your contract is configured properly](thirdweb-contracts). +- Using your own NFT contract? [Ensure your custom contract is compatible](custom-contracts). +- Selling a token listed on a secondary marketplace? [Visit the marketplaces guide](marketplaces). + +## Enable a contract for Payments + +### Dashboard + +1. Navigate into your contract from the [Contracts > Deploy dashboard page](https://thirdweb.com/dashboard/contracts/deploy). +2. Navigate to the "Payments" page from the sidebar. +3. Click the "Enable Payments" button + ![Enable payments for contract](./assets/enable-contract/enable-payments-for-contract.jpg) + +### API + +[See the API Reference for enabling contracts for Payments](https://redocly.github.io/redoc/?url=https://payments.thirdweb.com/api/doc#tag/Contracts/paths/~1api~12022-08-12~1register-contract/post) diff --git a/docs/onboarding/22 NFT Checkouts/1a Integration/1 Shareable Checkout Link.mdx b/docs/onboarding/22 NFT Checkouts/1a Integration/1 Shareable Checkout Link.mdx new file mode 100644 index 000000000..c184cf140 --- /dev/null +++ b/docs/onboarding/22 NFT Checkouts/1a Integration/1 Shareable Checkout Link.mdx @@ -0,0 +1,35 @@ +--- +slug: /checkouts/checkout-link +title: 2. Create a Checkout Link +--- + +Checkout Links are public, reusable URLs that allow buyers to complete a purchase with thirdweb's prebuilt checkout experience. + +## Prerequisites + +Make sure you've [enabled your contract for Payments](enable-contract) first. + +## Use cases + +- Integrate a functional, prebuilt checkout experience quickly. +- Open your NFT's public sale to all buyers. +- Charge your buyers the same price. +- Request your buyer's details (email, wallet address) during checkout. + +## Create a checkout link + +### Dashboard + +1. Navigate into your contract from the [Contracts > Deploy dashboard page](https://thirdweb.com/dashboard/contracts/deploy). +2. Navigate to the "Payments" page from the sidebar. +3. Click the "Create New Checkout" button + ![Create a new checkout link from the dashboard](./assets/checkout-link/create-new-checkout-link.jpg) +4. Customize the look and feel of your checkout experience, and hit "Create" + +### API + +[See the API Reference for creating a checkout link](https://redocly.github.io/redoc/?url=https://payments.thirdweb.com/api/doc#tag/Checkout-Links/paths/~1api~12022-08-12~1shareable-checkout-link/post) + +## Branding + +Creating a Checkout Link is the fastest way to get started with thirdweb Checkouts. If you are looking for complete customization over branding and UX, check out the guide on [Embedded Elements](elements). diff --git a/docs/onboarding/22 NFT Checkouts/1a Integration/4 Go Live Checklist.mdx b/docs/onboarding/22 NFT Checkouts/1a Integration/4 Go Live Checklist.mdx new file mode 100644 index 000000000..558721c99 --- /dev/null +++ b/docs/onboarding/22 NFT Checkouts/1a Integration/4 Go Live Checklist.mdx @@ -0,0 +1,44 @@ +--- +slug: /checkouts/go-live-checklist +title: 3. Go Live Checklist +--- + +Before you go live on mainnet, be sure to review this checklist to ensure your production checkout launch goes smoothly. + +## 3.1 Test your expected flow works on testnet + +Testing on mainnet is costly! Please test your contract and checkout implementation on testnet. + +- For Polygon projects, please test on Mumbai. +- For Ethereum projects, please test on Sepolia. +- Visit the [overview page](/checkouts) to see a list of supported testnets. + +You should be able to test all critical aspects of your smart contract on testnet, including allowlists, signature-based mints, your custom mint method, etc. + +## 3.2 Provide personal and business information + +In order to accept fiat payments (credit cards, debit cards) on mainnet chains, we are required by law to verify your personal (KYC) and business (KYB) information. This information is collected purely for compliance purposes and is not used or shared for any other reason. **You must provide this information at least 48 hours prior to launch.** + +## 3.3 Set up production webhook endpoints + +Testnet and mainnet transactions call a different set of webhook endpoints. Make sure to add your production endpoint(s) in the Webhooks section of the dashboard before going live. + +## 3.4 Ensure your NFT is priced under $2,000 USD + +We currently limit checkouts to be priced under $2,000 USD by default. We may be able to change this at our discretion based on your checkout's risk profile. + +To request a higher price limit, please contact support@thirdweb.com. + +## 3.5 Inform us of high volume launches + +If you are expecting very high sales volume, please reach out in Discord in advance so we can make sure the engineering team is aware and ready to support your launch. + +## 3.6 Change ERC-20 addresses (if applicable) + +Remember that ERC-20 token addresses differ between testnet and mainnet. Make sure to update your contract to point at the mainnet address for the requested token. + +## 3.7 Verify your collection on OpenSea + +If your contract is on an L2 chain like Polygon, OpenSea may hide your collection by default from buyers' profiles. To avoid this, please contact OpenSea to verify your collection before your launch. + +Buyers are still able to complete their purchase regardless of OpenSea verification, but may need to manually unhide their purchased token from their OpenSea profile if it is hidden by default. diff --git a/docs/onboarding/22 NFT Checkouts/1a Integration/_category_.json b/docs/onboarding/22 NFT Checkouts/1a Integration/_category_.json new file mode 100644 index 000000000..ca6faf571 --- /dev/null +++ b/docs/onboarding/22 NFT Checkouts/1a Integration/_category_.json @@ -0,0 +1,5 @@ +{ + "label": "Integration", + "collapsible": true, + "collapsed": false +} diff --git a/docs/onboarding/22 NFT Checkouts/1a Integration/assets/checkout-link/create-new-checkout-link.jpg b/docs/onboarding/22 NFT Checkouts/1a Integration/assets/checkout-link/create-new-checkout-link.jpg new file mode 100644 index 000000000..e8a790726 Binary files /dev/null and b/docs/onboarding/22 NFT Checkouts/1a Integration/assets/checkout-link/create-new-checkout-link.jpg differ diff --git a/docs/onboarding/22 NFT Checkouts/1a Integration/assets/enable-contract/enable-payments-for-contract.jpg b/docs/onboarding/22 NFT Checkouts/1a Integration/assets/enable-contract/enable-payments-for-contract.jpg new file mode 100644 index 000000000..578d3d146 Binary files /dev/null and b/docs/onboarding/22 NFT Checkouts/1a Integration/assets/enable-contract/enable-payments-for-contract.jpg differ diff --git a/docs/onboarding/22 NFT Checkouts/1b Advanced Guides/0 Embedded Elements/0 Overview.mdx b/docs/onboarding/22 NFT Checkouts/1b Advanced Guides/0 Embedded Elements/0 Overview.mdx new file mode 100644 index 000000000..50cd8e168 --- /dev/null +++ b/docs/onboarding/22 NFT Checkouts/1b Advanced Guides/0 Embedded Elements/0 Overview.mdx @@ -0,0 +1,27 @@ +--- +slug: /checkouts/elements +title: Overview +--- + +Checkout Embedded Elements are modular components that can be embedded directly in your app. This allows you to fully customize the look and feel of the checkout experience within your application. + +## Prerequisites + +- Make sure you've [enabled your contract for Payments](enable-contract) +- You have the user's wallet address + - If you do not already a wallet set up for your users, use [Connect](/connect) to create a wallet first. +- Your Content Security Policy is set allowing thirdweb's domain. + - Make sure you enable the [Content Security Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP) directives on your server, please allow the following directives: + - `connect-src https://payments.thirdweb.com;` + - `frame-src https://payments.thirdweb.com;` + - `script-src https://payments.thirdweb.com;` + +## Integration + +### Accepting fiat payment options (credit/debit card, Apple Pay, Google Pay) + +Embed [CheckoutWithCard](/checkouts/checkout-with-card) in your app. + +### Accepting crypto payment options (ETH) + +Embed [CheckoutWithEth](/checkouts/checkout-with-eth) in your app. diff --git a/docs/onboarding/22 NFT Checkouts/1b Advanced Guides/0 Embedded Elements/1 CheckoutWithCard.mdx b/docs/onboarding/22 NFT Checkouts/1b Advanced Guides/0 Embedded Elements/1 CheckoutWithCard.mdx new file mode 100644 index 000000000..3f813e446 --- /dev/null +++ b/docs/onboarding/22 NFT Checkouts/1b Advanced Guides/0 Embedded Elements/1 CheckoutWithCard.mdx @@ -0,0 +1,168 @@ +--- +slug: /checkouts/checkout-with-card +title: CheckoutWithCard +--- + +The **CheckoutWithCard** element embeds a form on your app that accepts credit/debit card, Apple Pay, and Google Pay. + +This component also handles: + +- Apple Pay and Google Pay +- Bot and anti-fraud detection +- 3D Secure (if necessary) +- Buyer KYC (if necessary) + +## Demo + +> 👍 Try a demo! + +![CheckoutWithCard component demo](../../assets/checkout-with-card-demo.png) + +## React Integration + +1. Install the React SDK ([Install guide](/react/getting-started)): + ```Text npm + npm install @thirdweb-dev/react + ``` + ```Text yarn + yarn add @thirdweb-dev/react + ``` +2. On your frontend, render the `CheckoutWithCard` component with your configs. + +### Example code + +```typescript +import { CheckoutWithCard } from "@thirdweb-dev/react"; + + { + console.log("Payment successful:", result); + }} +/>; +``` + +### `CheckoutWithCard` props + +| Name | Type | Description | +| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| clientId **\*** | string | thirdweb client ID (Obtained from an API key which you can generate on the [Dashboard](https://thirdweb.com/dashboard)) | +| configs **\*** | object | A list of configs to create your card checkout element. Fields are the same as the ones found in the [Create Checkout Elements Client Secret](https://docs.withpaper.com/reference/create-checkout-elements-client-secret) API. | +| onPaymentSuccess **\*** | ({ transactionId: string; }) => void | This method is called after the payment has been submitted for processing. This payment may still be rejected by the cardholder's bank. | +| onError | (PaperSDKError) => void | This method is called when an error is encountered. | +| onPriceUpdate | ({ quantity: number; unitPrice: PriceDetail; networkFees: PriceDetail; serviceFees: PriceDetail; total: PriceDetail; }) => void | This method is called when the price is updated or loaded for the first time. This summary is helpful to show a granular price breakdown. Where PriceDetail is { display: string; valueInSubunits: number; currency: string; } | +| locale | enum Valid values: `en`, `fr`, `es`, `it`, `de`, `ja`, `ko`, `zh` | The language to show text in. Defaults to `en`. | +| options | object | Customize component styling. See [Customization](#customization). | + +## Javascript Integration + +1. Install the Javascript SDK with your preferred package manager. + - `npm install @thirdweb-dev/payments` + - `yarn add @thirdweb-dev/payments` +2. Call `createCheckoutWithCardElement` to insert the iframe on your page. Pass the `configs` to this component. + 1. If you don't provide `elementOrId`, this call returns an iframe element for you to insert into your page. + +### Example code + +```typescript +import { createCheckoutWithCardElement } from "@thirdweb-dev/payments"; + +// Assume a container exists: +// +//
+// +createCheckoutWithCardElement({ + clientId: "YOUR_CLIENT_ID", + configs: { + contractId: "YOUR_CONTRACT_ID", + walletAddress: "0x...", + } + elementOrId: "paper-checkout-container", + appName: "My Web3 App", + options, + onError(error) { + console.error("Payment error:", error); + }, + onPaymentSuccess({ id }) { + console.log("Payment successful."); + }, +}); + +// Alternatively, insert the iframe programmatically: +// +// const iframe = createCheckoutWithCardElement(...) +// document.getElementById('paper-checkout-container').appendChild(iframe); + +``` + +### Props + +| Name | Type | Description | +| ---------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| clientId **\*** | string | thirdweb client ID (Obtained from an API key which you can generate on the [Dashboard](https://thirdweb.com/dashboard)) | +| configs **\*** | object | A list of configs to create your card checkout element. Fields are the same as the ones found in the [Create Checkout Elements Client Secret](https://docs.withpaper.com/reference/create-checkout-elements-client-secret) API. | +| elementOrId | string \| HTMLElement | If provided, the iframe will be appended to this element. You can pass in the DOM element or the `id` associated with the element. A minimum width of 380px is recommended. | +| appName | string | If provided, the wallet card will display your `appName`. | +| locale | enum (Valid values: `en`, `fr`, `es`, `it`, `de`, `ja`, `ko`, `zh`) | The language to show text in. Defaults to `en`. | +| options | object | Customize component styling. See [Customization](#customization). | +| onLoad | () => void | This method is called when the iframe loads. | +| onError | (error: PaperSDKError) => void | This method is called when an error occurs during the payment process. | +| onPaymentSuccess | (props: { transactionId: string }) => void | This method is called when the buyer has successfully paid. | +| onReview | (props: { cardholderName: string, id: string }) => void | This method is called after the user enters their card details. | + +## Customization + +The optional `options` argument allows you to customize the component's styling. All customization fields are optional. + +#### `options` object + +| Name | Type | Description | +| -------------------- | ----------------------------------------------------------------------------------- | ----------------------------------------------- | +| colorPrimary | string (In hex, e.g. #cf3781) | The primary brand color for buttons and links. | +| colorBackground | string (In hex, e.g. #cf3781) | The background color of the page. | +| colorText | string (In hex, e.g. #cf3781) | The color for text on the page and UI elements. | +| borderRadius | number (In px, e.g. 0 for sharp corners, 12 for rounded corners, 24 for pill shape) | The roundness of buttons and input elements. | +| inputBorderColor | string (In hex, e.g. #cf3781) | The border color of the input field. | +| inputBackgroundColor | string (In hex, e.g. #cf3781) | The background color of the input field. | + +#### Examples + +Here's an example component with the following props: + +```javascript +{ + colorBackground: '#fefae0', + colorPrimary: '#606c38', + colorText: '#283618', + borderRadius: 6, + inputBackgroundColor: '#faedcd', + inputBorderColor: '#d4a373', +} +``` + +![](../../assets/checkout-with-card-customization-demo.png) + +## Important Notes + +### How do I prevent the 3D Secure or KYC modal from popping up behind my other frontend components? + +The SDK uses a z-index of `10000` for these modals. If they are appearing behind other components, please lower your other components' z-index values. diff --git a/docs/onboarding/22 NFT Checkouts/1b Advanced Guides/0 Embedded Elements/2 CheckoutWithEth.mdx b/docs/onboarding/22 NFT Checkouts/1b Advanced Guides/0 Embedded Elements/2 CheckoutWithEth.mdx new file mode 100644 index 000000000..da8d9f01d --- /dev/null +++ b/docs/onboarding/22 NFT Checkouts/1b Advanced Guides/0 Embedded Elements/2 CheckoutWithEth.mdx @@ -0,0 +1,138 @@ +--- +slug: /checkouts/checkout-with-eth +title: CheckoutWithEth +--- + +**CheckoutWithEth** embeds a component on your page that accepts ETH payments on Ethereum. + +This component also handles: + +- Connecting the payment wallet +- Prompting the payment wallet to switch chain, if necessary +- Informing the payment wallet they have insufficient funds + +## Example + +> 👍 Try a demo! + +The user is prompted to connect their payment wallet. This step is skipped if they've already connected their wallet to your app since this connection is established on your domain. + +![](../../assets/checkout-with-eth-demo.png) + +The user is then prompted to review their purchase, accept the Terms of Service, and complete their payment. + +![](../../assets/checkout-with-eth-demo-2.png) + +## React Integration + +1. Install the React SDK with your preferred package manager. + - `npm install @paperxyz/react-client-sdk-checkout-with-eth` + - `yarn add @paperxyz/react-client-sdk-checkout-with-eth` +2. Copy your API key from the [Developer Dashboard: Developers](https://withpaper.com/dashboard/developers) page. +3. When a buyer wants to make a purchase, create a `configs` object (see props table below). You will provide some buyer information and configure behavior via this API. +4. Instantiate a `PaperSDKProvider` provider to store Paper-specific properties. +5. Within the provider, instantiate the `CheckoutWithEth` component to render this component. Pass the SDK Client Secret to this component. + +### Example code + +```typescript +import { CheckoutWithEth } from "@paperxyz/react-client-sdk-checkout-with-eth"; + + { + console.log("Payment successful."); + }} +/>; +``` + +### `CheckoutWithEth` props + +| Name | Type | Description | +| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| configs **\*** | string | A list of configs to create your eth checkout element. Fields are the same as the ones found in the [Create Checkout Elements Client Secret](ref:create-checkout-elements-client-secret) API. | +| onPaymentSuccess **\*** | `(props : { onChainTxReceipt: TransactionReceipt; transactionId: string; }) => void` | This method is called after the payment has succeeded on-chain. | +| onPriceUpdate | `({ cryptoToFiatConversionRate: number; quantity: number; unitPrice: PriceDetail; networkFees: PriceDetail; serviceFees: PriceDetail; total: PriceDetail; }) => void` | This method is called when the price is updated or loaded for the first time. This summary is helpful to show a granular price breakdown. \* The `valueInSubunits` type here differs from the subunits for CheckoutWithCard (which is a number) | +| locale | enum (Valid values: `en`, `fr`, `es`, `it`, `de`, `ja`, `ko`, `zh`) | The language to show text in. Defaults to `en`. | +| receivingWalletType | enum (Valid values: `WalletConnect`, `MetaMask`, `Coinbase Wallet`, `Phantom`, `Preset`) | Defaults to `Preset`. The wallet type of the user wallet receiving the NFT to render the appropriate wallet icon in the component. | +| suppressErrorToast | boolean | Defaults to `false`. If `false`, there will be a toast (within the iFrame) that pops up informing the user of what went wrong. This can include canceling transactions, pending transactions, etc. | +| showConnectWalletOptions | boolean | Defaults to `true`. If `true`, a connect wallet screen will be displayed allowing users to connect their wallet. | +| payingWalletSigner | [`ethers.Signer`](https://docs.ethers.io/v5/api/signer/) | If provided, the component will request funds from this signer. | +| onWalletConnected | `(props: { userAddress: string, chainId: number }) => void` | This method is called when a payment wallet is connected. | +| onPageChange | `(currentPage: CheckoutWithEthPage) => void` | This method is called when the buyer transitions between pages. | +| onError | `(error: PaperSDKError) => void` | This method is called when an error is encountered. | +| setUpUserPayingWalletSigner | `(args: { chainId: number }) => void` | This method is called before the `payingWalletSigner` is asked to pay with the `chainId` that the `payingWalletSigner` is supposed to be on. | + +## Javascript Integration + +1. Install the Javascript SDK with your preferred package manager. + - `npm install @paperxyz/js-client-sdk` + - `yarn add @paperxyz/js-client-sdk` +2. Copy your API key from the [Developer Dashboard: Developers](https://withpaper.com/dashboard/developers) page. +3. When a buyer wants to make a purchase, create a `configs` object (see props table below). You will provide some buyer information and configure behavior via this API. +4. Call `createCheckoutWithEthElement` to insert the iframe on your page. Pass the SDK Client Secret to this component. + 1. If you don't provide `elementOrId`, this call returns an iframe element for you to insert into your page. + +### Code example + +```javascript +import type { createCheckoutWithEthElement } from "@paperxyz/js-client-sdk-checkout-with-eth"; + +// Assume a container exists: +// +//
+// +const iframe = await createCheckoutWithEthElement({ + configs: { + contractId: 'CONTRACT_ID', + walletAddress: "0x...", + } + elementOrId: "paper-checkout-container", + payingWalletSigner, + setUpUserPayingWalletSigner, + receivingWalletType, + onError(error) { + console.log("Payment error:", error); + }, + onSuccess({ transactionId }) { + console.log("Payment successful."); + }, +}); + +// Alternatively, insert the iframe programmatically: +// +// const iframe = createCheckoutWithEthElement(...) +// document.getElementById('paper-checkout-container').appendChild(iframe); +``` + +### Props + +| Name | Type | Description | +| --------------------------- | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| configs **\*** | string | A list of configs to create your eth checkout element. Fields are the same as the ones found in the [Create Checkout Elements Client Secret](ref:create-checkout-elements-client-secret) API. | +| payingWalletSigner **\*** | [ethers.Signer](https://docs.ethers.io/v5/api/signer/) | The connected wallet who is going to be paying the `ETH` required for the checkout | +| locale | enum (Valid values: `en`, `fr`, `es`, `it`, `de`, `ja`, `ko`, `zh`) | The language to show text in. Defaults to `en`. | +| options | object | Customize component styling. See [Customization](#customzation). | +| setUpUserPayingWalletSigner | `(args: { chainId: number; }) => void \| Promise` | If provided, the callback will be called before asking buyers to pay with the `chainId` that they are expected to be on. Developers must make sure that users are on the right chain (Goerli for testnets, Eth for mainnets) or risk buyers sending funds into the void. | +| receivingWalletType | enum (Valid values: `WalletConnect`, `MetaMask`, `Coinbase Wallet`, `Phantom`, `Preset`) | Defaults to `Preset`. The wallet type of the user wallet receiving the NFT to render the appropriate wallet icon in the component. | +| onError | `(error: PaperSDKError) => void` | This method is called when anything wrong happens during the checkout process. | +| onPaymentSuccess | `(props: { onChainTxReceipt: TransactionReceipt; transactionId: string; }) => void` | This method is called after the payment has succeeded on-chain. | +| suppressErrorToast | boolean | Defaults to `true`. If false, any error thrown will be displayed in a toast. | +| onLoad | `() => void` | This method is called when the iframe loads. | +| elementOrId | `string \| HTMLElement` | If provided, the iframe will be appended this element. You can pass in the DOM element or the `id` associated with the element. A minimum width of 380px is recommended. | + +## Customization + +The optional `options` argument allows you to customize the component's styling. All customization fields are optional. + +#### `options` object + +| Name | Type | Description | +| --------------- | ----------------------------------------------------------------------------------- | ----------------------------------------------- | +| colorPrimary | string (In hex, e.g. #cf3781) | The primary brand color for buttons and links. | +| colorBackground | string (In hex, e.g. #cf3781) | The background color of the page. | +| colorText | string (In hex, e.g. #cf3781) | The color for text on the page and UI elements. | +| borderRadius | number (In px, e.g. 0 for sharp corners, 12 for rounded corners, 24 for pill shape) | The roundness of buttons and input elements. | diff --git a/docs/onboarding/22 NFT Checkouts/1b Advanced Guides/0 Embedded Elements/_category_.json b/docs/onboarding/22 NFT Checkouts/1b Advanced Guides/0 Embedded Elements/_category_.json new file mode 100644 index 000000000..d8d83bfa0 --- /dev/null +++ b/docs/onboarding/22 NFT Checkouts/1b Advanced Guides/0 Embedded Elements/_category_.json @@ -0,0 +1,5 @@ +{ + "label": "Embedded Elements", + "collapsible": true, + "collapsed": true +} diff --git a/docs/onboarding/22 NFT Checkouts/1b Advanced Guides/0 Webhooks.mdx b/docs/onboarding/22 NFT Checkouts/1b Advanced Guides/0 Webhooks.mdx new file mode 100644 index 000000000..b03b8eb40 --- /dev/null +++ b/docs/onboarding/22 NFT Checkouts/1b Advanced Guides/0 Webhooks.mdx @@ -0,0 +1,209 @@ +--- +slug: /checkouts/webhooks +title: Webhooks +--- + +Configure webhook URLs to have thirdweb notify your backend when successful or failed events occur. + +## Use cases + +- Update your database when a buyer purchases an NFT. +- Send an email to a buyer after their purchase succeeds. +- Inform your team in Slack/Discord when a payment or purchase failed. + +## Events + +The following webhook events are supported. + +| Event | Description | +| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `transfer:succeeded` | The NFT has been delivered to the buyer's wallet. | +| `transfer:failed` | The NFT was unable to be delivered after multiple retries. A refund will automatically be processed. | +| `payment:succeeded` | A buyer's payment has been successfully completed. | +| `payment:failed` | A buyer's payment attempt has been rejected. Extra data fields may be available with information from our payment processor on the failure reason. | +| `payment:refunded` | A buyer's payment has been refunded because the mint failed multiple attempts. Extra data fields may be available with the reason for the refund. | +| `payment:hold_created` | This is only emitted if `capturePaymentLater` is set. A buyer's payment method has a pre-authorization hold created for the given amount. They have not been charged yet. You can [capture this hold]() to complete their purchase, or [cancel it](ref:cancel-transaction-hold). | + +## Request format + +thirdweb will call your backend with an HTTPS `POST` request: + +### Headers + +```text +Content-Type: application/json +x-thirdweb-signature: +``` + +### Request body + +```json +{ + "event": "transfer:succeeded", + "result": { + "id": "5bbbada7-e864-4dac-ae4b-0ee4967f55d8", + "checkoutId": "70e08b7f-c528-46af-8b17-76b0e0ade641", + "walletAddress": "0x2086Fcd5b0B8F4aFAc376873E861DE00c67D7B83", + "walletType": "Preset", + "email": "buyer@example.com", + "quantity": 1, + "paymentMethod": "BUY_WITH_CARD", + "networkFeeUsd": 0.02, + "serviceFeeUsd": 1.79, + "totalPriceUsd": 45.99, + "createdAt": "2022-08-22T19:15:09.755375+00:00", + "paymentCompletedAt": "2022-08-22T19:16:01.673+00:00", + "transferCompletedAt": "2022-08-22T19:16:18.024+00:00", + "claimedTokens": { + "collectionAddress": "0x965550329b91b7c703a527347b613E175f38872d", + "collectionTitle": "My First NFT", + "tokens": [ + { + "transferHash": "0x076d1b496152efd2a97d0db1d558c681188a1a76a8a2c271a33e4c34cc1fa467", + "transferExplorerUrl": "https://polygonscan.com/tx/0x076d1b496152efd2a97d0db1d558c681188a1a76a8a2c271a33e4c34cc1fa467", + "tokenId": "262", + "quantity": 1 + } + ] + }, + "title": "My First Checkout", + "transactionHash": "0x076d1b496152efd2a97d0db1d558c681188a1a76a8a2c271a33e4c34cc1fa467", + "valueInCurrency": "0.05", + "currency": "ETH", + "metadata": { + "myAppUserId": "23a9fj2930gya0" + }, + "mintMethod": { ... }, + "eligibilityMethod": { ... }, + "contractArgs": { ... }, + } +} +``` + +```json JSON (Marketplace) +{ + "event": "transfer:succeeded", + "result": { + "id": "5bbbada7-e864-4dac-ae4b-0ee4967f55d8", + "checkoutId": "70e08b7f-c528-46af-8b17-76b0e0ade641", + "walletAddress": "0x2086Fcd5b0B8F4aFAc376873E861DE00c67D7B83", + "walletType": "Preset", + "email": "buyer@example.com", + "quantity": 1, + "paymentMethod": "BUY_WITH_CARD", + "networkFeeUsd": 0.02, + "serviceFeeUsd": 1.79, + "totalPriceUsd": 45.99, + "createdAt": "2022-08-22T19:15:09.755375+00:00", + "paymentCompletedAt": "2022-08-22T19:16:01.673+00:00", + "transferCompletedAt": "2022-08-22T19:16:18.024+00:00", + "claimedTokens": { + "tokens": [ + { + "transferHash": "0x076d1b496152efd2a97d0db1d558c681188a1a76a8a2c271a33e4c34cc1fa467", + "transferExplorerUrl": "https://polygonscan.com/tx/0x076d1b496152efd2a97d0db1d558c681188a1a76a8a2c271a33e4c34cc1fa467", + "tokenId": "262", + "quantity": 1, + "from": "0xce6913CA121276E550b82844A08aCB4dfDc09178", + "collectionAddress": "0x965550329b91b7c703a527347b613E175f38872d", + "collectionTitle": "My First NFT" + } + ] + }, + "title": "My First Checkout", + "transactionHash": "0x076d1b496152efd2a97d0db1d558c681188a1a76a8a2c271a33e4c34cc1fa467", + "valueInCurrency": "0.05", + "currency": "ETH", + "metadata": { + "myAppUserId": "23a9fj2930gya0" + }, + "mintMethod": { ... }, + "eligibilityMethod": { ... }, + "contractArgs": { ... }, + } +} +``` + +## Usage + +### Provide a webhook handler URL + +Webhooks are configured separately for testnet and production checkout on the dashboard. Webhook URLs must be publicly accessible `https` endpoints. + +Do not provide a `localhost` URL to test your local server. We recommend testing your development server with a service like [ngrok](https://ngrok.io/) to serve a temporary public URL. + +**Please return a `2xx` response for unexpected or unused event types to prevent unnecessary retries.** + +### Verify the signature header + +To ensure the request came from thirdweb, each webhook request signs the payload and provides this signature in the `x-thirdweb-signature` header. + +To verify this signature, create a **SHA-256 HMAC hash** with your **thirdweb payments secret key** that can be found in the thirdweb dashboard [payments settings](https://thirdweb.com/dashboard/payments/settings) and the **body payload as the message** (as a JSON-encoded string). + +### Example implementation + +Here's a simplified HTTP handler in Next.js: + +```typescript +import { createHmac, timingSafeEqual } from "crypto"; + +const thirdwebCheckoutsWebhookHandler = (req, res) => { + const apiKey = ""; // Your thirdweb payments secret key + + // Get the provided signature. + const signature = req.headers["x-thirdweb-signature"]; + // Compute the expected signature. + const hash = createHmac("sha256", apiKey) + .update(JSON.stringify(req.body)) // {"event":"transfer:succeeded","result":{"id":... + .digest("hex"); + // Confirm the provided signature matches. + if (!timingSafeEqual(Buffer.from(signature), Buffer.from(hash))) { + return res.status(400).send("Signature mismatch!"); + } + + switch (req.body.event) { + case "transfer:succeeded": + // Handle when an NFT was delivered. + case "transfer:failed": + // Handle when an NFT could not be delivered. + default: + // Ignore all other events and return 2xx. + } + + return res.status(200).send("OK"); +}; +``` + +### Test the webhook response + +Use the **Test webhook** button to send a dummy payload to your webhook URL and see response status/body. + +### View recent webhook events + +Select the **List events** button to view the recent webhook events, including the request body and response status/body from your backend. This view is useful to debug misconfigured webhook handlers. + +## FAQ + +### Why do I need to verify the signature header? + +If your server is public, a bad actor can spoof a webhook request. Verifying the signature ensures the payload has not been changed. If a bad actor changes the webhook request body, the signature would not match the signed payload. + +### Why is my signature header mismatched? + +Here are common reasons the signature header may be mismatched. + +- Check if the header is set lower-cased. Some server frameworks (e.g. Next.js) use lowercase request header names since they are case-insensitive (RFC 2616). +- Make sure you're passing the entire body as the message in the HMAC signature. Some frameworks require you to configure the HTTP handler to not parse the request body (e.g. [Next.js](https://nextjs.org/docs/api-routes/request-helpers)). +- Make sure your API key is valid. + +### What IP address will webhook requests come from? + +Webhooks will be sent from the IP address `44.225.232.73`. + +### How often will webhook requests be retried? + +Webhooks are retried every five minutes for up to one hour until a `2xx` response is returned. + +### Can I filter which webhook events are sent? + +Currently there is no way to filter which events are sent to your webhook URLs. thirdweb may add new webhook event types without notice. Please ignore events that you don't need by returning a `2xx` response. diff --git a/docs/onboarding/22 NFT Checkouts/1b Advanced Guides/1 Translations.mdx b/docs/onboarding/22 NFT Checkouts/1b Advanced Guides/1 Translations.mdx new file mode 100644 index 000000000..aa4ae0e44 --- /dev/null +++ b/docs/onboarding/22 NFT Checkouts/1b Advanced Guides/1 Translations.mdx @@ -0,0 +1,39 @@ +--- +slug: /checkouts/translations +title: Translations +--- + +Checkouts supports the following languages: + +- English +- French +- Italian +- Spanish +- German +- Japanese +- Korean +- Chinese + +By default, text is shown in the buyer's preferred browser language and defaults to English. Non-English languages are **only supported in the Embedded Elements implementation**. + +## Force a specific language + +To always show text in one language, set the `locale` property to the two-letter [ISO 639-1 code](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) when creating the Checkout Element in your frontend code. + +### React example + +```typescript + +``` + +### Javascript SDK example + +```typescript +createCheckoutWithCardElement({ + // ... + locale: "fr", +}); +``` diff --git a/docs/onboarding/22 NFT Checkouts/1b Advanced Guides/2 Marketplaces.mdx b/docs/onboarding/22 NFT Checkouts/1b Advanced Guides/2 Marketplaces.mdx new file mode 100644 index 000000000..a345dc7d2 --- /dev/null +++ b/docs/onboarding/22 NFT Checkouts/1b Advanced Guides/2 Marketplaces.mdx @@ -0,0 +1,65 @@ +--- +slug: /checkouts/marketplaces +title: Marketplaces +--- + +thirdweb supports marketplace contracts where a user can list an NFT and receive funds when a buyer purchases it. + +Integration is identical to a checkout using a `CUSTOM_CONTRACT` contract type. Follow the guide on integrating [custom contracts](custom-contracts), and ensure the `mintMethod` identifies the method on your smart contract that purchases the NFT (a "buy" method). + +Your contract method should do the following: + +- Accepts the wallet address where the NFT should be delivered. +- Accepts payment in the chain's native coin or [USDC / ERC-20 tokens](erc20-pricing) from the caller (`msg.sender`) of the method. +- Transfers the NFT from the seller to the recipient's wallet address. Remember: `msg.sender` is thirdweb's minter wallet and not the buyer's wallet address. Your function needs to ensure the recipient is specified in the argument list. + +## Third-party marketplaces + +Checkouts also supports purchases of tokens listed on third-party Marketplaces such as OpenSea, LooksRare, or X2Y2. + +Purchases on third-party marketplaces are facilitated by the [Reservoir](https://docs.reservoir.tools/docs) contract. You can create a Checkout for an item listed on any [supported Reservoir marketplace](https://docs.reservoir.tools/docs/supported-marketplaces). + +## Integration + +1. Register a new contract + 1. Set your **Contract Type** to **Reservoir**. + 2. Leave **Contract Address** blank. +2. Create a checkout link with the ID of the registered contract. We recommend using one-time checkout links as the underlying token listed on third-party marketplaces may sell out. + +### Code sample + +```typescript +const body = { + contractId: "REGISTERED_CONTRACT_ID", // this contract should be registered with Reservoir as the contract type + title: "My Checkout", + contractArgs: { + // TIP! You can add more than 1 token to the nfts array and we'll accept all of those listings! + nfts: [ + { token: `COLLECTION_CONTRACT_ADDRESS_1:TOKEN_ID_1` }, + { token: `COLLECTION_CONTRACT_ADDRESS_2:TOKEN_ID_2` } + ] + }, +}; + +const resp = await fetch("https://payments.thirdweb.com/api/2022-08-12/checkout-link-intent", { + method: "POST", + headers: [ + "Authorization": "Bearer MY_THIRDWEB_API_SECRET_KEY", + "Content-Type": "application/json", + ] + body: JSON.stringify(body); +}); +const { checkoutLinkIntentUrl } = await resp.body(); + +// Navigate users to this URL to purchase your NFT. + +``` + +Please update the following variables: + +- `REGISTERED_CONTRACT_ID`: The Contract ID from Step 1. +- `COLLECTION_CONTRACT_ADDRESS`: The contract address of the NFT collection. +- `TOKEN_ID`: The token ID of the NFT from the listing. This listing must exist on one of Reservoir's supported marketplaces. +- `MY_THIRDWEB_API_SECRET_KEY` found on your API Keys dashboard page. + +For a more embedded and branded checkout experience, you may also sell marketplace NFTs with [Checkout Elements](checkout-elements). diff --git a/docs/onboarding/22 NFT Checkouts/1b Advanced Guides/3 One Time Checkout Link.mdx b/docs/onboarding/22 NFT Checkouts/1b Advanced Guides/3 One Time Checkout Link.mdx new file mode 100644 index 000000000..1a74daf28 --- /dev/null +++ b/docs/onboarding/22 NFT Checkouts/1b Advanced Guides/3 One Time Checkout Link.mdx @@ -0,0 +1,27 @@ +--- +slug: /checkouts/one-time-checkout-link +title: One-time Checkout Links +--- + +A one-time Checkout Link is a prebuilt checkout experience that is customized per buyer by providing a fixed price, email, wallet address, quantity, and more. + +Each unique link allows at most one purchase and expires after the specified duration. + +## Prerequisites + +Make sure you've [enabled your contract for Payments](enable-contract). + +## Use cases + +- Gate purchases via an off-chain allowlist. After verifying the buyer's identity on your app, navigate them to the checkout link. +- Implement dynamic pricing by passing in the price for each checkout. This feature allows you to provide coupon codes, bulk discounts, and loyalty discounts. +- Restrict the quantity of NFTs your buyers can purchase. +- Directly email the checkout URL directly to the buyer's inbox. + +## Create a one-time checkout link + +One-time checkout links can only be created via API. + +### API + +[See the API Reference for creating a one-time checkout link](https://redocly.github.io/redoc/?url=https://payments.thirdweb.com/api/doc#tag/One-time-Checkout-Links/paths/~1api~12022-08-12~1checkout-link-intent/post) diff --git a/docs/onboarding/22 NFT Checkouts/1b Advanced Guides/4 Custom Contracts.mdx b/docs/onboarding/22 NFT Checkouts/1b Advanced Guides/4 Custom Contracts.mdx new file mode 100644 index 000000000..5c67ed906 --- /dev/null +++ b/docs/onboarding/22 NFT Checkouts/1b Advanced Guides/4 Custom Contracts.mdx @@ -0,0 +1,142 @@ +--- +slug: /checkouts/custom-contracts +title: Custom Contracts +--- + +Using your own Custom Contract on Polygon, Ethereum, or another EVM blockchain? The following example shows you how to use it with thirdweb. + +## Example + +Assume that this is your contract's claim function: + +```javascript +function claimTo( + address _to, + uint256 _quantity, + uint256 _tokenId, + string CUSTOM_ARG_1, // Any additional arguments. + bool CUSTOM_ARG_2 +) + external + payable + mintCompliant(_tokenId, _quantity) + priceCompliant(_tokenId, _quantity) + tokenLive(_tokenId) + { + // YOUR MINTING LOGIC HERE + } +``` + +You will then need a **mintMethod** in order for thirdweb to call your claim function. For the example above, your mintMethod should look like this: + +```json +mintMethod: { + name: "claimTo", // Name of the function to call within the smart contract. + args: { + _to: "$WALLET", + _quantity: "$QUANTITY", + _tokenId: 0, + CUSTOM_ARG_1: "xyz", + CUSTOM_ARG_2: false + }, + payment: { + value: "0.1 * $QUANTITY", // Assuming that your NFT costs 0.1 ETH each. + currency: "ETH" + } +} +``` + +This will ensure that when thirdweb calls the smart contract during any checkout flow, under the hood, we would be calling your smart contract like so: + +```javascript +claimTo("0x...", 1, 0, "xyz", false { + value: ethers.utils.parseEther("0.1"), +}); +``` + +## Requirements + +Your smart contract method that mints the NFT must satisfy these requirements: + +1. The method must accept the buyer's wallet address as an argument. +2. The method must allow thirdweb's minter wallets to mint an unlimited amount as the `msg.sender`. Any restrictions on the minting wallet address or quantity is not allowed. +3. (If priced in USDC) The method must explicitly [request USDC token](/checkouts/erc20-pricing) from the `msg.sender`. + +## MintMethod + +The **mintMethod** is required when creating [Shareable Checkout Links](/checkouts/checkout-link), [One-Time Checkout Links](/checkouts/one-time-checkout-link), or [Checkout Elements](/checkouts/elements). Think of it as an ABI for thirdweb to know how to call your claim function. + +The generic format of the mintMethod is: + +```json +"mintMethod": { + "name": "claimTo", + "args": { + "_to": "$WALLET", + "_quantity": "$QUANTITY" + }, + "payment": { + "value": "0.1 * $QUANTITY", + "currency": "ETH" + } +} +``` + +## Template variables + +> 🚧 Don't know the values? +> +> thirdweb supports two template variables -`$WALLET` and `$QUANTITY` that you may use if you don't know the buyer's wallet address and quantity. Note that for **all other** fields such as `value` and `currency`, you would need to hardcode the actual values. + +Template variables will be replaced when calling your contract: + +| Variable | Replaced with | +| :---------- | :------------------------------ | +| `$WALLET` | The buyer's wallet address. | +| `$QUANTITY` | The quantity of tokens to mint. | + +## Payment + +The `payment` field should provide the **price per NFT in human-readable form** (not wei). + +Example: `"payment": { "value": "0.1 * $QUANTITY", "currency": "ETH" }` + +### Free NFTs + +Set the price to zero. + +Example: `"payment": { value: "0 * $QUANTITY", currency: "MATIC" }` + +### NFTs priced in USDC + +Ensure your mint method **explicitly requests USDC tokens from msg.sender**. See [USDC Pricing](/checkouts/erc20-pricing) for more details. + +### Delegate a different ERC-20 payment address + +> 📘 This is required when interacting with the [Seaport contract](https://docs.opensea.io/reference/seaport-overview). + +By default thirdweb's float wallet approves your NFT contract to request ERC-20 tokens. + +To specify a different contract address that will request ERC-20 tokens from thirdweb's float wallet, set that address in the `"spender"` field: + +```json +"payment": { + "value": "100 * $QUANTITY", + "currency": "USDC", + "spender": "" +} +``` + +## FAQ + +### I have multiple methods with the same name. Why isn't my mintMethod isn't working? + +Please provide the full signature as your mintMethod. thirdweb will not try to "guess" the correct method. + +> **Example** +> +> Your contract has methods `mint(address to)` and `mint(address to, string tokenId)` and your checkout will call the former. +> +> Provide your mintMethod as `mint(address)`. + +You **do not** need to modify your contract. diff --git a/docs/onboarding/22 NFT Checkouts/1b Advanced Guides/5 Thirdweb Contracts.mdx b/docs/onboarding/22 NFT Checkouts/1b Advanced Guides/5 Thirdweb Contracts.mdx new file mode 100644 index 000000000..3727e6a86 --- /dev/null +++ b/docs/onboarding/22 NFT Checkouts/1b Advanced Guides/5 Thirdweb Contracts.mdx @@ -0,0 +1,91 @@ +--- +slug: /checkouts/thirdweb-contracts +title: thirdweb Contracts +--- + +## Integration + +For some thirdweb contracts, set `contractArgs` when creating [Shareable Checkout Links](/checkouts/checkout-link), [One-Time Checkout Links](/checkouts/one-time-checkout-link), or [Checkout Elements](/checkouts/elements). + +### Signature Drop + +This is an ERC-721A contract where the NFT metadata is unique but the claim configuration can be modified for each buyer by creating a _signature_ on your backend. If you don't plan to use signatures, you should consider using the [NFT Drop](https://portal.thirdweb.com/pre-built-contracts/nft-drop) contract. + +To customize the NFT metadata, allow dynamic pricing, or enforce an off-chain allowlist, generate a signature on your backend and set `contractArgs`: + +```typescript +const signatureDrop = thirdwebSdk.getContract('signature-drop'); + +// Generate a signature from a payload that provides some configuration override. +const payload = { + to: buyerWalletAddress, + price: "0.01", + mintStartTime: new Date(0), +}; +const signature = await signatureDrop.signature.generate(payload); + +// Set contractArgs with the payload and signature. +contractArgs = { + payload, + signature, +} +``` + +See guide: [Create an ERC721A NFT Drop with Signature-Based Minting](https://blog.thirdweb.com/guides/signature-drop/) + +### NFT Drop + +This is an ERC-721A contract where the NFT metadata is unique but the claim configuration is identical for all buyers. No `contractArgs` should be set. + +### Edition Drop + +This is an ERC-1155 contract where the NFT metadata and claim configuration is identical for all buyers. Set `contractArgs` with the token ID to mint: + +```typescript +contractArgs = { tokenId: "0" } +``` + +### Marketplace + +This is a contract that allows other users to purchase already-minted NFTs. Set `contractArgs` with an array of the marketplace listing IDs of each of the direct listing: + +```typescript +contractArgs = { + listings: [ + { listingId: "0" }, + { listingId: "1" }, + ... + ] +} +``` + +## Configure the Claim Condition + +Your thirdweb contract must have at least one active claim condition, meaning the **When will this phase start?** date is in the past. + +![Claim Condition Configuration Image](https://files.readme.io/994d683-image.png) + +Helpful tips for each field: + +| Field | Notes | +|-------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **When will this phase start?** | thirdweb can only mint NFTs after this date. | +| **How many NFTs will you drop in this phase?** | Remember to create NFTs on the **NFTs** tab for NFT Drop contracts. | +| **How much do you want to charge to claim each NFT?** | For Mumbai, this price must be ≤ 0.0001 MATIC.
For Goerli, this price must be ≤ 0.0001 ETH.

On production, there is a $2,000 price limit. Please fill out [this Typeform](https://fw3786mcxwl.typeform.com/to/B0xIFoiu) to request an increase. | +| **What currency do you want to use?** | Supported currencies on thirdweb:
- Mumbai: MATIC
- Polygon: MATIC, USDC, WETH
- Goerli: ETH
- Ethereum: ETH, USDC | +| **Who can claim NFTs during this phase?** | If you have an allowlist, please add thirdweb's minter wallets.
Otherwise leave this blank. | +| **How many NFTs can be claimed per transaction?** | This value must be Unlimited. Otherwise thirdweb's minter wallets will not be able to mint more than this amount. | +| **How many seconds do wallets have to wait in-between claiming?** | This value must be 0. Otherwise thirdweb's minter wallets will fail when many mints occur at once. | + +## Debug common blockchain error responses + +| Error Message | Description | Solution | +|-------------------|----------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `!Qty` | The buyer is attempting to purchase more than allowed per wallet. | **:warning: Your Claim Condition must allow thirdweb Wallets to mint an unlimited amount.**

The **How many NFTs can be claimed per transaction?** setting must be set to Unlimited. Alternatively, allow thirdweb's minter wallets to mint the full supply in a snapshot. | +| `!MaxSupply` | The buyer is attempting to purchase more than the available supply, or the drop is sold out. | Allow more NFTs to be sold, or prevent buyers from navigating to the checkout page if sold out. | +| `cant claim yet` | There is no claim phase, or the claim phase has not started. | Wait until the claim phase has started, or set one claim phase's start date to a past date. | +| `!PriceOrCurrency`| thirdweb sent the incorrect amount or currency to the contract. | thirdweb may be auto-detecting the price incorrectly. Please reach out on [Discord](https://discord.gg/thirdweb). | + +_Source: Drop.sol from thirdweb contracts_ + +If your transactions are failing for these reasons, please update the active **Claim Condition** on your thirdweb contract. diff --git a/docs/onboarding/22 NFT Checkouts/1b Advanced Guides/6 ERC20 Pricing.mdx b/docs/onboarding/22 NFT Checkouts/1b Advanced Guides/6 ERC20 Pricing.mdx new file mode 100644 index 000000000..0759a3c54 --- /dev/null +++ b/docs/onboarding/22 NFT Checkouts/1b Advanced Guides/6 ERC20 Pricing.mdx @@ -0,0 +1,51 @@ +--- +slug: /checkouts/erc20-pricing +title: ERC-20 Pricing +--- + +> thirdweb supports selling NFTs that accept the USDC token **for enterprise customers only**. +> +> 👉 Read our guide on [How to Price your NFTs in USDC](https://blog.withpaper.com/how-to-price-your-nfts-in-usdc/). + +## Integration + +### For thirdweb contracts + +1. Navigate to the thirdweb dashboard for your contract +2. Set the claim condition to price the NFT in USDC. + +![In the **Claim Conditions** section](https://files.readme.io/f1bd58f-image.png "In the **Claim Conditions** section") + +### For custom contracts + +1. Add the following snippet to your contract (modify as needed): + + ```solidity + // Replace MY_USDC_ADDRESS with the address based on the blockchain below. + IERC20 public usdc = IERC20("0xe6b8a5CF854791412c1f6EFC7CAf629f5Df1c747"); + uint256 priceInUsdc = 50 * 10 ** 6 + + function mintTo(address recipient, uint256 quantity) public { + usdc.transferFrom(msg.sender, address(this), quantity * priceInUsdc); + } + ``` + +2. Configure your checkout to accept USDC payment: + 1. **Shareable Checkout Links:** When creating the checkout set the **Price per NFT** currency to **USDC**. + 2. **One-Time Checkout Links:** When [creating a One-Time Checkout Link](/checkouts/one-time-checkout-link) set `mintMethod` with `"payment": { "value": "50 * $QUANTITY", currency: "USDC" }`. + +## Accepting the correct USDC token + +Make sure your contract requests the correct USDC token address from thirdweb. These are the supported USDC token addresses. + +- USDC on Mumbai: [0x0fa8781a83e46826621b3bc094ea2a0212e71b23](https://mumbai.polygonscan.com/address/0x0fa8781a83e46826621b3bc094ea2a0212e71b23) +- USDC on Polygon: [0x3c499c542cef5e3811e1192ce70d8cc03d5c3359](https://polygonscan.com/address/0x3c499c542cef5e3811e1192ce70d8cc03d5c3359) +- USDC on Goerli: [0x07865c6E87B9F70255377e024ace6630C1Eaa37F](https://goerli.etherscan.io/address/0x07865c6E87B9F70255377e024ace6630C1Eaa37F) +- USDC on Ethereum: [0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48](https://etherscan.io/address/0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48) +- USDC on Optimism: [0x7f5c764cbc14f9669b88837ca1490cca17c31607](https://optimistic.etherscan.io/address/0x7f5c764cbc14f9669b88837ca1490cca17c31607) + +## FAQ + +### Do you support other ERC-20 tokens? + +thirdweb supports popular ERC-20 (or ERC20) tokens like USDC and WETH. If your NFT is priced in a different token, [contact us](mailto:support@withpaper.com). diff --git a/docs/onboarding/22 NFT Checkouts/1b Advanced Guides/_category_.json b/docs/onboarding/22 NFT Checkouts/1b Advanced Guides/_category_.json new file mode 100644 index 000000000..59d71bdfc --- /dev/null +++ b/docs/onboarding/22 NFT Checkouts/1b Advanced Guides/_category_.json @@ -0,0 +1,5 @@ +{ + "label": "Advanced Guides", + "collapsible": true, + "collapsed": true +} diff --git a/docs/onboarding/22 NFT Checkouts/2 API Reference.mdx b/docs/onboarding/22 NFT Checkouts/2 API Reference.mdx new file mode 100644 index 000000000..ac9bfc4a7 --- /dev/null +++ b/docs/onboarding/22 NFT Checkouts/2 API Reference.mdx @@ -0,0 +1,65 @@ +--- +slug: /checkouts/api-reference +title: API Reference +--- + +The Payments API enables all the functionalities needed to create checkouts. + +:::info + +[View the full API reference.](https://redocly.github.io/redoc/?url=https://payments.thirdweb.com/api/doc) + +::: + +### Usage + +You must use an API Secret Key to make authenticated calls. These calls should be +made from your backend. [Create an API Key from your thirdweb dashboard.](https://thirdweb.com/dashboard/settings/api-keys) + +Provide your secret key as a header: `x-secret-key: your_api_secret_key` + +--- + +## API Categories + +### Enable Contracts for Payments + +Enable, edit, and disable contracts for Payments. + +[View API reference.](https://redocly.github.io/redoc/?url=https://payments.thirdweb.com/api/doc#tag/Contracts) + +### Checkout Links + +Create, edit, and delete Checkout Links. + +[View API reference.](https://redocly.github.io/redoc/?url=https://payments.thirdweb.com/api/doc#tag/Checkout-Links) + +### One-time Checkout Links (Advanced) + +Create One-time Checkout Links. + +[View API reference.](https://redocly.github.io/redoc/?url=https://payments.thirdweb.com/api/doc#tag/One-time-Checkout-Links) + +### Embedded Elements + +Create SDK Client Secret used for Embedded Elements. + +[View API reference.](https://redocly.github.io/redoc/?url=https://payments.thirdweb.com/api/doc#tag/Checkout-Embedded-Elements) + +### Transaction Status + +Get the status of a transaction by transaction ID. + +[View API reference.](https://redocly.github.io/redoc/?url=https://payments.thirdweb.com/api/doc#tag/Transaction-Status) + +### Get Estimated Price + +Get the estimated price of a checkout, including fees and gas. + +[View API reference.](https://redocly.github.io/redoc/?url=https://payments.thirdweb.com/api/doc#tag/Estimated-Price) + +### Transaction Holds + +Capture or cancel a transaction hold. + +[View API reference.]() diff --git a/docs/onboarding/22 NFT Checkouts/3 FAQ.mdx b/docs/onboarding/22 NFT Checkouts/3 FAQ.mdx new file mode 100644 index 000000000..6dce3967d --- /dev/null +++ b/docs/onboarding/22 NFT Checkouts/3 FAQ.mdx @@ -0,0 +1,162 @@ +--- +slug: /checkouts/faq +title: FAQ +--- + +## General + +### How much does thirdweb Checkouts cost? + +There is **no cost to sellers**! Buyers pay a 1% service fee on top of payment processing fees. + +### How long does implementation take? + +A full-featured checkout link **takes minutes to set up**: + +1. [Register your contract](enable-contract). +2. Create a [🔗 Checkout Link](checkout-link). +3. Send the link to your customers. Done ✨! + +When you're ready to customize further, you can tinker with styling, SDKs, webhooks, dynamic pricing, and more. + +### How scalable is thirdweb Checkouts? How much load can it handle? + +Our product is enterprise-ready with a 99.9% uptime. We are battle-tested with enterprises like Balmain, New York Fashion Week, Unilever, deadmau5 and Tilting Point. We can enqueue transactions up to 200 transactions/minute by default, with higher limits upon request. + +### What platforms are supported? + +Checkout links can be used anywhere webpages are supported. + +The Checkout Embedded Elements SDK is supported on Web and Mobile Web. + +## Smart contract support + +### Which blockchains and currencies are supported? + +See the [overview](/checkouts) page for a list of supported chains and currencies. We can support any EVM chain upon request. Please contact support@thirdweb.com if the chain or currency you want to sell in is not on our list. + +### Are marketplace contracts supported? + +Yes! See [Marketplace Sales](marketplaces) for more details. + +### Can I sell an NFT that is already minted? + +Yes! You'll need to "wrap" your NFT with a marketplace contract like [thirdweb marketplace](https://portal.thirdweb.com/pre-built-contracts/marketplace) or build your own. This "direct listing" approach works like this: + +- The seller has an NFT already minted and wants to sell it. +- The seller approves the marketplace contract to take this NFT from their wallet once a buyer offers a specified amount. The NFT is not moved until a sale is completed. +- A buyer agrees to pay the specified amount. They pay via your Checkout flow. +- After the buyer's payment is successful, thirdweb calls the "buy" method with the expected amount in crypto to the marketplace contract. This method transfers the NFT to the buyer's wallet. + +## Payments + +### Where does thirdweb send the funds after a customer has paid? + +thirdweb directly calls the smart contract and pays for the mint using the native currency specified in the contract function. If you are looking for FIAT payout, it is available for the enterprise customers. Please [contact sales](mailto:sales@thirdweb.com) . + +### What regions does thirdweb support credit card payments? + +thirdweb uses multiple payment processors and supports credit card payments in most countries (190+) and all 50 US states. Select countries that the US cannot conduct business with are not supported (Cuba, Iran, North Korea, Syria, and the Crimea, Donetsk, and Luhansk Regions). 10+ currencies and languages are supported. + +### What fiat payment options are accepted? + +thirdweb accepts: credit/debit cards (Visa, Mastercard, American Express, Discover, UnionPay, JCB, Diners Club), Apple Pay, Google Pay, iDEAL + +### What is the price limit for checkouts? + +thirdweb limits checkouts to be priced at $2,000 USD and reserves the right to change this limit based on your checkout's risk profile. For enterprise customers, we can support up to $15,000. + +If you need a higher price limit, please fill out [this form](https://thirdweb.com/contact-us). + +### Do you support gasless transactions? + +Yes, we support the ability for merchants to cover the gas fees related to transactions. See the guide on [Sponsored Fees](sponsored-fees). + +### When does thirdweb require identity verification (KYC)? + +thirdweb combines buyer, merchant, payment method, device, and behavioral signals from multiple vendors to compute the riskiness of a purchase. A small portion of buyers (\< 3% and varies by merchant) will be prompted to submit a photo ID and take a webcam selfie. This step is automated and takes under 1 minute. + +Reminder: thirdweb takes on **all** chargeback liability from the developer! + +## Testing + +### Is there a test credit card? + +Yes, please use the following card numbers. The expiry date, CVV, and postal code do not matter. + +| Card Number | Description | +| :--------------- | :----------------------------------- | +| 4242424242424242 | A "low risk" card. | +| 4000000000009235 | A "high risk" card that prompts KYC. | + +### Where can I get testnet funds? + +Here are some faucets to receive testnet funds: + +| Chain | Currency | Faucet link | +| :----------------- | :------- | :------------------------------------------- | +| Mumbai (Polygon) | MATIC | [Faucet](https://faucet.polygon.technology/) | +| Sepolia (Ethereum) | ETH | [Faucet](https://sepoliafaucet.com/) | +| Goerli (Optimism) | ETH | [Faucet](https://faucet.paradigm.xyz/) | + +## Customization + +### Can I customize the checkout to match my branding? + +Yes, customize colors and UI elements to fit your theme for [Checkout Links](checkout-link). Or embed [Checkout Elements](elements) in your app with granular control of colors. + +### How do allow my users to redeem utility with their NFT? + +NFTs are a great way to gate content! Once the NFT is purchased, you can provide a link to redeem their utility on the post-purchase page and email. + +Listen to [webhooks](webhooks) to update your database or send a custom email when the NFT has been transferred. + +### How do I customize the emails sent to buyers? + +See the [Email Customization](email-customization) guide. + +### Are checkouts translated into different languages? + +Yes, the checkout is localized to the buyer's browser language, or you can force a specific language. See [Translations](translations) for more details. + +### How does checkout support referral codes or discounts? + +You can use our dynamic one-time checkout links to generate payment links with discounts or referral codes for customers. For a full guide to how to implement this, refer [here](one-time-checkout-link). + +### Does Checkouts support allowlists? + +Yep, you can use our dynamic one-time checkout links to generate gated payment links for users who've verified their identity on your website. For a full guide to how to implement this, refer [here](allowlists). + +## Wallets + +### What if my users don't have a wallet? + +Buyers who don't have a wallet can create one with their email or social login. This uses thirdweb's non-custodial [Embedded Wallet](https://portal.thirdweb.com/embedded-wallet) product. + +### How does my user transfer the NFT from the Embedded Wallet? + +Buyers can visit [My Wallets](https://ews.thirdweb.com/wallet) to view and transfer NFTs in their Embedded Wallets. We cover all gas fees related to transferring and offer a way for users to export their private key. + +## Other + +### Does Checkouts support credit card payments for functions outside of minting like burning and editing NFTs? + +This feature is available upon request. Please contact us at [sales@thirdweb.com](mailto:sales@thirdweb.com). + +### What is the customer support level provided to customers? + +For developers, we have a Discord forum for questions that is checked on a daily basis. If you are looking for guaranteed support time and SLA, please contact [sales@thirdweb.com](mailto:sales@thirdweb.com). + +For customers, we respond to inquiries on our support center and to [support@thirdweb.com](mailto:support@thirdweb.com) within 24 business hours. + +### How does thirdweb handle compliance? + +We conduct KYC (know your customer) verification with driver's license and liveliness check on suspicious customers (\<3% on average and varies by merchant). We also handle dark wallet checks to ensure that flagged wallets and stolen funds are not being used in any of our transactions. + +We take on all liabilities & chargeback risks as the Merchant of Record. + +thirdweb is currently in the process of receiving our SOC II certification. + +### What are the authorization rates? + +We have industry leading authorization rates at 92%. We are able to maintain a high authorization by only operating with NFTs, and having a proprietary fraud engine that keeps our fraud rate at \<0.5%. diff --git a/docs/onboarding/22 NFT Checkouts/assets/checkout-with-card-customization-demo.png b/docs/onboarding/22 NFT Checkouts/assets/checkout-with-card-customization-demo.png new file mode 100644 index 000000000..7d626a441 Binary files /dev/null and b/docs/onboarding/22 NFT Checkouts/assets/checkout-with-card-customization-demo.png differ diff --git a/docs/onboarding/22 NFT Checkouts/assets/checkout-with-card-demo.png b/docs/onboarding/22 NFT Checkouts/assets/checkout-with-card-demo.png new file mode 100644 index 000000000..d3305f133 Binary files /dev/null and b/docs/onboarding/22 NFT Checkouts/assets/checkout-with-card-demo.png differ diff --git a/docs/onboarding/22 NFT Checkouts/assets/checkout-with-eth-demo-2.png b/docs/onboarding/22 NFT Checkouts/assets/checkout-with-eth-demo-2.png new file mode 100644 index 000000000..f02f6317a Binary files /dev/null and b/docs/onboarding/22 NFT Checkouts/assets/checkout-with-eth-demo-2.png differ diff --git a/docs/onboarding/22 NFT Checkouts/assets/checkout-with-eth-demo.png b/docs/onboarding/22 NFT Checkouts/assets/checkout-with-eth-demo.png new file mode 100644 index 000000000..4cad57a29 Binary files /dev/null and b/docs/onboarding/22 NFT Checkouts/assets/checkout-with-eth-demo.png differ diff --git a/docs/onboarding/22 NFT Checkouts/assets/checkouts-overview.png b/docs/onboarding/22 NFT Checkouts/assets/checkouts-overview.png new file mode 100644 index 000000000..d047ea0df Binary files /dev/null and b/docs/onboarding/22 NFT Checkouts/assets/checkouts-overview.png differ diff --git a/sidebars/onboarding.js b/sidebars/onboarding.js index dc5b6eefc..950218c82 100644 --- a/sidebars/onboarding.js +++ b/sidebars/onboarding.js @@ -113,6 +113,11 @@ const sidebars = { label: "Wallet SDK", href: "/wallet", }, + { + type: "link", + label: "NFT Checkouts", + href: "/checkouts", + }, { type: "link", label: "Dashboard", @@ -302,6 +307,13 @@ const sidebars = { }, ], + checkouts: [ + { + type: "autogenerated", + dirName: "22 NFT Checkouts", + }, + ], + connect: [ { type: "autogenerated", diff --git a/src/theme/DocSidebarItems/index.js b/src/theme/DocSidebarItems/index.js index 06640ed99..74cda3abd 100644 --- a/src/theme/DocSidebarItems/index.js +++ b/src/theme/DocSidebarItems/index.js @@ -54,6 +54,10 @@ function DocSidebarItems({ items, ...props }) { title: "Infrastructure", items: ["Engine", "Storage", "RPC Edge"], }, + { + title: "Payments", + items: ["NFT Checkouts"], + }, { title: "Tools", items: ["CLI", "Dashboard"],