From f1370de5eae15e036ee1647922f4d40d96acaf88 Mon Sep 17 00:00:00 2001
From: Spencer Stock <spencerstock@gmail.com>
Date: Tue, 3 Mar 2026 14:34:40 -0700
Subject: [PATCH] Document dataSuffix for Base Pay attribution

Made-with: Cursor
---
 docs/base-account/guides/accept-payments.mdx  | 21 ++++++++++++++++++
 docs/base-account/reference/base-pay/pay.mdx  | 22 +++++++++++++++++++
 .../reference/core/createBaseAccount.mdx      |  4 ++--
 3 files changed, 45 insertions(+), 2 deletions(-)

diff --git a/docs/base-account/guides/accept-payments.mdx b/docs/base-account/guides/accept-payments.mdx
index 2bd176355..852158691 100644
--- a/docs/base-account/guides/accept-payments.mdx
+++ b/docs/base-account/guides/accept-payments.mdx
@@ -313,6 +313,27 @@ See full props and theming options in the [Button Reference](/base-account/refer
 If you intend on using the BasePayButton, please follow the [Brand Guidelines](/base-account/reference/ui-elements/brand-guidelines) to ensure consistency across your application.
 </Warning>
 
+## Attribution (dataSuffix)
+
+Pass a `dataSuffix` to attribute payments to your app via [Builder Codes](/base-chain/builder-codes/builder-codes). The suffix is appended to the transaction calldata and must be a `0x`-prefixed hex string with no fixed length requirement.
+
+```ts Payment with Attribution (dataSuffix)
+import { pay } from '@base-org/account';
+
+// Replace with your app's ERC-8021 data suffix from Builder Codes.
+const DATA_SUFFIX = '0x07626173656170700080218021802180218021802180218021';
+
+const payment = await pay({
+  amount: '10.50',
+  to: '0xRecipient',
+  dataSuffix: DATA_SUFFIX,
+});
+```
+
+<Tip>
+If your suffix is not a valid `0x`-prefixed hex string, `pay()` will throw a validation error before submitting the transaction.
+</Tip>
+
 ## Test on Base Sepolia
 
 1. Get test USDC from the <a href="https://faucet.circle.com" target="_blank">Circle Faucet</a> (select "Base Sepolia").  
diff --git a/docs/base-account/reference/base-pay/pay.mdx b/docs/base-account/reference/base-pay/pay.mdx
index ca49004a8..357c2a977 100644
--- a/docs/base-account/reference/base-pay/pay.mdx
+++ b/docs/base-account/reference/base-pay/pay.mdx
@@ -23,6 +23,10 @@ Ethereum address to send USDC to (must start with 0x).
 **Pattern:** `^0x[0-9a-fA-F]{40}$`
 </ParamField>
 
+<ParamField body="dataSuffix" type="`0x${string}`">
+Optional attribution data suffix to append to the transaction calldata. Must be a `0x`-prefixed hex string (e.g., `"0xabc123"`). Use this to pass [Builder Codes](/base-chain/builder-codes/builder-codes) or other onchain attribution identifiers. No fixed length requirement.
+</ParamField>
+
 <ParamField body="testnet" type="boolean">
 Set to true to use Base Sepolia testnet instead of mainnet. Default: false
 </ParamField>
@@ -98,6 +102,24 @@ try {
 }
 ```
 
+```typescript Payment with Attribution (dataSuffix)
+import { pay } from '@base-org/account';
+
+// Replace with your app's ERC-8021 data suffix from Builder Codes.
+const DATA_SUFFIX = "0x07626173656170700080218021802180218021802180218021";
+
+try {
+  const payment = await pay({
+    amount: "10.50",
+    to: "0x1234567890123456789012345678901234567890",
+    dataSuffix: DATA_SUFFIX,
+  });
+  console.log(`Payment sent! Transaction ID: ${payment.id}`);
+} catch (error) {
+  console.error(`Payment failed: ${error.message}`);
+}
+```
+
 ```typescript Payment with Data Collection
 try {
   const payment = await pay({
diff --git a/docs/base-account/reference/core/createBaseAccount.mdx b/docs/base-account/reference/core/createBaseAccount.mdx
index 1a80c8a9e..23e8f851d 100644
--- a/docs/base-account/reference/core/createBaseAccount.mdx
+++ b/docs/base-account/reference/core/createBaseAccount.mdx
@@ -40,11 +40,11 @@ Attribution configuration for Smart Wallet transactions.
 
 <Expandable title="Attribution properties">
 <ParamField body="auto" type="boolean">
-When true, Smart Wallet will generate a 16 byte hex string from the app's origin.
+When true, Smart Wallet will generate a deterministic hex suffix from the app's origin.
 </ParamField>
 
 <ParamField body="dataSuffix" type="`0x${string}`">
-Custom 16 byte hex string appended to initCode and executeBatch calldata. Cannot be used with `auto: true`.
+Custom `0x`-prefixed hex string appended to initCode and executeBatch calldata. Cannot be used with `auto: true`.
 </ParamField>
 </Expandable>
 </ParamField>