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

# Saving Payment Methods

> Save API client payment methods for future reuse

## Overview

The Satsuma API allows API clients to save their own payment methods securely. This enables a flow where merchants can charge API clients directly for orders, rather than the end-consumer. This is ideal for scenarios where API clients want to process payment for their customers, and remain the merchant of record.

## Payment Method Flow

The API client payment method saving process involves three main steps:

<Steps>
  <Step title="Create Setup Intent">
    Generate a Stripe-hosted page where API clients can securely add their payment methods
  </Step>

  <Step title="Retrieve Payment Methods">
    List all saved API client payment methods for a specific merchant
  </Step>

  <Step title="Submit Order">
    Use a saved API client payment method to complete an order
  </Step>
</Steps>

## Step 1: Create Setup Intent

Create a setup intent to generate a Stripe-hosted page where your API client organization can securely add payment methods that the merchant can charge for future orders.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST 'https://api.satsuma.ai/payment-method/setup-intent' \
    -H 'Authorization: sk_live_abcd1234567890' \
    -H 'Content-Type: application/json' \
    -d '{
      "merchant_id": "merchant_123"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.satsuma.ai/payment-method/setup-intent', {
    method: 'POST',
    headers: {
      'Authorization': 'sk_live_abcd1234567890',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      merchant_id: 'merchant_123'
    })
  });

  const setupIntent = await response.json();
  ```

  ```python Python theme={null}
  import requests

  headers = {
      'Authorization': 'sk_live_abcd1234567890',
      'Content-Type': 'application/json'
  }

  data = {
      'merchant_id': 'merchant_123'
  }

  response = requests.post(
      'https://api.satsuma.ai/payment-method/setup-intent',
      headers=headers,
      json=data
  )

  setup_intent = response.json()
  ```

  ```java Java theme={null}
  import java.net.http.HttpClient;
  import java.net.http.HttpRequest;
  import java.net.http.HttpResponse;
  import java.net.URI;

  HttpClient client = HttpClient.newHttpClient();
  String requestBody = """
  {
    "merchant_id": "merchant_123"
  }
  """;

  HttpRequest request = HttpRequest.newBuilder()
      .uri(URI.create("https://api.satsuma.ai/payment-method/setup-intent"))
      .header("Authorization", "sk_live_abcd1234567890")
      .header("Content-Type", "application/json")
      .POST(HttpRequest.BodyPublishers.ofString(requestBody))
      .build();

  HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
  ```
</CodeGroup>

### Response

The API returns a checkout session with a URL where the API client can securely enter their payment information:

```json Response theme={null}
{
  "success": true,
  "data": {
    "url": "https://checkout.stripe.com/c/pay/cs_live_a1B2c3D4e5F6g7H8i9J0k1L2m3N4o5P6q7R8s9T0"
  }
}
```

<Info>
  Have your organization's authorized personnel visit the `url` to add a payment method.
</Info>

## Step 2: List Payment Methods

After your organization has saved payment methods, retrieve all available payment methods for the specific merchant.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET 'https://api.satsuma.ai/payment-method?merchant_id=merchant_123' \
    -H 'Authorization: sk_live_abcd1234567890'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.satsuma.ai/payment-method?merchant_id=merchant_123', {
    headers: {
      'Authorization': 'sk_live_abcd1234567890'
    }
  });

  const paymentMethods = await response.json();
  ```

  ```python Python theme={null}
  import requests

  headers = {
      'Authorization': 'sk_live_abcd1234567890'
  }

  params = {
      'merchant_id': 'merchant_123'
  }

  response = requests.get(
      'https://api.satsuma.ai/payment-method',
      headers=headers,
      params=params
  )

  payment_methods = response.json()
  ```

  ```java Java theme={null}
  import java.net.http.HttpClient;
  import java.net.http.HttpRequest;
  import java.net.http.HttpResponse;
  import java.net.URI;

  HttpClient client = HttpClient.newHttpClient();
  HttpRequest request = HttpRequest.newBuilder()
      .uri(URI.create("https://api.satsuma.ai/payment-method?merchant_id=merchant_123"))
      .header("Authorization", "sk_live_abcd1234567890")
      .GET()
      .build();

  HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
  ```
</CodeGroup>

### Response

The API returns a list of your API client organization's saved payment methods for this merchant:

```json Response theme={null}
{
  "success": true,
  "data": [
    {
      "id": "pm_1234567890abcdef",
      "type": "card",
      "card": {
        "brand": "visa",
        "last4": "4242",
        "exp_month": 12,
        "exp_year": 2025
      }
    },
    {
      "id": "pm_0987654321fedcba",
      "type": "card",
      "card": {
        "brand": "mastercard",
        "last4": "5555",
        "exp_month": 8,
        "exp_year": 2026
      }
    }
  ]
}
```

## Step 3: Submit Order with Saved Payment Method

Use a payment method to complete an order, with the merchant charging your organization directly. Provide the payment method ID in the order submission.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST 'https://api.satsuma.ai/order/order_123/submit' \
    -H 'Authorization: sk_live_abcd1234567890' \
    -H 'Content-Type: application/json' \
    -d '{
      "payment_method_id": "pm_1234567890abcdef"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.satsuma.ai/order/order_123/submit', {
    method: 'POST',
    headers: {
      'Authorization': 'sk_live_abcd1234567890',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      payment_method_id: 'pm_1234567890abcdef'
    })
  });

  const orderResult = await response.json();
  ```

  ```python Python theme={null}
  import requests

  headers = {
      'Authorization': 'sk_live_abcd1234567890',
      'Content-Type': 'application/json'
  }

  data = {
      'payment_method_id': 'pm_1234567890abcdef'
  }

  response = requests.post(
      'https://api.satsuma.ai/order/order_123/submit',
      headers=headers,
      json=data
  )

  order_result = response.json()
  ```

  ```java Java theme={null}
  import java.net.http.HttpClient;
  import java.net.http.HttpRequest;
  import java.net.http.HttpResponse;
  import java.net.URI;

  HttpClient client = HttpClient.newHttpClient();
  String requestBody = """
  {
    "payment_method_id": "pm_1234567890abcdef"
  }
  """;

  HttpRequest request = HttpRequest.newBuilder()
      .uri(URI.create("https://api.satsuma.ai/order/order_123/submit"))
      .header("Authorization", "sk_live_abcd1234567890")
      .header("Content-Type", "application/json")
      .POST(HttpRequest.BodyPublishers.ofString(requestBody))
      .build();

  HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
  ```
</CodeGroup>

### Response

The API returns the updated order with payment status, showing that your API client organization has been charged:

```json Response theme={null}
{
  "success": true,
  "data": {
    "id": "order_123",
    "status": "confirmed",
    "payment_status": "paid",
    "total": 29.99,
    "currency": "USD",
    "payment_method": {
      "id": "pm_1234567890abcdef",
      "type": "card",
      "card": {
        "brand": "visa",
        "last4": "4242"
      }
    }
  }
}
```