SDK API Reference

Installation

npm install @pepaylabs/bnbpay ethers
# compatibility
npm install @bnbpay/sdk ethers

Use the SDK helpers to avoid hash drift. They mirror router and Permit2 typed data so wallets and relayers sign identical bytes.

Core exports

Export	Purpose
createFlexIntent	Returns {intent, witness, paymentId, resourceId, schemeId, referenceId} for router submissions.
sendRouterPayment	Push payment helper that picks the right router entry point.
payWithPermit2 / payWithEIP2612 / payWithEIP3009	Pull helpers for each permit scheme.
decodePaymentSettledEvent	Parses registry logs into typed objects.
getFlexSchemeId	Computes scheme IDs (exact:evm:permit2, push:evm:direct, ...).
hashPaymentIntent / hashFlexWitness	Deterministic hashes for typed-data signatures.
deriveEip3009Nonce	Derives intent-bound EIP-3009 nonce for receiveWithAuthorization.
buildFlexResponse	Builds HTTP 402 payloads for x402Flex.
createApiClient	Typed REST client for bnbpay-api.
X402FlexRouter__factory / X402FlexRegistry__factory	TypeChain factories for on-chain contracts.
buildSessionContext / auditSessionReceipts	SessionGuard helpers for tagging + reconciliation.

Example

import {
  createFlexIntent,
  buildPaymentTransaction,
  decodePaymentSettledEvent,
  X402FlexRouter__factory,
} from '@pepaylabs/bnbpay';
import { ethers } from 'ethers';

const intent = createFlexIntent({
  merchant: '0xMerchant',
  token: ethers.ZeroAddress,
  amount: ethers.parseEther('0.5'),
  chainId: 56,
  referenceId: 'POS-14',
  scheme: 'push:evm:direct',
});

const router = X402FlexRouter__factory.connect(ROUTER_ADDRESS, signer);
await router.depositAndSettleNative(
  intent.intent,
  intent.witness,
  '0x',
  intent.referenceId,
  { value: intent.intent.amount }
);

API client example

import { createApiClient } from '@pepaylabs/bnbpay';

const api = createApiClient();
const payments = await api.payments.list({ network: 'bnb', page: 1 });

Notes

• referenceHash must be computed after all tags are applied; the SDK handles this.
• For session flows, pass sessionId into createFlexIntent (or pre-tag via formatSessionReference) so the tagged hash matches the router.
• createFlexIntent generates a per-invoice nonce; persist it with the invoice metadata.
• EIP-3009 signatures must use ReceiveWithAuthorization with to = router.
• EIP-3009 requires an intent-derived authNonce: deriveEip3009Nonce({ intentHash, router, chainId }).
• Session spend auth must include the current epoch from X402FlexSessionStore.getSessionState.
• Subscription helpers are contract-level today; see contracts/subscriptions for ABI usage.