# Save card for returning customers

Save payment methods for returning customers who will be present during future checkouts. This is Customer-Initiated Transaction (CIT) flow - the customer authenticates each payment, providing the highest security. Ideal for e-commerce 'remember my card' features and account wallets.

## Use cases

- E-commerce 'Remember my card' feature
- One-click checkout for returning customers
- Customer payment wallet/account
- Marketplace buyer accounts

## Steps

### 1. First purchase: Create payment — `POST /payments`

Create a payment with customer details and setup_future_usage: "on_session" to save the card during payment.

Key parameters:
• customer.id (required) - Your unique customer identifier
• customer.email, customer.name, customer.phone (optional) - Customer details
• setup_future_usage: "on_session" - Tells the SDK to save card for future CIT payments
• amount: The purchase amount

The customer is created if the ID doesn't exist, or matched to an existing customer.

Request body:

```json
{
  "amount": 6500,
  "currency": "ZAR",
  "confirm": false,
  "description": "Test payment from Interactive Docs",
  "return_url": "https://example.com/flows/simple-purchase?status=complete",
  "is_iframe_redirection_enabled": true,
  "billing": {
    "address": {
      "line1": "123 Main Street",
      "line2": "Apartment 4B",
      "city": "Cape Town",
      "state": "Western Cape",
      "zip": "8001",
      "country": "ZA",
      "first_name": "John",
      "last_name": "Doe"
    },
    "phone": {
      "number": "821234567",
      "country_code": "+27"
    },
    "email": "john.doe@example.com"
  },
  "shipping": {
    "address": {
      "line1": "456 Delivery Road",
      "line2": "Unit 7",
      "city": "Cape Town",
      "state": "Western Cape",
      "zip": "8001",
      "country": "ZA",
      "first_name": "John",
      "last_name": "Doe"
    },
    "phone": {
      "number": "821234567",
      "country_code": "+27"
    },
    "email": "john.doe@example.com"
  },
  "capture_method": "automatic",
  "authentication_type": "three_ds",
  "setup_future_usage": "on_session",
  "customer": {
    "id": "cus_returning_customer",
    "email": "customer@example.com",
    "name": "Test Customer",
    "phone": "+27123456789"
  }
}
```

### 2. First purchase: Mount SDK

Initialise the Orchestration SDK with the client_secret and mount the UnifiedCheckout component.

The SDK displays the payment form where the customer enters their card details. When setup_future_usage is set, the SDK includes a "Save card for future" checkbox (checked by default).

### 3. First purchase: Customer pays

Customer enters card details and completes 3DS authentication.

Upon successful payment:
• The payment is processed
• The card is automatically saved to the customer's profile
• A payment_method_id is generated for the saved card

The customer can now use this saved card for future purchases.

### 4. Returning customer: Create new payment — `POST /payments`

When the customer returns for another purchase, create a NEW payment intent with their customer_id.

Key parameters:
• customer_id: The same customer ID from the first purchase
• amount: The new purchase amount

The SDK will automatically detect saved payment methods for this customer and display them in the checkout.

Request body:

```json
{
  "amount": 6500,
  "currency": "ZAR",
  "confirm": false,
  "description": "Test payment from Interactive Docs",
  "return_url": "https://example.com/flows/simple-purchase?status=complete",
  "is_iframe_redirection_enabled": true,
  "billing": {
    "address": {
      "line1": "123 Main Street",
      "line2": "Apartment 4B",
      "city": "Cape Town",
      "state": "Western Cape",
      "zip": "8001",
      "country": "ZA",
      "first_name": "John",
      "last_name": "Doe"
    },
    "phone": {
      "number": "821234567",
      "country_code": "+27"
    },
    "email": "john.doe@example.com"
  },
  "shipping": {
    "address": {
      "line1": "456 Delivery Road",
      "line2": "Unit 7",
      "city": "Cape Town",
      "state": "Western Cape",
      "zip": "8001",
      "country": "ZA",
      "first_name": "John",
      "last_name": "Doe"
    },
    "phone": {
      "number": "821234567",
      "country_code": "+27"
    },
    "email": "john.doe@example.com"
  },
  "capture_method": "automatic",
  "authentication_type": "three_ds"
}
```

### 5. Returning customer: Mount SDK

Mount the SDK for the returning customer. The UnifiedCheckout will automatically:

• Detect the customer_id from the payment intent
• Fetch and display saved payment methods
• Show "•••• 4242" style cards the customer can select
• Allow entering a new card if preferred

No additional API calls needed - the SDK handles listing saved methods automatically.

### 6. Returning customer: Pay with saved card

Customer selects their saved card and completes the payment.

The customer may need to:
• Re-enter CVV (some issuers require this)
• Complete 3DS authentication (risk-based decision by issuer)

This is the key difference from off-session/MIT payments - the customer is present and authenticates each transaction, providing the highest security level.

## Response

Payment endpoints return the payment object. Key fields to read:

- `payment_id` — the payment identifier.
- `status` — current payment status (see the state transitions below).
- `client_secret` — pass to the SDK to complete the payment client-side.
- `next_action` — present when a redirect or 3-D Secure challenge is required.

## Key parameters

- setup_future_usage: 'on_session' - Customer present for future charges
- SDK automatically shows saved cards when customer_id is set
- Each payment requires customer authentication (CVV/3DS)
- Highest security - customer confirms every transaction

## Flow diagram

```mermaid
flowchart LR
    subgraph Initial["First Purchase"]
    A[Create Payment + Customer] --> B[Mount SDK]
    B --> C[Customer Pays]
    C --> D[Card Saved]
    end
    subgraph Future["Returning Customer"]
    D -.-> E[Create New Payment]
    E --> F[Mount SDK]
    F --> G[Shows Saved Cards]
    G --> H[Customer Authenticates]
    H --> I[Payment Complete]
    end
```

## Payment state transitions

```mermaid
stateDiagram-v2
    state "First Purchase" as first {
        [*] --> requires_payment_method
        requires_payment_method --> processing: Submit Card
        processing --> succeeded: Card Saved
    }
    state "Returning Customer" as future {
        [*] --> requires_payment_method: SDK Shows Saved Cards
        requires_payment_method --> requires_customer_action: Select Card
        requires_customer_action --> processing: CVV/3DS
        processing --> succeeded: Complete
    }
    first --> future: Customer Returns

    note right of future: Customer present - Authentication required
```

---

Interactive version: https://playground.peachpayments.com/flows/save-card-on-session