Payment Sessions API

POST /api/v1/payment-sessions

Create a new payment session.

Authorization

Authorization: Bearer <MERCHANT_API_TOKEN>

Request Body

request.ts

{
  requestId: string; // Idempotency key
  amount: string;    // e.g., "10.00"
  currency: string;  // "USD"
}

Response

response.ts

{
  paymentSessionId: string;
  paymentSessionToken: string;
}

Example

curl

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

---

GET /api/v1/payment-sessions/:paymentSessionId

Retrieve details of a payment session.

Authorization

Authorization: Bearer <paymentSessionToken>

Response

response.ts

{
  paymentSessionId: string;
  createdAt: string; // ISO 8601
  status: "CREATED" | "PENDING" | "FUNDED" | "CANCELED" | "CAPTURING" | "SUCCEEDED" | "ERROR";
  amount: string;
  currency: string;

  // PENDING or later
  oneTimeWalletAddress?: string;
  userAddress?: string;
  network?: string;         // "ETHEREUM" | "POLYGON" | "SEPOLIA"
  tokenSymbol?: string;     // e.g., "USDC", "USD1"
  userSubmittedTransactionHash?: string;

  // FUNDED or later
  fundingTransactionHash?: string;
  capturableAmount?: string;
  capturedAmount?: string;
  refundedAmount?: string;

  captures: Array<{
    paymentCaptureId: string;
    createdAt: string; // ISO 8601
    finalCapture: boolean;
    captureAmount: string;
    refundAmount: string;
    status: "CAPTURING" | "CAPTURED" | "ERROR";
    transactionHash?: string;
    error?: string;
  }>;
}

Example

curl

curl -X GET https://api.grain.inc/api/v1/payment-sessions/ps_123 \
  -H "Authorization: Bearer <paymentSessionToken>"