Skip to main content

​
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:
1

Create Setup Intent

Generate a Stripe-hosted page where API clients can securely add their payment methods
2

Retrieve Payment Methods

List all saved API client payment methods for a specific merchant
3

Submit Order

Use a saved API client payment method to complete an order

​
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. 
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"
  }'

​
Response

The API returns a checkout session with a URL where the API client can securely enter their payment information:
Response
{
  "success": true,
  "data": {
    "url": "https://checkout.stripe.com/c/pay/cs_live_a1B2c3D4e5F6g7H8i9J0k1L2m3N4o5P6q7R8s9T0"
  }
}
Have your organization’s authorized personnel visit the url to add a payment method.

​
Step 2: List Payment Methods

After your organization has saved payment methods, retrieve all available payment methods for the specific merchant. 
curl -X GET 'https://api.satsuma.ai/payment-method?merchant_id=merchant_123' \
  -H 'Authorization: sk_live_abcd1234567890'

​
Response

The API returns a list of your API client organization’s saved payment methods for this merchant:
Response
{
  "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. 
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"
  }'

​
Response

The API returns the updated order with payment status, showing that your API client organization has been charged:
Response
{
  "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"
      }
    }
  }
}