Payment Processing

GetClient

Returns the initialized Stripe client instance. The returned promise resolves once the Stripe client has been configured by the implementing module.

import { GetClient } from "@antelopejs/interface-stripe";

async function listCharges() {
  const client = await GetClient();
  const charges = await client.charges.list({ limit: 10 });
  return charges;
}

Returns

• Promise<Stripe> -- Resolves to the configured Stripe SDK client.

Tip: Use GetClient when you need direct access to the Stripe SDK for operations not covered by the higher-level interface functions.

InitializePayment

Creates a new Stripe payment intent and stores a custom identifier in its metadata.payload field. This identifier ties the payment intent to an application-level entity such as an order or invoice.

import { InitializePayment } from "@antelopejs/interface-stripe";

async function createOrderPayment(orderId: string) {
  const paymentIntent = await InitializePayment(orderId, {
    amount: 2500, // $25.00 in cents
    currency: "usd",
    payment_method_types: ["card"],
  });

  return {
    clientSecret: paymentIntent.client_secret,
    paymentIntentId: paymentIntent.id,
  };
}

Parameters

Returns

• Promise<Stripe.PaymentIntent> -- The created payment intent.

Note: Any existing metadata you pass in params is preserved. The metadata.payload field is set to the provided id value.

WaitForPayment

Waits for a payment intent to reach a terminal state. The returned promise resolves with the payment intent when its status becomes succeeded, or rejects with the cancellation reason when its status becomes canceled.

If the payment intent has already reached a terminal state at the time of the call, the function returns or throws immediately without registering a watcher.

import { WaitForPayment } from "@antelopejs/interface-stripe";

async function awaitPayment(paymentIntentId: string) {
  try {
    const completedIntent = await WaitForPayment(paymentIntentId);
    console.log("Payment succeeded:", completedIntent.id);
    return completedIntent;
  } catch (reason) {
    console.error("Payment canceled:", reason);
    throw reason;
  }
}

Parameters

Returns

• Promise<Stripe.PaymentIntent> -- Resolves when the intent succeeds.
• Rejects with the cancellation_reason string when the intent is canceled.

Important: Calling WaitForPayment multiple times with the same payment intent ID reuses the same underlying promise. This prevents duplicate watchers and ensures consistent behavior.

CompletePayment

Completes a payment by creating a charge from a chargeable Stripe source. The function retrieves the payment intent to determine the amount and currency, creates the charge with an idempotency key derived from the payload metadata, and stores the resulting charge ID in the payment intent's metadata.

import { CompletePayment } from "@antelopejs/interface-stripe";
import type Stripe from "stripe";

async function finalizePayment(paymentIntentId: string, source: Stripe.Source) {
  try {
    await CompletePayment(paymentIntentId, source);
    console.log("Payment completed successfully");
  } catch (error) {
    console.error("Failed to complete payment:", error);
  }
}

Parameters

Behavior

1. Validates that the source status is chargeable. Throws an error if it is not.
2. Retrieves the payment intent to read its amount and currency.
3. Creates a charge using the source, with an idempotency key set to metadata.payload (or the payment intent ID as a fallback).
4. Updates the payment intent metadata with the created charge ID.

Warning: The source must be in chargeable status before calling this function. Passing a source in any other state throws an error immediately.

Complete Payment Flow

The following example combines InitializePayment and WaitForPayment into a full server-side payment flow.

import { InitializePayment, WaitForPayment } from "@antelopejs/interface-stripe";

async function processOrder(orderId: string, amountInCents: number) {
  // 1. Create the payment intent
  const intent = await InitializePayment(orderId, {
    amount: amountInCents,
    currency: "usd",
    payment_method_types: ["card"],
  });

  // 2. Return the client secret to your frontend for Stripe.js confirmation
  const clientData = {
    clientSecret: intent.client_secret,
    paymentIntentId: intent.id,
  };

  // 3. Await the payment outcome on the server side
  try {
    const completed = await WaitForPayment(intent.id);
    console.log(`Order ${orderId} paid successfully`);
    return completed;
  } catch (reason) {
    console.error(`Order ${orderId} payment canceled:`, reason);
    throw reason;
  }
}

Your client application uses the client_secret with Stripe.js to collect payment details and confirm the payment on the frontend.