# Save card (new user)

Save a card during the first purchase for a brand new customer. Creates the customer record and saves their payment method in a single flow. Ideal for account creation with payment.

## Use cases

- Account registration with payment
- First-time checkout with card save
- Subscription signup
- Marketplace onboarding

## Steps

### 1. Create payment with new customer — `POST /payments`

Create a payment that establishes a new customer and saves their card.

Key parameters:
• customer.id - Your unique identifier (you generate this)
• customer.email, customer.name, customer.phone - Optional details
• setup_future_usage: "on_session" or "off_session" depending on use case
• amount: The first purchase amount

The customer record is created automatically if the ID doesn't exist. This single API call:
• Creates the customer
• Processes the payment
• Saves the card for future use

Request body:

```json
{
  "amount": 6500,
  "currency": "ZAR",
  "confirm": false,
  "description": "First purchase - new customer",
  "return_url": "https://example.com/flows/save-card-new-user?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_new_user_mrxzdvmp",
    "email": "newuser@example.com",
    "name": "New Customer",
    "phone": "+27123456789"
  }
}
```

### 2. Mount SDK

Initialise the SDK with the client_secret. The checkout displays:

• Card entry form
• "Save card for future" checkbox (checked by default)
• Your configured payment methods

For new users, the SDK shows only the card entry form (no saved cards to display).

### 3. Customer completes first payment

Customer enters card details and completes 3DS if required.

On success:
• Payment is processed
• Customer record created in Orchestration
• Card saved to customer profile
• payment_method_id generated

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

### 4. Verify card saved — `GET /payments/{id}`

Confirm the card was saved by checking the payment response:

• customer_id: Confirms customer exists
• payment_method_id: The saved card identifier
• status: "succeeded" confirms everything worked

Store the customer_id in your system linked to your user account. For future purchases, pass customer_id to show saved cards automatically.

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

- Single flow creates customer + saves card
- Customer ID can be your own identifier
- setup_future_usage determines CIT vs MIT
- No separate customer creation API needed

## Flow diagram

```mermaid
flowchart LR
    A[Create Payment<br/>+ New Customer] --> B[Mount SDK]
    B --> C[Customer Enters Card]
    C --> D{Payment Success?}
    D -->|Yes| E[Customer Created<br/>+ Card Saved]
    E --> F[Store customer_id]
    D -->|No| G[Show Error]
```

## Payment state transitions

```mermaid
stateDiagram-v2
    [*] --> requires_payment_method: Create with customer object
    requires_payment_method --> processing: Submit Card + 3DS
    processing --> succeeded: Payment + Card Save
    processing --> failed: Error
    succeeded --> [*]: customer_id + payment_method_id

    note right of succeeded: Customer created - Card saved for future
```

---

Interactive version: https://playground.peachpayments.com/flows/save-card-new-user