E-Commerce Crypto Checkout

Accept crypto at checkout with the embedded SDK and order webhooks.

Open the interactive version or read this guide as markdown.

Tags: Checkout SDK, Webhooks, Node.js

Paste this prompt into Claude, ChatGPT, or any AI tool. It works best with the CoinCircuit MCP server connected: https://mcp.coincircuit.io

You are helping me integrate CoinCircuit crypto payments into my existing e-commerce website. I have the CoinCircuit MCP server connected.

If you have access to the CoinCircuit MCP server, call these tools for the most accurate and detailed schema outputs:

Use the live MCP data as your source of truth. The details below are a guide, but if the MCP returns something different, trust the MCP.

API Basics

Project Context

I have an e-commerce site and I'm adding crypto payments at checkout using CoinCircuit. The flow:

  1. Customer clicks "Pay with Crypto" on my checkout page
  2. My server creates a CoinCircuit payment session via POST /api/v1/payments
  3. The embedded checkout modal opens on the frontend using the session reference
  4. Customer pays, my server gets a webhook, and the order is fulfilled

What I Need You to Implement

1. Server-side: Create a payment session

Endpoint: POST /api/v1/payments (Call get_endpoint with method post, path /api/v1/payments, section example in the CoinCircuit MCP for a ready-to-use sample request.)

Required fields:

Optional fields:

Example request body:

{
  "title": "Order #1234",
  "description": "2x Widget Pro",
  "amount": "150.00",
  "currency": "USD",
  "customer": {
    "email": "buyer@example.com",
    "firstName": "Jane",
    "lastName": "Smith"
  },
  "metadata": {
    "orderId": "ORD-1234",
    "items": "2x Widget Pro"
  },
  "successUrl": "https://mystore.com/order/1234/success",
  "cancelUrl": "https://mystore.com/cart"
}

Response (201): Returns a session object. The key fields you need:

(Call get_endpoint with method post, path /api/v1/payments, section success in the CoinCircuit MCP for the full response schema.)

Error responses: 400 (invalid input or unsupported asset/chain combo), 401 (bad API key)

2. Client-side: Embedded checkout

Install the checkout SDK:

npm install @coincircuit/checkout

Use CoinCircuitCheckout to open a modal with the session reference from the server response. Handle these callbacks:

Alternative: Skip the SDK entirely and redirect the customer to data.url from the session response. This is the hosted checkout page and requires zero frontend code.

3. Webhook handler: Order fulfillment

Set up an endpoint to receive CoinCircuit webhooks.

(Call search_api with query payment webhook and type schemas in the CoinCircuit MCP to list all payment and transaction webhook schemas. Then call get_schema on any specific one for full field details.)

Payment events (envelope: { event: string, data: { session: PaymentSession, failureReason?: string } }):

(Call get_schema with name PaymentCompletedWebhookDto in the CoinCircuit MCP for every field in the payment.completed payload.)

Transaction events (envelope: { event: string, data: { session: PaymentSession } }, the session includes a transaction field):

(Call get_schema with name TransactionReceivedWebhookDto or TransactionConfirmedWebhookDto in the CoinCircuit MCP for exact field details.)

Webhook security:

Key webhook fields for reconciliation:

Constraints