Skip to main content

Working with Saved Payment Methods

A saved payment method is a tokenized card, PayPal account, or Apple Pay wallet stored against a customer. Once saved, it can be reused for future payments and subscription renewals without requiring the customer to enter their details again.

How payment methods are saved​

Payment methods are created automatically when a customer completes a payment through the Checkout SDK. There is no standalone endpoint to save a card or PayPal account in isolation. The customer's payment details are tokenized and stored securely during the authorization step.

After authorization, Odus associates the new payment method with the customer. You can then retrieve its ID and use it for future payments.

Listing payment methods for a customer​

To retrieve all payment methods for a specific customer, send a GET /payment-methods request with the customer[eq] filter:

GET /payment-methods?customer[eq]=cus_2R0uWz4tu9wxTMBXxj9CJfSE9vV

The response contains a paginated list of payment methods:

Response
{
  "data": [
    {
      "id": "pm_2RTUw7lL6IuBUwGQOD1EB0OAmx7",
      "type": "card",
      "customer": "cus_2R0uWz4tu9wxTMBXxj9CJfSE9vV",
      "isDefault": true,
      "card": {
        "brand": "visa",
        "lastFour": "4242",
        "expMonth": "12",
        "expYear": "2027",
        "cardholderName": "Jane Doe"
      },
      "createdAt": "2024-02-18T12:00:00Z",
      "updatedAt": "2024-02-21T12:15:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 10,
    "itemCount": 1,
    "pageCount": 1,
    "hasPreviousPage": false,
    "hasNextPage": false
  }
}

To retrieve a single payment method by its ID, use GET /payment-methods/:id.

tip

To find only the default payment method for a customer, add isDefault[eq]=true to the request: GET /payment-methods?customer[eq]=cus_xxx&isDefault[eq]=true

See the GET /payment-methods reference for the full list of response fields.

Using a saved payment method for a payment​

To charge a customer with a saved payment method, provide the customer and paymentMethod IDs when creating a payment. The payment method must belong to the specified customer.

Creating a payment with a saved payment method
{
  "amount": 5000,
  "currency": "usd",
  "initiator": "customer",
  "paymentMethodOptions": {
    "card": {
      "mode": "cascade",
      "cascade": "cas_abc123"
    }
  },
  "customer": "cus_2R0uWz4tu9wxTMBXxj9CJfSE9vV",
  "paymentMethod": "pm_2RTUw7lL6IuBUwGQOD1EB0OAmx7"
}

For more details on creating and authorizing payments, see Making Payments.

Payment methods and subscriptions​

When a subscription is created for a customer, Odus uses the customer's default payment method at that point in time for all recurring charges. If the default payment method changes after the subscription is created, existing subscriptions are not affected — they continue to use the payment method that was active when they were set up.

warning

If the payment method used by a subscription expires, recurring charges will fail. Make sure customers keep their payment methods up to date.

Viewing payment methods in the Dashboard​

Open the Customers page and select a customer. The customer detail page includes a Payment methods section showing all saved payment methods for that customer. Each row shows:

  • The cardholder name (or customer name for non-card methods)
  • The payment method type and last four digits
  • The expiration date (cards only)
  • Whether the method is the customer's default