# Recurring via payment method ID

Set up recurring payments using payment_method_id instead of mandates. This simpler approach saves the card and charges it using the payment method reference. Best for scenarios where formal mandate documentation isn't required.

## Use cases

- Simple subscription setups
- Low-risk recurring payments
- Regions without mandate requirements
- Quick integration scenarios

## Steps

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

Create a payment with customer details and setup_future_usage to save the card for recurring charges.

Key parameters:
• customer.id (required) - Your unique customer identifier
• customer.email, customer.name (optional) - Additional details
• amount: Your charge amount
• setup_future_usage: "off_session" - For merchant-initiated charges

This approach is simpler than mandates but offers less dispute protection.
The payment_method_id will be saved and linked to your customer.

Request body:

```json
{
  "amount": 6500,
  "currency": "ZAR",
  "confirm": false,
  "capture_method": "automatic",
  "authentication_type": "three_ds",
  "setup_future_usage": "off_session",
  "description": "Initial payment - saving card for recurring",
  "return_url": "https://example.com/flows/recurring-pm?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"
  },
  "customer": {
    "id": "cus_recurring_pm_user",
    "email": "subscriber@example.com",
    "name": "Recurring PM User",
    "phone": "+27123456789"
  }
}
```

### 2. Customer completes payment

Customer enters card details and completes 3DS authentication.

After success, you'll receive:
• payment_method_id: Use this for all future charges
• customer_id: The customer reference
• status: "succeeded" confirms the card is saved

Important: Save the payment_method_id - you'll need it for every recurring charge.

### 3. Process recurring charge — `POST /payments`

Charge the customer using their saved payment method.

Key parameters:
• amount: The charge amount
• off_session: true - Customer is not present
• confirm: true - Process immediately
• payment_method: The saved payment_method_id
• customer_id: The customer reference
• recurring_details: { type: "payment_method_id", data: "pm_xxx" }

Note: Without mandates, you have less dispute protection.
Ensure clear communication with customers about recurring charges.

Request body:

```json
{
  "amount": 6500,
  "currency": "ZAR",
  "confirm": true,
  "off_session": true,
  "description": "Recurring charge via payment method"
}
```

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

- Uses payment_method_id instead of mandate_id
- No mandate_data required in initial request
- Simpler setup but less dispute protection
- Use recurring_details with type: payment_method_id

## Flow diagram

```mermaid
flowchart LR
    subgraph Setup["Initial Setup (Customer Present)"]
    A[Create Payment + Customer] --> B[Mount SDK]
    B --> C[Customer Pays + 3DS]
    C --> D[Card Saved]
    end
    subgraph Recurring["Recurring Charges (Customer Not Present)"]
    D --> E[Process Charge with PM ID]
    E --> F{Success?}
    F -->|Yes| G[Payment Complete]
    F -->|No| H[Handle Failure]
    H --> E
    end
    style A fill:#1C6DEA,color:#fff
    style D fill:#22c55e,color:#fff
    style G fill:#22c55e,color:#fff
    style H fill:#C91C00,color:#fff
```

## Payment state transitions

```mermaid
stateDiagram-v2
    direction LR
    state "Initial Setup" as setup {
        [*] --> requires_payment_method: Payment Created
        requires_payment_method --> requires_customer_action: SDK Mounted
        requires_customer_action --> processing: Customer Pays
        processing --> succeeded: Card Saved
    }
    state "Recurring Charges" as recurring {
        [*] --> processing: Charge Created
        processing --> succeeded: Charged
        processing --> failed: Declined
        failed --> processing: Retry
    }
    setup --> recurring: payment_method_id saved

    note right of setup: Customer present - One-time authentication
    note right of recurring: Customer not present - Uses payment_method_id
```

---

Interactive version: https://playground.peachpayments.com/flows/recurring-pm