Captures API

POST /api/v1/payment-sessions/:paymentSessionId/captures

Create a capture for the session. This is asynchronous and returns 202 Accepted immediately.

Authorization: Authorization: Bearer <MERCHANT_API_TOKEN> (server to server)

Request Body

{
  requestId: string;      // Idempotency key
  captureAmount: string;  // e.g., "10.00"
  finalCapture?: boolean; // default: true
}

Response (202 Accepted)

{
  paymentCaptureId: string;
  createdAt: string;      // ISO 8601
  captureAmount: string;
  refundAmount: string;
  finalCapture: boolean;
  status: "CAPTURING";
}

Rules

• captureAmount ≤ capturableAmount

• If finalCapture is true, any remainder is refunded to the user

• Only FUNDED sessions can be captured; during capture, the session status is CAPTURING

Example

curl

curl -X POST https://api.example.com/api/v1/payment-sessions/ps_123/captures \
  -H "Authorization: Bearer <MERCHANT_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{ "requestId":"cap-001", "captureAmount":"10.00", "finalCapture":true }'

---

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

Retrieve details of a specific capture.

Response

{
  paymentCaptureId: string;
  createdAt: string; // ISO 8601
  finalCapture: boolean;
  captureAmount: string;
  refundAmount: string; // If applicable
  status: "CAPTURING" | "CAPTURED" | "ERROR";
  transactionHash?: string; // Present when CAPTURED
  error?: string;           // Present when ERROR
}

Example

curl

curl -X GET https://api.grain.inc/api/v1/payment-sessions/ps_123/captures/pc_123