Quickstart Guide

This guide shows the complete journey from creating a payment session to capturing funds.

1

Create a payment session (server)

curl -X POST https://api.grain.inc/api/v1/payment-sessions   -H "Authorization: Bearer <MERCHANT_API_TOKEN>"   -H "Content-Type: application/json"   -d '{
    "requestId": "d3b07384-d1e5-4b3e-9b1f-req-001",
    "amount": "10.00",
    "currency": "USD"
  }'

Response:

{
  "paymentSessionId": "ps_123",
  "paymentSessionToken": "pst_abc"
}

2

Ask user to connect wallet & select stablecoin (client)

Use the JavaScript SDK (recommended) or call the endpoint directly.

SDK (recommended)

const sdk = new SDK({ merchantId: "your-merchant-id" });
const result = await sdk.open({ paymentSessionId: "ps_123" });
console.log("Funding tx:", result.fundingTransactionHash);

Direct endpoint (alternative)

3

User funds the OTW

If you use the SDK, funding and monitoring are handled for you. Optionally associate the funding transaction hash:

curl -X POST https://api.grain.inc/api/v1/payment-sessions/ps_123/funding-transaction   -H "Authorization: Bearer pst_abc"   -H "Content-Type: application/json"   -d '{ "fundingTransactionHash": "0xFUNDHASH" }'

When funded, the session status becomes FUNDED.

4

Capture funds (server)

curl -X POST https://api.grain.inc/api/v1/payment-sessions/ps_123/captures   -H "Authorization: Bearer <MERCHANT_API_TOKEN>"   -H "Content-Type: application/json"   -d '{
    "requestId": "d3b07384-d1e5-4b3e-9b1f-cap-001",
    "captureAmount": "10.00",
    "finalCapture": true
  }'

Response:

{
  "paymentCaptureId": "pc_123",
  "createdAt": "2025-01-01T00:00:00Z",
  "captureAmount": "10.00",
  "refundAmount": "0.00",
  "finalCapture": true,
  "status": "CAPTURING"
}

If finalCapture is true, any remainder is refunded to the user after capture.