# Payment Processing

Interface Stripe provides functions for creating payment intents, waiting for their completion, and finalizing payments with chargeable sources.

## `GetClient`

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

```typescript
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.

```typescript
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

| Parameter | Type                              | Required | Description                                      |
| --------- | --------------------------------- | -------- | ------------------------------------------------ |
| `id`      | `string`                          | Yes      | Custom identifier stored in `metadata.payload`.   |
| `params`  | `Stripe.PaymentIntentCreateParams`| Yes      | Stripe payment intent creation parameters.        |
| `options` | `Stripe.RequestOptions`           | No       | Additional Stripe request options.                |

### 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.

```typescript
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

| Parameter          | Type     | Required | Description                              |
| ------------------ | -------- | -------- | ---------------------------------------- |
| `paymentIntentId`  | `string` | Yes      | The Stripe payment intent ID to monitor. |

### 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.

```typescript
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

| Parameter          | Type            | Required | Description                                     |
| ------------------ | --------------- | -------- | ----------------------------------------------- |
| `paymentIntentId`  | `string`        | Yes      | The Stripe payment intent ID to complete.       |
| `source`           | `Stripe.Source` | Yes      | A source object that must be in `chargeable` status. |

### 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.

```typescript
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](https://stripe.com/docs/js) to collect payment details and confirm the payment on the frontend.