Payments SDK Methods

Method catalog

Method	When to use
createFlexIntent	Always, when creating deterministic intent/witness IDs.
sendRouterPayment	Direct push/native or token router calls.
payWithPermit2	Direct onchain Permit2 flow without API relay.
payWithEIP2612	Direct onchain EIP-2612 flow.
payWithEIP3009	Direct onchain EIP-3009 flow with intent-derived nonce.
decodePaymentSettledEvent	Decode registry settlement logs.
createApiClient	API/invoice/relay/session endpoint access.
deriveEip3009Nonce	Build canonical EIP-3009 auth nonce.
hashPaymentIntent	Verify typed data and witness construction.
buildSessionContext	Session-aware router calls.

Minimal usage pattern

What this does: covers create -> execute -> verify in one sequence.

import {
  createFlexIntent,
  sendRouterPayment,
  RpcTransport,
  createApiClient,
} from '@pepay/x402flex';
import { ethers } from 'ethers';

const MERCHANT_ADDRESS = '0x1111111111111111111111111111111111111111';
const ROUTER_ADDRESS = '0xf14f56A54E0540768b7bC9877BDa7a3FB9e66E91';
const TOKEN_ADDRESS = ethers.ZeroAddress;
const REFERENCE_ID = 'order-3001';
const AMOUNT_WEI = ethers.parseEther('0.02');

const provider = new ethers.JsonRpcProvider(process.env.BNB_RPC_URL);
const signer = new ethers.Wallet(process.env.PAYER_PRIVATE_KEY!, provider);

const intentBundle = createFlexIntent({
  merchant: MERCHANT_ADDRESS,
  token: TOKEN_ADDRESS,
  amount: AMOUNT_WEI,
  chainId: 97,
  referenceId: REFERENCE_ID,
  scheme: 'push:evm:direct',
});

await sendRouterPayment({
  transport: new RpcTransport(signer),
  routerAddress: ROUTER_ADDRESS,
  intent: intentBundle.intent,
  witness: intentBundle.witness,
  reference: intentBundle.referenceId,
});

const api = createApiClient({ baseUrl: 'https://api.bnbpay.org' });
const settled = await api.payments.get(intentBundle.paymentId);

Expected result: a verified settlement record keyed by paymentId.

Method selection notes

• Prefer SDK helpers over hand-built ABI calldata for consistency.
• For relay-first products, center on createApiClient().relay.* and payments.buildIntent.
• For contract-first products, center on router helpers + typechain factories.

Common failure modes

• paymentId mismatch: stale nonce/reference hash.
• Session flow reverts: missing/invalid SessionSpendAuth.
• Relay scheme mismatch: payload includes wrong scheme-specific object.