Skip to main content

Checkout API

Process complete checkout flows with customer creation, payment, and order management in a single operation using cards and bank accounts.

Wallet Payments

For stablecoin wallet payments, see the Wallet Checkout API documentation.

checkout​

Process a complete checkout with customer and payment using cards or bank accounts.

New Customer​

const result = await easy.checkout({
  customer_creation: true,
  customer_details: {
    first_name: "John",
    last_name: "Doe",
    email: "[email protected]",
    personal_address: {
      line1: "123 Main St",
      city: "Anytown",
      state: "CA",
      postal_code: "12345",
      country: "US",
    },
  },
  source: {
    type: "PAYMENT_CARD",
    tokenId: "tok_abc123",
    name: "Primary Card",
  },
  line_items: [
    { price_id: "price_123", quantity: 2 },
    { price_id: "price_456", quantity: 1 },
  ],
  metadata: {
    order_source: "api",
    campaign: "summer-sale",
  },
});

Existing Customer with New Payment Method​

const result = await easy.checkout({
  customer_creation: false,
  identity_id: "cust_123", // Note: use identity_id, not customer_id
  source: {
    type: "PAYMENT_CARD",
    tokenId: "tok_xyz789",
    name: "New Card",
  },
  line_items: [{ price_id: "price_789", quantity: 1 }],
  metadata: {
    order_source: "api",
  },
});

Existing Customer with Existing Payment Method​

const result = await easy.checkout({
  customer_creation: false,
  identity_id: "cust_123", // Note: use identity_id, not customer_id
  source: "pi_456", // Existing payment instrument ID
  line_items: [{ price_id: "price_789", quantity: 1 }],
});

Checkout with Subscriptions​

You can mix one-time purchases with subscription items:

const result = await easy.checkout({
  customer_creation: false,
  identity_id: "cust_123",
  source: "pi_456",
  line_items: [
    { price_id: "price_onetime_123", quantity: 2 }, // One-time purchase
    { price_id: "price_recurring_456", quantity: 1 }, // Subscription (recurring price)
  ],
  metadata: {
    order_type: "mixed",
    campaign: "bundle-offer",
  },
});
Subscription Pricing

When a line item uses a recurring price (linked to a subscription plan), it automatically creates a subscription for the customer. See the Subscriptions API documentation for more details.

Parameters​

checkout​

  • data (object, required)
    • customer_creation (boolean, required): Whether to create a new customer
    • customer_details (object, required if customer_creation is true): Customer information
      • first_name (string, required)
      • last_name (string, required)
      • email (string, required)
      • phone (string, optional)
      • personal_address (object, optional)
    • identity_id (string, required if customer_creation is false): Existing customer ID
    • source (object | string, required): Payment source
      • If object: New payment instrument details with type, tokenId, and name
      • If string: Existing payment instrument ID
    • line_items (array, required): Array of items to purchase
      • price_id (string, required): Price ID
      • quantity (number, required): Quantity
    • metadata (object, optional): Custom order metadata

Returns​

Promise<
  ApiResponse<{
    transfer?: TransferData;
    orderId?: string;
    subscriptions: (SubscriptionData & {
      order_id: string;
      order_number: string;
    })[];
  }>
>;

Important Notes​

Identity ID vs Customer ID

When checking out with an existing customer, use identity_id (not customer_id). The value is the customer's ID.

Token Security

The tokenId must be obtained from client-side tokenization. Never send raw payment details to your server.

Complete Example​

import { createClient } from "@easylabs/node";
import express from "express";

const app = express();
app.use(express.json());

const easy = await createClient({
  apiKey: process.env.EASY_API_KEY!,
});

app.post("/api/checkout", async (req, res) => {
  try {
    const { customerData, paymentToken, lineItems } = req.body;

    const result = await easy.checkout({
      customer_creation: true,
      customer_details: {
        first_name: customerData.firstName,
        last_name: customerData.lastName,
        email: customerData.email,
        phone: customerData.phone,
        personal_address: customerData.address,
      },
      source: {
        type: "PAYMENT_CARD",
        tokenId: paymentToken,
        name: "Customer Card",
      },
      line_items: lineItems,
      metadata: {
        order_source: "web-checkout",
      },
    });

    res.json({
      success: true,
      orderId: result.data.id,
      orderNumber: result.data.order_number,
    });
  } catch (error) {
    res.status(500).json({
      success: false,
      error: error.message,
    });
  }
});

Type Definitions​

OrderData​

interface OrderData {
  id: string;
  order_number: string;
  customer_id: string;
  total_cents: number;
  currency: string;
  state: string;
  line_items: LineItem[];
  created_at: string;
  updated_at: string;
  metadata?: Record<string, unknown>;
}