Skip to main content

​
Configure for Sandbox

Point the SDK to the sandbox API by setting the host environment variable: 
CUBEPAY_API_HOST=https://api.sandbox.pay.grain.inc
All other environment variables (NEXT_PUBLIC_CUBEPAY_MERCHANT_ID, CUBEPAY_API_KEY) use your sandbox credentials from the Grain Dashboard.

​
Run an End-to-End Test

1

Create a payment session

Use your server to create a session against the sandbox API.
curl -X POST https://api.sandbox.pay.grain.inc/payment-sessions \
  -H "Authorization: Bearer your-sandbox-api-key" \
  -H "Content-Type: application/json" \
  -d '{"amount": "10.00", "currency": "USD"}'
2

Open the payment modal

Launch the SDK on the client with the returned session credentials. In sandbox, the SDK connects to test blockchain networks (Sepolia) automatically.
3

Complete the payment

Connect a wallet funded with testnet tokens and approve the transaction. The SDK handles network switching automatically.
4

Verify in the dashboard

Go to the Grain Dashboard and navigate to Transactions. Confirm your test payment appears with the expected status.

​
Test Webhook Delivery

Sandbox webhooks work identically to production. Configure your webhook URL in the dashboard and use a tunneling tool to receive webhooks locally: 
# Expose your local server
ngrok http 3000
Then update your webhook URL in the Grain Dashboard to point to your ngrok URL: 
https://your-subdomain.ngrok.io/api/transactions/webhook

​
Simulate Payment Statuses

Each webhook delivery contains a status field. In sandbox, payments progress through the full lifecycle:
StatusWhen It Fires
PENDINGSession created
FUNDEDTestnet tokens received at the one-time wallet
SUCCEEDEDSimulated sweep to settlement
CANCELEDPayment cancelled (timeout or user action)
ERRORSimulated error condition
Verify your webhook handler processes each status correctly by monitoring your server logs as you complete test payments.

​
Sandbox vs Production

BehaviorSandboxProduction
Blockchain networkSepolia (testnet)Ethereum, Base (mainnet)
TokensTest USDC (no real value)Real USDC
SettlementSimulatedReal on-chain settlement
WebhooksDelivered to your endpointDelivered to your endpoint
API hostapi.sandbox.pay.grain.incapi.pay.grain.inc
Always test the full payment flow in sandbox before switching to production. Verify that your webhook handler, success screen, and error handling all work as expected.