# Interface Stripe Documentation

## Overview

Interface Stripe provides a structured API for integrating Stripe payment processing into AntelopeJS applications. The interface wraps the official [Stripe Node.js SDK](https://github.com/stripe/stripe-node) and exposes functions for creating payment intents, completing payments, and reacting to payment status changes.

## Installation

Install the interface as a dependency:

```bash
npm install @antelopejs/interface-stripe
```

## Exports

The interface exposes the following public API:

| Export              | Type       | Description                                                    |
| ------------------- | ---------- | -------------------------------------------------------------- |
| `GetClient`         | Function   | Returns the initialized Stripe client instance.                |
| `InitializePayment` | Function   | Creates a new payment intent and associates a custom payload ID. |
| `WaitForPayment`    | Function   | Waits for a payment intent to reach a terminal state.          |
| `CompletePayment`   | Function   | Completes a payment using a chargeable Stripe source.          |
| `WatchAllPayments`  | Function   | Registers a callback for all payment intent changes.           |
| `WatchPayment`      | Function   | Registers a callback for a specific payment intent's changes.  |
| `IntentChangeContext`| Interface | Context metadata attached to payment intent change events.     |

## Key Concepts

### Payment Intents

Every payment flows through the Stripe `PaymentIntent` object. The `InitializePayment` function creates a payment intent and stores a custom identifier in its `metadata.payload` field. This identifier links the Stripe payment intent back to your application-level entity (such as an order ID).

### Event Monitoring

Payment intent status changes propagate through an internal event system. The `IntentChangeContext` interface carries a `local` flag that indicates whether the event originated from the current instance or from another node in a clustered deployment. This distinction allows you to avoid duplicate processing across instances.

### Terminal States

A payment intent reaches a terminal state when its status becomes either `succeeded` or `canceled`. The `WaitForPayment` function resolves on success and rejects on cancellation. Watcher callbacks registered with `WatchPayment` are automatically cleaned up once the intent reaches a terminal state.

## Documentation Sections

- [Payment Processing](./2.payment-processing.md) - Create, complete, and await payment intents.
- [Event Monitoring](./3.event-monitoring.md) - Watch payment intent changes and react to status updates.