Handle Payment Completion

Client-Side: Transaction Hash

When a customer completes the payment modal, executePayment resolves with the funding transaction details. At this point the session status is FUNDED — funds are sitting in the one-time wallet (OTW), ready for you to capture.

const result = await cubePayService.executePayment({
  amount: 50.0,
  currency: "USD",
});

console.log(result.transactionHash);  // "0xabc123..."
console.log(result.session);          // { paymentSessionId, status: "FUNDED", ... }

Result Object

Field	Type	Description
`transactionHash`	`string`	On-chain funding transaction hash
`session`	`object`	Full session details (ID, status, network, token, addresses)
`details`	`object`	Additional session metadata

FUNDED does not mean the payment is complete. You must capture the funds to transfer them from the OTW to your treasury wallet.

Capture the Payment

Once a session is FUNDED, your server calls the capture endpoint to move funds from the one-time wallet to your treasury wallet. Capture supports both full and partial amounts.

Capture Request

// Server-side: capture the full payment
const captureResponse = await fetch(
  `${process.env.CUBEPAY_API_HOST}/api/v1/payment-sessions/${paymentSessionId}/captures`,
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${process.env.CUBEPAY_API_KEY}`,
    },
    body: JSON.stringify({
      requestId: "capture_ord_12345",   // idempotency key
      captureAmount: "50.00",           // amount to capture
      isFinalCapture: true,             // true = capture + refund remaining balance
    }),
  }
);

const capture = await captureResponse.json();
// { captureId: "cap_xyz", captureAmount: "50.00", refundAmount: "0.00", status: "CAPTURING" }

Capture Parameters

Parameter	Type	Required	Description
`requestId`	`string`	Yes	Idempotency key to prevent duplicate captures
`captureAmount`	`string`	Yes	Amount to capture (e.g., `"50.00"`)
`isFinalCapture`	`boolean`	No	Default `false`. When `true`, any remaining balance is refunded to the customer and the session moves to `SUCCEEDED`

Capture Response

{
  "captureId": "cap_xyz789",
  "captureAmount": "50.00",
  "refundAmount": "0.00",
  "status": "CAPTURING"
}

Capture is an async operation. The response returns immediately with status CAPTURING. You receive a webhook when the capture completes.

Partial vs Final Capture

Partial Capture

Capture a portion of the funded amount. The session returns to FUNDED and remains open for additional captures.

{
  "captureAmount": "25.00",
  "isFinalCapture": false
}

Final Capture

Capture the remaining amount (or a specific amount) and close the session. Any uncaptured balance is refunded to the customer.

{
  "captureAmount": "25.00",
  "isFinalCapture": true
}

Check Capture Status

const status = await fetch(
  `${process.env.CUBEPAY_API_HOST}/api/v1/payment-sessions/${paymentSessionId}/captures/${captureId}`,
  {
    headers: { Authorization: `Bearer ${process.env.CUBEPAY_API_KEY}` },
  }
);

Response:

{
  "captureId": "cap_xyz789",
  "status": "CAPTURED",
  "captureAmount": "50.00",
  "refundAmount": "0.00",
  "captureTransferTransactionHash": "0xcapture123...",
  "refundTransferTransactionHash": null
}

Field	Type	Description
`captureId`	`string`	Unique capture identifier
`status`	`string`	`CAPTURING` or `CAPTURED`
`captureAmount`	`string`	Amount captured
`refundAmount`	`string`	Amount refunded to customer (on final capture)
`captureTransferTransactionHash`	`string \| null`	On-chain hash of the capture transfer
`refundTransferTransactionHash`	`string \| null`	On-chain hash of the refund transfer

Fetch Session Details

After funding or capture, retrieve the full session state:

const response = await fetch(
  `${process.env.CUBEPAY_API_HOST}/payment-sessions/${sessionId}`,
  {
    headers: { Authorization: `Bearer ${paymentSessionToken}` },
  }
);

The response includes capturableAmount, capturedAmount, and a captures array tracking all capture operations.

Server-Side: Webhook Confirmation

Never rely solely on client-side results to fulfill orders. Always confirm payments server-side via webhooks.

Register Your Webhook Endpoint

Configure your webhook URL in the Grain Dashboard under Settings > Webhooks.

Handle the Webhook

Grain sends payment status updates as JSON-RPC 2.0 requests:

// app/api/transactions/webhook/route.ts
import { NextResponse } from "next/server";

export async function POST(request: Request) {
  const body = await request.json();
  const { method, params } = body;

  if (method === "cubepay_paymentStatusUpdate") {
    const update = params[0];

    switch (update.status) {
      case "FUNDED":
        // Customer funded the OTW — ready to capture
        await initiateCapture(update.paymentSessionId);
        break;

      case "CAPTURING":
        // Capture in progress
        console.log("Capture in progress:", update.paymentSessionId);
        break;

      case "SUCCEEDED":
        // Final capture complete — funds in your treasury
        await confirmSettlement(update.paymentSessionId);
        break;

      case "CANCELED":
        await handleCancellation(update.paymentSessionId);
        break;

      case "ERROR":
        await handlePaymentError(update.paymentSessionId);
        break;
    }
  }

  // Always return 200 to acknowledge receipt
  return NextResponse.json({ jsonrpc: "2.0", result: "ok" });
}

Webhook Payload

{
  "jsonrpc": "2.0",
  "id": "1770947403693",
  "method": "cubepay_paymentStatusUpdate",
  "params": [
    {
      "merchantId": "your-merchant-id",
      "paymentSessionId": "ps_abc123def456",
      "status": "FUNDED",
      "updatedAt": "2026-03-20T12:05:00Z"
    }
  ]
}

Payment Status Lifecycle

CREATED → PENDING → FUNDED → CAPTURING → SUCCEEDED
   |          |                    |
   ↓          ↓                    ↓
CANCELED   CANCELED         FUNDED (partial capture)

Status	Meaning
`CREATED`	Session created, customer has not connected a wallet yet
`PENDING`	Wallet connected, awaiting funding transaction
`FUNDED`	Funds received at the one-time wallet — ready to capture
`CAPTURING`	Capture in progress (funds being transferred)
`SUCCEEDED`	Final capture complete — funds settled to your treasury
`CANCELED`	Session expired or was cancelled (not funded within 24 hours)
`ERROR`	An error occurred during processing

Always return a 200 status from your webhook handler, even if your internal processing fails. This prevents unnecessary retries. Handle errors asynchronously.

Next Steps

Learn how to Handle Errors & Edge Cases for robust payment flows.

Home

Get Started

Payment SDK

Grain Dashboard

Support & Resources

Handle Payment Completion

Client-Side: Transaction Hash

Result Object

Capture the Payment

Capture Request

Capture Parameters

Capture Response

Partial vs Final Capture

Partial Capture

Final Capture

Check Capture Status

Fetch Session Details

Server-Side: Webhook Confirmation

Register Your Webhook Endpoint

Handle the Webhook

Webhook Payload

Payment Status Lifecycle

Next Steps

​Client-Side: Transaction Hash

​Result Object

​Capture the Payment

​Capture Request

​Capture Parameters

​Capture Response

​Partial vs Final Capture

Partial Capture

Final Capture

​Check Capture Status

​Fetch Session Details

​Server-Side: Webhook Confirmation

​Register Your Webhook Endpoint

​Handle the Webhook

​Webhook Payload

​Payment Status Lifecycle

​Next Steps

Client-Side: Transaction Hash

Result Object

Capture the Payment

Capture Request

Capture Parameters

Capture Response

Partial vs Final Capture

Check Capture Status

Fetch Session Details

Server-Side: Webhook Confirmation

Register Your Webhook Endpoint

Handle the Webhook

Webhook Payload

Payment Status Lifecycle

Next Steps