Skip to content

Commit aadbc02

Browse files
rohit-710rohit-710
authored
Merge pull request #21 from WalletConnectFoundation/devin/1760537913-wallet-pay-docs
docs: add wallet implementation guide for wallet_pay standard
2 parents 3914c88 + 334f5fa commit aadbc02

File tree

3 files changed

+279
-0
lines changed

3 files changed

+279
-0
lines changed

‎docs.json‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -271,6 +271,10 @@
271271
"group": "WalletConnect Payments Standard",
272272
"pages": ["payments/overview"]
273273
},
274+
{
275+
"group": "WalletConnect Pay",
276+
"pages": ["payments/wallet-implementation"]
277+
},
274278
{
275279
"group": "Point of Sale (POS) SDK",
276280
"pages": [

‎payments/overview.mdx‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -52,3 +52,14 @@ This means that any wallet or merchant integrating `wallet_pay` is automatically
5252
## Specification Reference
5353

5454
The `wallet_pay` standard is defined in [CAIP-358: Universal Payment Request Method](https://eip.tools/caip/358). It specifies how payment requests are structured and exchanged between merchants and wallets. Lifecycle management and status tracking (e.g., pending, confirmed, failed) are implementation details defined by [WalletConnect’s POS SDK](/payments/point-of-sale).
55+
56+
## Get Started
57+
58+
<CardGroup cols={2}>
59+
<Card title="WalletConnect Pay" icon="credit-card" href="/payments/wallet-implementation">
60+
Get started with WalletConnect Pay.
61+
</Card>
62+
<Card title="WalletConnect POS SDK" icon="cart-shopping" href="/payments/point-of-sale">
63+
Get started with WalletConnect POS SDK.
64+
</Card>
65+
</CardGroup>

‎payments/wallet-implementation.mdx‎

Lines changed: 264 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,264 @@
1+
---
2+
title: "WalletConnect Pay Implementation for Wallets"
3+
metatags:
4+
description: "Learn how to implement WalletConnect Pay in your wallet to process payment requests during session establishment."
5+
sidebarTitle: "Wallet Implementation"
6+
---
7+
8+
This guide shows wallet developers how to implement WalletConnect Pay to process payment requests during WalletConnect session establishment.
9+
10+
<Warning>
11+
This flow is not currently live and will be released soon. More information will be available shortly.
12+
</Warning>
13+
14+
## Overview
15+
16+
WalletConnect Pay allows merchants to request payments during the session connection flow. The payment request is included in the session proposal, and wallets can process the payment and return the transaction result when approving the session.
17+
18+
**WalletConnect Pay is chain-agnostic** and supports any asset on any blockchain network that can be identified using the CAIP-19 standard. This includes EVM chains, Solana, Bitcoin, Cosmos, and any other blockchain ecosystem.
19+
20+
## Integration Flow
21+
22+
1. Merchant calls `provider.connect({ walletPay, ... })` with payment details
23+
2. Wallet receives session proposal containing payment request
24+
3. Wallet shows payment details to user
25+
4. User approves session (optionally with payment)
26+
5. Wallet processes payment and returns result in session approval
27+
28+
## Payment Request Schema
29+
30+
The `walletPay` object is located at `proposal.params.requests.walletPay`:
31+
32+
```typescript
33+
{
34+
version: "1.0.0",
35+
orderId?: string,
36+
acceptedPayments: [{
37+
asset: string, // CAIP-19 format: "eip155:1/erc20:0x..."
38+
amount: string, // Hex-encoded: "0x186a0"
39+
recipient: string // CAIP-10 format: "eip155:1:0x..."
40+
}],
41+
expiry?: number // UNIX timestamp
42+
}
43+
```
44+
45+
### Examples
46+
47+
**EVM (Base network, USDC token):**
48+
```json
49+
{
50+
"version": "1.0.0",
51+
"acceptedPayments": [{
52+
"asset": "eip155:8453/erc20:0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
53+
"amount": "0x186a0",
54+
"recipient": "eip155:8453:0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb"
55+
}],
56+
"expiry": 1735689600
57+
}
58+
```
59+
60+
**Solana (USDC SPL token):**
61+
```json
62+
{
63+
"version": "1.0.0",
64+
"acceptedPayments": [{
65+
"asset": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp/token:EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
66+
"amount": "0xf4240",
67+
"recipient": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp:7S3P4HxJpyyigGzodYwHtCxZyUQe9JiBMHyRWXArAaKv"
68+
}]
69+
}
70+
```
71+
72+
## Implementation
73+
74+
### 1. Detect Payment Requests
75+
76+
Listen for session proposals and check for payment requests:
77+
78+
```typescript
79+
import { SignClientTypes } from '@walletconnect/types'
80+
81+
walletkit.on('session_proposal', async (proposal) => {
82+
const walletPay = proposal?.params?.requests?.walletPay
83+
84+
if (walletPay) {
85+
// Show payment approval UI
86+
await handlePaymentProposal(proposal, walletPay)
87+
} else {
88+
// Regular session approval
89+
await handleSessionProposal(proposal)
90+
}
91+
})
92+
```
93+
94+
<Warning>
95+
Wallets must integrate WalletConnect Wallet SDK to be compatible with WalletConnect and WalletConnect Pay. If your wallet has not yet integrated the WalletConnect Wallet SDK, please refer to the [WalletConnect Wallet SDK](/wallet-sdk/overview) documentation for instructions on how to integrate it.
96+
</Warning>
97+
98+
### 2. Display Payment Options to the User
99+
100+
Parse the `acceptedPayments` array and match available options against the user's token balances. Display payment details for tokens the user can fulfill:
101+
102+
- Token symbol and network (parsed from CAIP-19 asset identifier)
103+
- Amount (converted from hex to human-readable format with correct decimals)
104+
- Recipient address
105+
- Estimated network fees
106+
107+
If multiple payment options are available, prioritize by user's balance and preferences. Allow users to switch between options or approve the session without processing payment.
108+
109+
### 3. Process Payment & Approve Session
110+
111+
```typescript
112+
import { EngineTypes } from '@walletconnect/types'
113+
import { buildApprovedNamespaces } from '@walletconnect/utils'
114+
115+
async function approveWithPayment(proposal, walletPay, shouldProcess) {
116+
const namespaces = buildApprovedNamespaces({
117+
proposal: proposal.params,
118+
supportedNamespaces: YOUR_SUPPORTED_NAMESPACES
119+
})
120+
121+
const responses = []
122+
123+
// Process payment if user approved
124+
if (walletPay && shouldProcess) {
125+
const result = await executePayment(walletPay)
126+
responses.push(result)
127+
}
128+
129+
// Approve session with payment result
130+
await walletkit.approveSession({
131+
id: proposal.id,
132+
namespaces,
133+
proposalRequestsResponses: responses
134+
})
135+
}
136+
```
137+
138+
### 4. Execute Payment
139+
140+
Implement payment execution based on your wallet's architecture. The basic flow:
141+
142+
```typescript
143+
async function executePayment(walletPay: EngineTypes.WalletPayParams) {
144+
const payment = walletPay.acceptedPayments[0]
145+
146+
// Parse payment details
147+
const [chainId, assetType, assetAddress] = parseAsset(payment.asset)
148+
const recipientAddress = payment.recipient.split(':')[2]
149+
150+
// Execute transfer (implementation depends on your wallet)
151+
const txHash = await transferToken(
152+
assetAddress,
153+
recipientAddress,
154+
payment.amount,
155+
chainId
156+
)
157+
158+
// Return result
159+
return {
160+
version: walletPay.version,
161+
orderId: walletPay.orderId,
162+
txid: txHash,
163+
recipient: payment.recipient,
164+
asset: payment.asset,
165+
amount: payment.amount
166+
}
167+
}
168+
```
169+
170+
## Payment Result Schema
171+
172+
Return this structure in `proposalRequestsResponses`:
173+
174+
```typescript
175+
{
176+
version: string, // Echo from request
177+
orderId?: string, // Echo from request
178+
txid: string, // Transaction hash
179+
recipient: string, // CAIP-10 recipient
180+
asset: string, // CAIP-19 asset
181+
amount: string // Hex-encoded amount
182+
}
183+
```
184+
185+
The merchant receives this in `session.walletPayResult[0]`.
186+
187+
## Format Specifications
188+
189+
WalletConnect Pay uses CAIP standards to ensure chain-agnostic compatibility across all blockchain networks.
190+
191+
### CAIP-19 Asset Format
192+
193+
All assets use CAIP-19 identifiers:
194+
195+
```
196+
{chainNamespace}:{chainId}/{assetNamespace}:{assetReference}
197+
```
198+
199+
**Examples across different chains:**
200+
201+
| Chain | Example Asset |
202+
|-------|--------------|
203+
| Ethereum (USDC) | `eip155:1/erc20:0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48` |
204+
| Base (USDC) | `eip155:8453/erc20:0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913` |
205+
| Optimism (USDC) | `eip155:10/erc20:0x7F5c764cBc14f9669B88837ca1490cCa17c31607` |
206+
| Polygon (USDC) | `eip155:137/erc20:0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174` |
207+
| Arbitrum (USDC) | `eip155:42161/erc20:0xFF970A61A04b1cA14834A43f5dE4533eBDDB5CC8` |
208+
| Solana (USDC) | `solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp/token:EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v` |
209+
210+
WalletConnect Pay supports any asset on chains with CAIP-19 specifications, including all EVM chains and Solana.
211+
212+
### CAIP-10 Account Format
213+
214+
All recipients use CAIP-10 account identifiers:
215+
216+
```
217+
{chainNamespace}:{chainId}:{address}
218+
```
219+
220+
**Examples:**
221+
- Ethereum: `eip155:1:0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb`
222+
- Base: `eip155:8453:0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb`
223+
- Solana: `solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp:7S3P4HxJpyyigGzodYwHtCxZyUQe9JiBMHyRWXArAaKv`
224+
225+
### Amount Encoding
226+
227+
Amounts are hex-encoded in the asset's smallest unit (varies by chain):
228+
229+
```typescript
230+
// EVM tokens (e.g., 10 USDC with 6 decimals)
231+
"0x" + (10 * 10**6).toString(16) // "0x989680"
232+
233+
// Solana tokens (e.g., 1 USDC with 6 decimals)
234+
"0x" + (1 * 10**6).toString(16) // "0xf4240"
235+
```
236+
237+
## Error Handling
238+
239+
Handle common scenarios:
240+
241+
- **Expired requests**: Check `walletPay.expiry` against current timestamp
242+
- **Insufficient balance**: Validate before attempting transfer
243+
- **User rejection**: Allow session approval without payment
244+
- **Transaction failures**: Catch errors and optionally reject session
245+
246+
## Testing
247+
248+
Test with the reference implementation:
249+
250+
```bash
251+
git clone https://github.com/reown-com/web-examples.git
252+
cd web-examples
253+
git checkout chore/wallet-pay-dapp
254+
cd advanced/dapps/walletconnect-pay-dapp
255+
npm install && npm run dev
256+
```
257+
258+
## Additional Resources
259+
260+
- [Reference Wallet Implementation](https://github.com/reown-com/web-examples/tree/chore/wallet-pay-dapp/advanced/wallets/react-wallet-v2)
261+
- [Reference DApp](https://github.com/reown-com/web-examples/tree/chore/wallet-pay-dapp/advanced/dapps/walletconnect-pay-dapp)
262+
- [CAIP-19 Specification](https://chainagnostic.org/CAIPs/caip-19)
263+
- [CAIP-10 Specification](https://chainagnostic.org/CAIPs/caip-10)
264+
- [WalletConnect Wallet SDK](/wallet-sdk/overview)

0 commit comments

Comments
 (0)