@waffo/waffo-node 2.5.1 → 2.7.0

package/README.md

@@ -1,6 +1,6 @@
 # Waffo Node.js SDK
 
-<!-- Synced with waffo-sdk/README.md @ commit c23c86f -->
+<!-- Synced with waffo-sdk/README.md @ commit 0e59bbc -->
 
 **English** | [中文](README_CN.md)
 
@@ -666,18 +666,61 @@ if (response.isSuccess()) {
 
 #### Query Available Payment Methods
 
+The `payMethodDetails` response includes the payment method category, supported currency, order amount limits, and refund policy. `currentStatus` can be absent when real-time availability is temporarily unavailable.
+
 ```typescript
 // merchantId is auto-injected from config if not provided
 const response = await waffo.payMethodConfig().inquiry({});
 
 if (response.isSuccess()) {
   const data = response.getData();
-  for (const detail of data.payMethodDetails) {
-    console.log(`Payment Method: ${detail.payMethodName}, Country: ${detail.country}, Status: ${detail.currentStatus}`);
+  for (const detail of data?.payMethodDetails ?? []) {
+    console.log({
+      name: detail.payMethodName,
+      type: detail.payMethodType,
+      country: detail.country,
+      currency: detail.currency,
+      amountRange: [detail.orderAmountMin, detail.orderAmountMax],
+      refundAllowed: detail.refundAllowed,
+      currentStatus: detail.currentStatus,
+    });
   }
+} else {
+  console.error('Pay method config inquiry failed:', response.getCode(), response.getMessage());
+}
+```
+
+### Wallet Address Inquiry (x402)
+
+Inquire the on-chain stablecoin receiving address for an x402 payment. The response returns the target network, the on-chain token contract, and the Waffo platform wallet address to send funds to. Phase 1 supports `USDC`.
+
+```typescript
+// paymentRequestId: unique idempotency key for this inquiry
+// orderCurrency: settlement currency of the order (Phase 1 supports USDC)
+// merchantInfo is auto-injected from config if not provided
+const response = await waffo.wallet().inquiry({
+  paymentRequestId: 'unique-request-id',
+  orderCurrency: 'USDC',
+});
+
+if (response.isSuccess()) {
+  const data = response.getData();
+  console.log('Network:', data?.network); // CAIP-2 network id, e.g. eip155:8453 (Base mainnet)
+  console.log('Asset:', data?.asset);     // on-chain token contract address
+  console.log('Pay to:', data?.payTo);    // Waffo platform receiving wallet address
+} else {
+  console.error('Wallet inquiry failed:', response.getCode(), response.getMessage());
 }
 ```
 
+#### Wallet Inquiry Response Fields
+
+| Field | Description |
+|-------|-------------|
+| `network` | CAIP-2 network id (Phase 1: `eip155:8453`, Base mainnet) |
+| `asset` | On-chain token contract address for the network + currency |
+| `payTo` | Waffo platform receiving wallet address (send funds here) |
+
 ## Webhook Handling
 
 Waffo pushes payment results, refund results, subscription status changes, and more via webhooks.
@@ -862,6 +905,8 @@ The following examples show the actual payload structure for each notification t
 }
 ```
 
+For x402 stablecoin payments, `PAYMENT_NOTIFICATION.result` also includes `x402Info` with `x402Request`, `paymentSignatureHeader`, and `x402Response`.
+
 #### SUBSCRIPTION_STATUS_NOTIFICATION / SUBSCRIPTION_PERIOD_CHANGED_NOTIFICATION
 
 These two notification types share the same payload structure:
@@ -1294,7 +1339,7 @@ Error codes are classified by first letter:
 | `S0004` | Response Signature Verification Failed | `ApiResponse.error()` | Check Waffo public key config, contact Waffo |
 | `S0005` | Request Serialization Failed | `ApiResponse.error()` | Check request parameter format |
 | `S0006` | SDK Unknown Error | `ApiResponse.error()` | Check logs, contact technical support |
-| `S0007` | Invalid Private Key | `WaffoError` | Check if private key is valid Base64 PKCS8 DER or unencrypted PKCS8 PEM format |
+| `S0007` | Invalid Private Key | `WaffoError` | Check if private key is valid Base64 encoded PKCS8 format |
 
 > **Important**: `S0001` and `E0001` (returned by server) indicate **unknown status**. Do not close order directly! Should call query API or wait for webhook to confirm actual status.