Skip to main content

​
What is the Payment SDK?

The Payment SDK is a drop-in SDK that lets you accept cryptocurrency payments directly in your application. It handles wallet connections, network selection, transaction signing, and payment confirmation — so you can focus on your product. The SDK renders inside a Shadow DOM modal for complete style isolation, supports multiple wallet providers, and works with any JavaScript framework. 
// 1. Create a session on your server
const session = await fetch("/api/payment-sessions", {
  method: "POST",
  body: JSON.stringify({ amount: "50.00", currency: "USD" }),
});

// 2. Open the payment modal on the client
const transactionHash = await sdk.open({
  paymentSessionId: session.paymentSessionId,
  paymentSessionToken: session.paymentSessionToken,
});

​
How It Works

1

Your server creates a payment session

Call the Grain API from your backend with the payment amount and currency. You receive a paymentSessionId and paymentSessionToken.
2

The SDK opens a payment modal

Pass the session credentials to the client-side SDK. It opens a modal where the customer selects a wallet, connects, and approves the transaction.
3

Customer funds a one-time wallet

Each session gets a unique one-time wallet (OTW) address. The customer’s funds are sent to this address. The session status moves to FUNDED.
4

Your server captures the payment

Once funded, your server calls the capture endpoint to transfer funds from the OTW to your treasury wallet. You can capture the full amount or do partial captures.
5

You receive confirmation

The SDK returns the transaction hash on success. Your server receives webhooks as the session moves through FUNDED → CAPTURING → SUCCEEDED.

​
Key Features

  • Drop-in modal — Shadow DOM-based payment UI with full style isolation. No CSS conflicts with your application.
  • Multi-wallet support — WalletConnect, injected wallets (MetaMask, Coinbase Wallet), and more out of the box.
  • Payment methods — Crypto (stablecoins) with additional methods coming soon.
  • One-time wallets — Every payment session gets a unique receiving address for clean reconciliation.
  • Flexible capture — Capture the full amount or do partial captures. Final capture automatically refunds any remaining balance to the customer.
  • Webhook confirmations — Receive server-side status updates via JSON-RPC 2.0 webhooks.
  • Customizable theme — Match the payment modal to your brand with CSS custom properties.

​
Payment Methods

MethodDescriptionSettlement
CryptoCustomer pays with stablecoins (USDC) from any supported walletOn-chain

​
Next Steps

Get up and running in minutes. Follow the Installation & Setup guide to add the SDK to your project, then walk through the Integration Guide to process your first payment.