FlintflintDocs

Payment methods

Payment methods are saved cards linked to a customer. They enable one-click repeat payments and recurring subscription billing: once a payment method is active, you can charge it by passing its payment_method_id when creating a payment intent, or let subscription billing charge it automatically.

Saving a card is a two-step flow. Creating a payment method starts a setup intent and returns processor details your frontend uses to confirm card collection with Stripe.js. The payment method starts in pending and becomes active once Flint receives setup confirmation; only active payment methods are billable, so wait for status=active before charging or setting a default. Other statuses are expired, removed, and failed.

For the end-to-end saved-card flow, start with the Subscription billing guide. This page is the lower-level API reference.

Endpoints

List payment methods#

GET/v1/payment-methods

Returns saved payment methods for the merchant, optionally filtered to a customer. By default, only active payment methods are returned.

Query parameters
customer_idstring

Optional Flint customer ID filter.

page_sizeinteger

Page size, default 20, max 100.

page_tokenstring

Cursor returned by the previous list response.

typeenum

Filter by payment method type.

cardaffirm
statusenum

Filter by payment method status.

activependingexpiredremovedfailed
Response · 200
dataarray of objectrequired
metaobject
next_page_tokenstring
request_idstring
Bash
curl https://api.withflintpay.com/v1/payment-methods \
  -H "Authorization: Bearer YOUR_API_KEY"
JSON
{
  "data": [
    {
      "payment_method_id": "pm_123",
      "customer_id": "cus_123",
      "type": "card",
      "status": "active",
      "merchant_id": "mer_123",
      "created_at": "2026-03-17T14:30:00Z",
      "updated_at": "2026-03-17T14:30:00Z",
      "card": {
        "last4": "4242",
        "brand": "visa",
        "exp_month": 12,
        "exp_year": 2030
      }
    }
  ],
  "next_page_token": "Zm9yd2FyZC1vbmx5LW9wYXF1ZS1jdXJzb3I",
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Save payment method#

POST/v1/payment-methodsIdempotent

Initiates saving a payment method and returns the client setup payload needed to complete setup on the frontend.

Request body
customer_idstringrequired
typeenum
cardaffirmlink
Response · 201
dataobjectrequired
metaobject
request_idstring
Bash
curl -X POST https://api.withflintpay.com/v1/payment-methods \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "customer_id": "cus_123",
    "type": "card"
  }'
JSON
{
  "data": {
    "payment_method": {
      "payment_method_id": "pm_123",
      "customer_id": "cus_123",
      "type": "card",
      "status": "pending",
      "merchant_id": "mer_123",
      "created_at": "2026-03-17T14:30:00Z",
      "updated_at": "2026-03-17T14:30:00Z"
    },
    "client_setup": {
      "stripe": {
        "client_secret": "seti_secret_123",
        "account_id": "acct_123",
        "publishable_key": "pk_test_123"
      }
    }
  },
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Get payment method#

GET/v1/payment-methods/{payment_method_id}

Returns a single payment method by ID.

Path parameters
payment_method_idstringrequired

Flint payment method ID.

Query parameters
expandarray of enum

Supported expansions: customer. Expansion requires payments.payment_methods.read plus customers.customers.read. Limits: at most 10 unique expand paths per request; path depth at most 2. Send repeated expand parameters as the canonical form, for example expand=customer&expand=customer. Comma-separated values, expand[]=customer, and numeric expand[0]=customer are accepted for common client compatibility.

customer
Response · 200
dataobjectrequired
metaobject
request_idstring
Bash
curl https://api.withflintpay.com/v1/payment-methods/pm_123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Remove payment method#

DELETE/v1/payment-methods/{payment_method_id}Idempotent

Soft-removes a saved payment method so it can no longer be used for future payments.

Path parameters
payment_method_idstringrequired

Flint payment method ID.

Response · 200
dataobjectrequired
metaobject
request_idstring
Bash
curl -X DELETE https://api.withflintpay.com/v1/payment-methods/pm_123 \
  -H "Authorization: Bearer YOUR_API_KEY"
JSON
{
  "data": {
    "success": true
  },
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Set default payment method#

POST/v1/payment-methods/{payment_method_id}/set-defaultIdempotent

Sets the default payment method for the payment method's owning customer.

Path parameters
payment_method_idstringrequired

Flint payment method ID.

Response · 200
dataobjectrequired
metaobject
request_idstring
Bash
curl -X POST https://api.withflintpay.com/v1/payment-methods/pm_123/set-default \
  -H "Authorization: Bearer YOUR_API_KEY"
JSON
{
  "data": {
    "payment_method_id": "pm_123",
    "customer_id": "cus_123",
    "type": "card",
    "status": "active",
    "merchant_id": "mer_123",
    "created_at": "2026-03-17T14:30:00Z",
    "updated_at": "2026-03-17T14:30:00Z",
    "card": {
      "last4": "4242",
      "brand": "visa",
      "exp_month": 12,
      "exp_year": 2030
    }
  },
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}
Rate this doc