> ## Documentation Index
> Fetch the complete documentation index at: https://docs.atlaspay.cc/llms.txt
> Use this file to discover all available pages before exploring further.

# Payment Sessions

A Payment Session represents a customer's payment intent. Create a session server-side, then use the `client_secret` to mount the payment form on your frontend.

## Payment Flow

```
1. Create Session (Server) → 2. Mount Form (Client SDK) → 3. Confirm (Automatic) → 4. Capture (Optional)
```

Card data is collected securely via the SDK and never touches your servers.

## Create a Session

```bash theme={null}
curl -X POST https://api.atlas.co/functions/v1/create-session \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 4990,
    "currency": "USD",
    "merchant_reference": "order_12345",
    "payment_method_types": ["card", "apple_pay"],
    "capture_method": "automatic",
    "customer": {
      "email": "customer@example.com",
      "name": "John Doe"
    },
    "callback_urls": {
      "approved": "https://yoursite.com/success",
      "declined": "https://yoursite.com/declined",
      "cancelled": "https://yoursite.com/cancel"
    }
  }'
```

### Request Parameters

| Parameter              | Type    | Required | Description                                                   |
| ---------------------- | ------- | -------- | ------------------------------------------------------------- |
| `amount`               | integer | Yes      | Amount in smallest currency unit (cents for USD)              |
| `currency`             | string  | Yes      | Three-letter ISO 4217 currency code (USD, EUR, GBP)           |
| `external_id`          | string  | No       | Your order or cart reference (idempotent if reused)           |
| `capture_method`       | string  | No       | "automatic" (default) or "manual" for auth-only               |
| `customer.email`       | string  | No       | Customer email address                                        |
| `customer.name`        | string  | No       | Customer full name                                            |
| `success_url`          | string  | No       | Redirect after successful payment                             |
| `cancel_url`           | string  | No       | Redirect after cancellation                                   |
| `payment_method_types` | array   | No       | Allowed methods: card, apple\_pay, google\_pay, bank\_account |
| `metadata`             | object  | No       | Custom key-value pairs                                        |

### Response

```json theme={null}
{
  "id": "sess_2xK9mN7vQ3pL8wYz",
  "object": "payment_session",
  "status": "requires_payment_method",
  "amount": 4990,
  "currency": "USD",
  "client_secret": "cs_abc123xyz789...",
  "payment_method_types": ["card", "apple_pay"],
  "capture_method": "automatic",
  "created_at": "2024-01-15T10:30:00Z",
  "livemode": false
}
```

## Session Lifecycle States

Sessions progress through a state machine from creation to completion:

| State                     | Description                                                    |
| ------------------------- | -------------------------------------------------------------- |
| `requires_payment_method` | Session created, waiting for customer to enter payment details |
| `requires_action`         | Additional action needed (3DS authentication, redirect)        |
| `processing`              | Payment is being processed                                     |
| `succeeded`               | Payment completed successfully                                 |
| `failed`                  | Payment failed                                                 |
| `canceled`                | Customer abandoned checkout or session expired                 |

## Session Expiration

Sessions expire automatically to prevent stale payment intents. Expired sessions cannot be completed.

| Setting     | Description                                                                       |
| ----------- | --------------------------------------------------------------------------------- |
| **Default** | Sessions expire 24 hours after creation                                           |
| **Custom**  | Set `expires` as seconds from now (e.g., `3600` for 1 hour) or ISO 8601 timestamp |

> **Best Practice**: Set shorter expiration times for high-value transactions. If a session expires before the customer completes payment, create a new session.

## Retrieve a Session

```bash theme={null}
curl https://api.atlas.co/functions/v1/sessions/sess_xxx \
  -H "Authorization: Bearer sk_test_xxx"
```

## Cancel a Session

```bash theme={null}
curl -X POST https://api.atlas.co/functions/v1/sessions/sess_xxx/cancel \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{"cancellation_reason": "requested_by_customer"}'
```

Cancellation reasons: `duplicate`, `fraudulent`, `requested_by_customer`, `abandoned`