|
| 1 | +import { |
| 2 | + Callout, |
| 3 | + OpenSourceCard, |
| 4 | + createMetadata, |
| 5 | + InstallTabs, |
| 6 | + SDKCard, |
| 7 | + Grid, |
| 8 | + ArticleIconCard, |
| 9 | + Tabs, |
| 10 | + TabsList, |
| 11 | + TabsTrigger, |
| 12 | + TabsContent, |
| 13 | +} from "@doc"; |
| 14 | +import { |
| 15 | + ReactIcon, |
| 16 | + TypeScriptIcon, |
| 17 | + UnityIcon, |
| 18 | + DotNetIcon, |
| 19 | + UnrealEngineIcon, |
| 20 | +} from "@/icons"; |
| 21 | +import { ExternalLink } from "lucide-react"; |
| 22 | + |
| 23 | +export const metadata = createMetadata({ |
| 24 | + image: { |
| 25 | + title: "Payments", |
| 26 | + icon: "pay", |
| 27 | + }, |
| 28 | + title: "Custom Payment Data", |
| 29 | + description: "Pass custom app data to payments to be included on webhooks, payment history, and more.", |
| 30 | +}); |
| 31 | + |
| 32 | +# Custom Payment Data |
| 33 | + |
| 34 | +Associate user IDs, custom payment IDs, order details, and more with any payment. |
| 35 | + |
| 36 | +<Tabs defaultValue="typescript"> |
| 37 | + <TabsList> |
| 38 | + <TabsTrigger value="typescript" className="flex items-center gap-2 [&>p]:mb-0"> |
| 39 | + <TypeScriptIcon className="w-4 h-4 mr-2" /> |
| 40 | + TypeScript |
| 41 | + </TabsTrigger> |
| 42 | + <TabsTrigger value="react" className="flex items-center gap-2 [&>p]:mb-0"> |
| 43 | + <ReactIcon className="w-4 h-4 mr-2" /> |
| 44 | + React |
| 45 | + </TabsTrigger> |
| 46 | + </TabsList> |
| 47 | + |
| 48 | + <TabsContent value="typescript"> |
| 49 | + To include custom `purchaseData` in webhooks or payment history, pass a `purchaseData` object to any `prepare` function: |
| 50 | + |
| 51 | + ```typescript |
| 52 | + import { Bridge } from "thirdweb"; |
| 53 | + |
| 54 | + const preparedQuote = await Bridge.Buy.prepare({ |
| 55 | + originChainId: 42161, |
| 56 | + originTokenAddress: "0xFd086bC7CD5C481DCC9C85ebE478A1C0b69FCbb9", |
| 57 | + destinationChainId: 10, |
| 58 | + destinationTokenAddress: "0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85", |
| 59 | + amount: 10_000_000n, |
| 60 | + sender: "0x2a4f24F935Eb178e3e7BA9B53A5Ee6d8407C0709", |
| 61 | + receiver: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045", |
| 62 | + client, |
| 63 | + purchaseData: { |
| 64 | + userId: "75750df7-ec39-4724-9995-6c75e7a59ef6", |
| 65 | + itemId: "af4a7350-a89b-4329-8262-0cdf09557803", |
| 66 | + size: "L", |
| 67 | + shippingAddress: { |
| 68 | + addressLine1: "2 Marina Blvd", |
| 69 | + city: "San Francisco", |
| 70 | + state: "CA", |
| 71 | + postalCode: "94123", |
| 72 | + country: "US", |
| 73 | + }, |
| 74 | + }, |
| 75 | + }); |
| 76 | + ``` |
| 77 | + </TabsContent> |
| 78 | + |
| 79 | + <TabsContent value="react"> |
| 80 | + For React applications, you can pass custom `purchaseData` to any of the payment widgets: |
| 81 | + |
| 82 | + ### BuyWidget |
| 83 | + |
| 84 | + ```tsx |
| 85 | + import { BuyWidget } from "thirdweb/react"; |
| 86 | + import { ethereum } from "thirdweb/chains"; |
| 87 | + |
| 88 | + function FundWalletComponent() { |
| 89 | + return ( |
| 90 | + <BuyWidget |
| 91 | + client={client} |
| 92 | + chain={ethereum} |
| 93 | + amount="0.1" |
| 94 | + purchaseData={{ |
| 95 | + userId: "user-123", |
| 96 | + orderId: "order-456", |
| 97 | + productType: "wallet-funding", |
| 98 | + metadata: { |
| 99 | + source: "app", |
| 100 | + campaign: "new-user" |
| 101 | + } |
| 102 | + }} |
| 103 | + /> |
| 104 | + ); |
| 105 | + } |
| 106 | + ``` |
| 107 | + |
| 108 | + ### CheckoutWidget |
| 109 | + |
| 110 | + ```tsx |
| 111 | + import { CheckoutWidget } from "thirdweb/react"; |
| 112 | + import { base } from "thirdweb/chains"; |
| 113 | + |
| 114 | + function CheckoutComponent() { |
| 115 | + return ( |
| 116 | + <CheckoutWidget |
| 117 | + client={client} |
| 118 | + chain={base} |
| 119 | + amount="50" |
| 120 | + seller="0x123...abc" |
| 121 | + name="Digital Product" |
| 122 | + description="Premium subscription" |
| 123 | + purchaseData={{ |
| 124 | + itemId: "premium-plan-yearly", |
| 125 | + customerId: "customer-789", |
| 126 | + size: "enterprise", |
| 127 | + shippingAddress: { |
| 128 | + addressLine1: "123 Business Ave", |
| 129 | + city: "New York", |
| 130 | + state: "NY", |
| 131 | + postalCode: "10001", |
| 132 | + country: "US" |
| 133 | + }, |
| 134 | + specialInstructions: "Corporate billing required" |
| 135 | + }} |
| 136 | + /> |
| 137 | + ); |
| 138 | + } |
| 139 | + ``` |
| 140 | + |
| 141 | + ### TransactionWidget |
| 142 | + |
| 143 | + ```tsx |
| 144 | + import { TransactionWidget, prepareContractCall } from "thirdweb/react"; |
| 145 | + import { ethereum } from "thirdweb/chains"; |
| 146 | + import { getContract } from "thirdweb"; |
| 147 | + |
| 148 | + function MintNFTComponent() { |
| 149 | + const contract = getContract({ |
| 150 | + client, |
| 151 | + chain: ethereum, |
| 152 | + address: "0x...", // Your NFT contract address |
| 153 | + }); |
| 154 | + |
| 155 | + const transaction = prepareContractCall({ |
| 156 | + contract, |
| 157 | + method: "mint", |
| 158 | + params: ["0x123...abc", 1], // recipient, quantity |
| 159 | + }); |
| 160 | + |
| 161 | + return ( |
| 162 | + <TransactionWidget |
| 163 | + client={client} |
| 164 | + transaction={transaction} |
| 165 | + title="Mint NFT" |
| 166 | + description="Mint your exclusive NFT" |
| 167 | + purchaseData={{ |
| 168 | + transactionType: "nft-mint", |
| 169 | + collectionId: "exclusive-collection", |
| 170 | + mintQuantity: 1, |
| 171 | + recipientInfo: { |
| 172 | + userId: "user-456", |
| 173 | + |
| 174 | + tier: "premium" |
| 175 | + } |
| 176 | + }} |
| 177 | + /> |
| 178 | + ); |
| 179 | + } |
| 180 | + ``` |
| 181 | + |
| 182 | + All widgets support the same `purchaseData` format, allowing you to pass any custom metadata that will be included in webhooks and payment history. |
| 183 | + </TabsContent> |
| 184 | +</Tabs> |
| 185 | + |
| 186 | +Any purchase data you provide to a payment will be included on all webhooks, status responses, and payment history for that payment. |
| 187 | + |
| 188 | +## Going further |
| 189 | + |
| 190 | +To connect with other auth strategies, use external wallets, or sponsor gas for users, check out the following guides: |
| 191 | + |
| 192 | +- [Send a Payment](/payments/send) |
| 193 | +- [Webhooks](/payments/webhooks) |
| 194 | + |
| 195 | +## Explore Full API References |
| 196 | + |
| 197 | +- [Buy.prepare](/references/typescript/v5/buy/prepare) |
| 198 | +- [Sell.prepare](/references/typescript/v5/sell/prepare) |
| 199 | +- [BuyWidget](/references/typescript/v5/buywidget) |
| 200 | +- [CheckoutWidget](/references/typescript/v5/checkoutwidget) |
| 201 | +- [TransactionWidget](/references/typescript/v5/transactionwidget) |
| 202 | + |
0 commit comments