Skip to content

Save a card and charge it later

A saved card is a payment method that belongs to one customer. The customer enters the card once, in Stripe's card fields on your page, and completes any 3D Secure check their bank asks for. After that, Flint can charge the card without asking for the number again.

How you charge it later depends on whether the customer is there. A one-click repeat purchase runs while they are in your app. A fee you charge while they're away, an automatic invoice, or a subscription renewal runs while they are not, and relies on the authentication they completed when they saved the card.

How saving works#

You can save a card in two ways:

  • While the customer pays. Pay an order, or confirm a standalone payment intent, with save_payment_method: true, and the card that pays is saved too, with one bank authentication for both. See Save a card while the customer pays.
  • On its own, without a payment. Your backend starts the save, the browser collects the card, and Flint finishes it when the card processor confirms the setup.
Saving a cardResponse
BrowserYour backendFlintPOST /v1/payment-methods with the customer_ida pending payment method and client_setupaccount_id, publishable_key, and client_secretthe customer enters the card, and stripe.confirmSetup runs any 3D Secure checkpayment_method.activated: the card is active
  1. Your backend sends POST /v1/payment-methods with the customer_id to Flint
  2. Flint returns a pending payment method and client_setup to Your backend
  3. Your backend sends account_id, publishable_key, and client_secret to Browser
  4. Browser sends the customer enters the card, and stripe.confirmSetup runs any 3D Secure check to Browser
  5. Flint sends payment_method.activated: the card is active to Your backend

confirmSetup succeeding in the browser does not make the card chargeable. The card stays pending until Flint receives the processor's confirmation, usually a few seconds later. Only an active card can be charged or made the default.

Note: Payments save a card only when asked

With merchant credentials, paying an order or confirming a payment intent with save_payment_method: true keeps the card for off-session charges for the order's customer or the standalone payment intent's customer. See Save a card while the customer pays.

Without the flag, order pay and payment links keep no card on file. Subscription signup saves the card that starts the subscription, and a buyer can check "Save my details for faster checkout" in hosted checkout. A card saved in checkout can pay only in later checkouts, not subscriptions or automatic invoices; see Cards buyers save in checkout.

Before you start#

  • A webhook endpoint subscribed to payment_method.activated, payment_method.failed, and payment_method.archived, and to customer.updated if you keep your own copy of the default card.
  • A page in your app where the customer enters the card. The card fields come from Stripe.js, loaded with keys that Flint returns. You don't need a Stripe account of your own.
  • An API key with the scopes shown on these routes:

Only cards can be saved. ACH debit is a one-time payment and does not keep the bank account. Send an Idempotency-Key on every POST and DELETE so a request that times out can be retried safely. See Idempotency.

Save a card#

  1. Create the customer#

    A saved card always belongs to a customer. If your app already creates Flint customers at signup, reuse that ID.

    <!-- docs-test {"scenario":"saved","status":201,"isolateEmail":true,"expect":{"data.customer_id":"cus_Example"}} -->

    cURL
    curl -X POST https://api.withflintpay.com/v1/customers \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -H "Idempotency-Key: customer-ada-001" \
      -d '{
        "name": "Ada Lovelace",
        "email": "ada@example.com"
      }'
    

    Store data.customer_id with the user in your app.

  2. Start the save#

    From your backend, create a payment method for the customer:

    <!-- docs-test {"scenario":"setup","status":201,"fixtures":{"customer":true},"expect":{"data.status":"pending"}} -->

    cURL
    curl -X POST https://api.withflintpay.com/v1/payment-methods \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -H "Idempotency-Key: save-card-ada-001" \
      -d '{"customer_id": "cus_1kmn0aExample"}'
    
    Response
    {
      "data": {
        "payment_method_id": "pm_1kmn0aExample",
        "customer_id": "cus_1kmn0aExample",
        "type": "card",
        "status": "pending",
        "usage": "off_session",
        "is_default": false,
        "created_at": "2026-09-22T17:04:05Z",
        "updated_at": "2026-09-22T17:04:05Z",
        "client_setup": {
          "stripe": {
            "account_id": "acct_Example",
            "publishable_key": "pk_test_Example",
            "setup_intent": {
              "stripe_js_call": "confirm_setup",
              "client_secret": "seti_Example_secret_Example"
            }
          }
        }
      }
    }
    

    The payment method exists now, with status pending and no card details. The response is the payment method with client_setup beside its fields. Store payment_method_id and send client_setup.stripe to the browser. The client secret authorizes this one setup and nothing else, so your API key stays on your backend. A retry with the same Idempotency-Key returns the same payment method and client secret instead of starting a second save.

    Warning:

    Saving a card needs card payments enabled for the environment. Until they are, this request fails with MERCHANT_NOT_READY with reason capability_not_requested or MERCHANT_NOT_READY with reason onboarding_required.

  3. Collect the card in the browser#

    Mount the Stripe Payment Element with the client secret, then confirm the setup when the customer submits. The card fields run in Stripe-hosted iframes, so card numbers never reach your servers.

    HTML
    <script src="https://js.stripe.com/v3/"></script>
    
    <form id="card-form">
      <div id="payment-element"></div>
      <button type="submit">Save card</button>
      <div id="card-message" role="alert"></div>
    </form>
    
    JavaScript
    // Your backend runs the previous step and returns data.client_setup.stripe.
    const response = await fetch("/account/cards/setup", { method: "POST" });
    const setup = await response.json();
    
    const stripe = Stripe(setup.publishable_key, {
      stripeAccount: setup.account_id, // required: the setup lives on this account
    });
    const elements = stripe.elements({
      clientSecret: setup.setup_intent.client_secret,
    });
    elements.create("payment").mount("#payment-element");
    
    const message = document.querySelector("#card-message");
    
    document.querySelector("#card-form").addEventListener("submit", async (event) => {
      event.preventDefault();
      message.textContent = "";
    
      const { error, setupIntent } = await stripe.confirmSetup({
        elements,
        confirmParams: { return_url: "https://example.com/account/cards" },
        redirect: "if_required",
      });
    
      if (error) {
        // A refused card or a failed 3D Secure check. The form stays usable.
        message.textContent = error.message;
        return;
      }
    
      if (setupIntent.status === "succeeded") {
        // Flint still shows the card as pending. Wait for it to become active.
        message.textContent = "Saving your card...";
      }
    });
    

    confirmSetup opens the bank's 3D Secure challenge on the page when the bank asks for one. With redirect: "if_required", a card never leaves the page, and return_url is only used by payment methods that redirect.

  4. Wait for the card to become active#

    When the processor confirms the setup, Flint moves the card from pending to active, fills in card, and sends payment_method.activated. Act on either signal:

    • Webhook (recommended). Handle payment_method.activated for this payment_method_id. It arrives even if the customer closed the page right after submitting.
    • Poll. If the customer is watching a "Saving your card" message, read GET /v1/payment-methods/pm_1kmn0aExample about once a second until data.status is active. After 30 seconds, stop polling, tell the customer the card is still being saved, and let the webhook finish the job.

    <!-- docs-test {"scenario":"saved","status":200,"fixtures":{"savedCard":true}} -->

    cURL
    curl https://api.withflintpay.com/v1/payment-methods/pm_1kmn0aExample \
      -H "Authorization: Bearer YOUR_API_KEY"
    
    Response
    {
      "data": {
        "payment_method_id": "pm_1kmn0aExample",
        "customer_id": "cus_1kmn0aExample",
        "type": "card",
        "status": "active",
        "usage": "off_session",
        "is_default": false,
        "fingerprint": "9f3a6c1e0b7d4a58c2e1f06b3d94a7c5",
        "card": {
          "brand": "visa",
          "last4": "4242",
          "exp_month": 12,
          "exp_year": 2030
        },
        "created_at": "2026-09-22T17:04:05Z",
        "updated_at": "2026-09-22T17:04:09Z"
      }
    }
    

    card holds what you can show the customer: brand, last4, exp_month, exp_year, and wallet (apple_pay or google_pay) when the card came from a wallet. Flint never returns the card number.

    is_default is true when the customer's default_payment_method_id names this card; see Choose a default card. fingerprint is the same for every saved copy of one card number at your business, which finds duplicates. It appears once the card's details are known, so a pending card has none.

  5. Handle a refused card#

    The bank can refuse the setup, for example because the card is declined or the customer fails the 3D Secure check. confirmSetup returns the error in the browser. Flint moves the card to failed and sends payment_method.failed. For a failed 3D Secure check, failure_code can be authentication_required; other codes include card_declined, insufficient_funds, expired_card, and incorrect_cvc.

    A failed card can still be saved. Keep the form on the page and let the customer fix the details or enter another card: the same client secret accepts another attempt. When one succeeds, the same payment_method_id moves from failed to active and payment_method.activated follows.

    Your webhook handler can therefore see payment_method.failed and then payment_method.activated for one card. Decide from the latest event, or read the card. Each event fires at most once per card, so a second refusal in the same form sends no second payment_method.failed.

Save a card while the customer pays#

When your backend pays an order with a new card, save the card in the same request instead of asking for it twice. Send save_payment_method: true on POST /v1/orders/{order_id}/pay, and Flint saves the card that pays for the order's customer with usage: "off_session":

  • Send it only when the customer agreed on your page to later charges, including what you will charge and when.
  • The order needs customer_id. Set it with PATCH /v1/orders/{order_id} before you pay. Without it, the request returns 409 ACTION_NOT_ALLOWED with reason configuration_required and param: save_payment_method.
  • Send exactly one new card, Apple Pay, or Google Pay credential in payment_source: credential_type: "stripe_confirmation_token" with a ConfirmationToken in payment_source.stripe.confirmation_token, created with setupFutureUsage: "off_session" on Elements, or credential_type: "stripe_payment_method" with a raw payment method such as pm_card_visa in payment_source.stripe.payment_method. A raw payment method needs no setup flag, so a native app can save without Stripe's PaymentSheet. With action: "confirm_payment_intents", send the credential in payment_intents[i].payment_source.stripe.… for one selected payment intent. The other selected payment intents can pay with saved payment methods.
  • An API key or partner token needs payments.payment_methods.write. A Dashboard session needs no scope.
  • If the bank asks for 3D Secure, one authentication covers both the payment and the saved card. Open the pending action's Flint URL in a redirect, popup, or iframe, then confirm each payment intent again without payment_source; it keeps the choice it started with. To use stripe.handleNextAction instead, explicitly send client_action_type: "stripe" when starting the payment. Finish 3D Secure has the full sequence.
  • Flint saves the card once the payment is approved, including an authorization that waits for capture, and sends payment_method.activated with the card already active. Then read the payment intent: payment_source.card.payment_method_id names the saved card. A declined payment saves nothing. The order attempt has no entry for the save.

<!-- docs-test {"scenario":"save-while-paying","status":200,"fixtures":{"customer":true,"order":23500},"expect":{"data.order.payment_status":"paid","data.order_payment_attempt.status":"succeeded"}} -->

cURL
curl -X POST https://api.withflintpay.com/v1/orders/ord_1kmn0aExample/pay \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: pay-ord-1kmn0a-save-card" \
  -d '{
    "action": "pay",
    "payment_source": {"credential_type": "stripe_payment_method", "stripe": {"payment_method": "pm_card_visa"}},
    "save_payment_method": true,
    "expected_outstanding_money": {"amount": 23500, "currency": "USD"},
    "expected_version": 1792512060
  }'

Flint checks the request before it starts the payment, so a refusal leaves no payment attempt, no holds, and the same order version, and you can retry with the same Idempotency-Key once you fix it:

  • 403 INSUFFICIENT_SCOPE with param: save_payment_method: the key lacks payments.payment_methods.write.
  • 400 INVALID_REQUEST with detail code REQUIRED and param: save_payment_method: the request doesn't collect exactly one new card. A request with only a saved payment_method or an attached source, with two new cards, or with an attached selection next to the new card is refused. A saved payment_method selection next to the new card is allowed.
  • 400 INVALID_REQUEST with detail code NOT_ALLOWED:
    • param is the ConfirmationToken path (payment_source.stripe.confirmation_token, or payment_intents[i].payment_source.stripe.confirmation_token) when the token wasn't created with setupFutureUsage: "off_session". The reverse also fails: a ConfirmationToken created to save the card, sent without save_payment_method: true, is refused on any order that doesn't start a subscription.
    • param is the ConfirmationToken path or the payment_method path (payment_source.stripe.payment_method, or payment_intents[i].payment_source.stripe.payment_method) when the credential is a bank account or Affirm, which can't be saved.
    • param is the payment_method path when the raw payment method is a card Flint holds as on_session only.
    • param is save_payment_method when the payment uses splits, which can't save a card.
  • 404 RESOURCE_NOT_FOUND for the order's customer, or 409 ACTION_NOT_ALLOWED with reason in_progress while that customer is being deleted.
  • 409 MERCHANT_NOT_READY with reason capability_not_requested or onboarding_required, which carries a capability field instead of a param, or 409 PAYMENT_OPTION_UNAVAILABLE with param: save_payment_method: card payments or card saving aren't enabled for your account.
  • 403 FORBIDDEN with reason not_checkout_session and param: save_payment_method_phone: that option belongs to the checkout credential, with or without save_payment_method.

A checkout credential can't make this save. It keeps its own on-session save for faster checkout, described in Cards buyers save in checkout.

To save while confirming a payment intent instead, send save_payment_method: true on the confirm. Save the card for later charges covers the consent wording, the Elements setup, the errors, and the webhook in full. It applies to standalone payment intents and order legs confirmed with merchant credentials, and hosted checkout keeps its separate on-session saving.

Card statuses#

Saved card statusesStartFinal
  • pending moves to active on setup confirmed
  • pending moves to failed on bank refuses
  • failed moves to active on retry succeeds
  • active moves to archived on delete
  • active moves to expired on expiration month passes
  • expired moves to active on expiration date updated
  • pending moves to archived on delete
status on payment method
Final values do not change again
  • pending
    The save started and the processor has not confirmed it, or a buyer saved the card in checkout and has not confirmed it yet. Not chargeable. Wait for payment_method.activated.
  • active
    The only status you can charge, make the default, or attach to a subscription or invoice. A card with usage: "on_session" can pay only in checkouts the buyer completes.
  • failed
    The bank refused the setup, or a buyer who saved the card in checkout didn't confirm it within 24 hours. Not chargeable. After a refused setup, another attempt in the same form can still make it active, or you can delete it.
  • archivedFinal
    Deleted and detached from the processor for good. The card stays readable by ID, and lists leave it out unless you filter for status=archived. Save a new card instead.
  • expired
    The card's expiration month has passed. Flint rejects it for charges and as a default, and a status=active list leaves it out. If the card's expiration date is updated, its status returns to active.

Treat any status other than active as not chargeable, including values added later.

Cards buyers save in checkout#

In Flint's hosted checkout, a returning buyer may receive a code at the mobile number they added to their Flint wallet; this does not change how codes reach buyers in a headless checkout.

Every payment method has a usage that says when Flint may charge it:

usageSaved byCan pay
off_sessionPOST /v1/payment-methods, an order payment or standalone payment confirmed with save_payment_method: true, or a subscription signupAnything: order payments, checkouts, subscriptions, automatic invoices, and the customer's default
on_sessionThe buyer, by checking "Save my details for faster checkout" in hosted checkoutOnly checkouts the buyer completes

A buyer who checks the option saves the card they typed for your business only. Flint saves it after the payment succeeds, for the customer the checkout acts for, and sends payment_method.activated with usage: "on_session". That is the customer you created the session for or, for a guest, the customer whose email the buyer confirmed with a six-digit code Flint emailed them. When the checkout acts for no customer, a typed email selects only the customer that holds a pending save: the buyer can pay first, then confirm the save with an emailed code on the receipt. The pending card works for nothing until confirmed, even with a proof of the same email. The code goes only to the payment's email while it is still the customer's email; if it changed, the request is refused as not_offered. A wrong code saves nothing, and an unconfirmed save expires after 24 hours. Subscription signup and setup still need verification before collection when the email belongs to an existing customer. The next time, checkout emails the buyer a code as soon as they type their email. Once they enter it, checkout lists the cards they saved and pays with one.

A buyer can instead give a US or Canadian mobile phone number with the option: a guest in place of the emailed code, or a buyer who confirmed their email, to save the card with the number. Flint keeps the card for your customer with the buyer's email, as pending, and the buyer confirms it after paying, on the receipt, with a code Flint Pay texts to that number. Read payment_method_save.email_confirmation_required on the receipt before requesting a code. It is true from the moment the save is pending when a texted code alone cannot save the card. Request an emailed code first in that case: it saves the card by email without adding the number. When the flag is false, one texted code saves the card with the number. API callers can still confirm a texted code and then an emailed code to save with the number. The card becomes active, with payment_method.activated, once they do. A card not confirmed within 24 hours becomes failed, with payment_method.failed, and no one can pay with it. At the buyer's next checkout, typing their email texts a code to the number. The customer that holds a pending card gets nothing else from the payment: when the buyer paid as a guest and that customer already existed, the order stays unlinked, and the customer's /v1/me doesn't show it.

A pending card can receive at most 3 confirmation codes per channel. This quota does not reset: 409 LIMIT_REACHED with details[0].reason: saved_card_codes has remediation.retry: none, so confirm through the other channel. A daily cap on confirmation codes is the same reason and also carries limit and resets_at. Phone and network limits over a window of an hour or less return 429 RATE_LIMIT_EXCEEDED with Retry-After.

For returning buyers, offer an emailed code beside the texted code only when the verification's can_use_email_code is true. It reports cards saved by email at your business, or a Flint wallet where the checkout offers one. With phone cards only it is false, so offer paying without saved details if the text cannot be sent.

Each card opens only with the proof it was saved with. A card saved with a number never opens with an emailed code, and a card saved by email never opens with a texted one. A customer has one saved number: a card saved with a new number makes it the customer's number, and the cards saved with the old one are archived, with payment_method.archived for each, since no code can open them anymore. A buyer who lost the phone confirms their email with an emailed code, pays with a card, and saves it with their new number. Save with a mobile phone number covers the API.

The buyer agreed to faster checkout, not to be charged later, so Flint never charges an on_session card without them:

  • Starting a subscription, changing its card, or issuing an automatic invoice with it returns 400 INVALID_REQUEST and detail code NOT_ALLOWED.
  • Making it the customer's default returns 400 INVALID_REQUEST with detail code NOT_ALLOWED and param: default_payment_method_id, because subscriptions and automatic invoices charge the default.
  • Paying an order with it using your API key returns 400 INVALID_REQUEST with detail code NOT_ALLOWED. Only the checkout session's own credential can spend it.

To list only the cards you can charge without the buyer, filter by status and usage:

<!-- docs-test {"scenario":"saved","status":200,"list":true,"expect":{"request_id":"req_..."}} -->

cURL
curl "https://api.withflintpay.com/v1/payment-methods?customer_id=cus_1kmn0aExample&status=active&usage=off_session" \
  -H "Authorization: Bearer YOUR_API_KEY"

Saving in checkout is on by default. Turn it off with checkout.saved_payment_details. Checkout never offers it when customer accounts are merchant hosted, for invoice, subscription, and return checkouts, or for Apple Pay, Google Pay, ACH debit, and Affirm. To build the same option into your own checkout, see Offer to save the card.

Choose a default card#

Flint never picks a default card for you, not even the customer's first card. The default is a field on the customer, so you set it by updating the customer:

<!-- docs-test {"scenario":"saved","status":200} -->

cURL
curl -X PATCH https://api.withflintpay.com/v1/customers/cus_1kmn0aExample \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: default-card-ada-001" \
  -d '{"default_payment_method_id": "pm_1kmn0aExample"}'
Response
{
  "data": {
    "customer_id": "cus_1kmn0aExample",
    "name": "Ada Lovelace",
    "email": "ada@example.com",
    "phone": null,
    "tax_identity": null,
    "default_payment_method_id": "pm_1kmn0aExample",
    "version": 4
  }
}

The response is the customer. Every customer response includes default_payment_method_id, which is null when there is no default. Send null to clear the default, or another card's ID to replace it. A request that sends the value the customer already has changes nothing and sends no event.

The card must belong to the customer, be active, and have usage: "off_session":

ProblemResponse
No payment method with that ID404 RESOURCE_NOT_FOUND, with param: "default_payment_method_id"
The card belongs to another customer400 INVALID_REQUEST, detail NOT_ALLOWED, param: default_payment_method_id
The buyer saved the card in checkout (usage: "on_session")400 INVALID_REQUEST, detail NOT_ALLOWED, param: default_payment_method_id
The card is pending, failed, expired, or archived409 ACTION_NOT_ALLOWED with reason unsupported_state
The customer is being deleted409 ACTION_NOT_ALLOWED with reason in_progress

Each change to the default advances the customer's version once and sends customer.updated with the customer as it is after the change. The payment methods themselves don't change, so they send no payment_method event. To refuse a change made on an out-of-date read, send expected_version with the version you read; a different version returns 409 VERSION_CONFLICT and changes nothing.

Deleting the default card clears the default in the same way. It advances the version and sends customer.updated along with payment_method.archived, so a PATCH that carries the version from before the deletion returns VERSION_CONFLICT.

The default fills in when a request leaves the card out:

ChargeUses the default
New subscription with no payment_method_idYes, at creation. The subscription keeps that card afterward.
Automatic invoice with no collection.payment_method_idYes, when the invoice is issued. The invoice keeps that card afterward.
Order paymentNo. Pass the card in payment_source.

Changing the default does not move existing subscriptions or issued invoices to the new card.

To mark the default in your UI, read is_default on each card. It is true on the card the customer's default_payment_method_id names and false on every other card, including an archived one. To read the default card itself, expand it on the customer. Expanding needs both customers.read and payments.payment_methods.read.

<!-- docs-test {"scenario":"saved","status":200,"expect":{"data.default_payment_method_id":"pm_Example","data.default_payment_method.status":"active"}} -->

cURL
curl "https://api.withflintpay.com/v1/customers/cus_1kmn0aExample?expand=default_payment_method" \
  -H "Authorization: Bearer YOUR_API_KEY"

Deleting the default card clears default_payment_method_id. Flint does not promote another card, so set a new default if the customer has one.

Charge a saved card#

Pick the path by who is present when the charge runs:

Customer present

Pay an order

A one-click repeat purchase. The customer picks a saved card in your app, sees the total, and confirms. If the bank asks for 3D Secure, they complete it on the page.

Customer not there

Pay an order with the customer absent

A no-show fee, damages, or a top-up. Pay the order with customer_presence: "absent", and Flint charges the card without the customer. For usage you bill and want retried on a schedule, issue an automatic invoice. For the same amount on a schedule, use subscription billing.

The difference is how the charge reaches the bank. A charge the customer isn't present for goes to the card network as merchant-initiated, backed by the authentication they completed while saving the card, so the bank can approve it without a challenge. Flint sends payments made with customer_presence: "absent", automatic invoice charges, and subscription renewals this way. Any other order payment goes to the bank with the customer present, and the bank can ask for 3D Secure, which nobody answers if your backend pays while the customer is away. Each payment intent's customer_presence reports which way its latest charge went.

While the customer is present#

Create an order for the customer. With customer_id set, Flint checks that the card you charge belongs to that customer.

<!-- docs-test {"scenario":"saved","status":201,"expect":{"data.status":"open"}} -->

cURL
curl -X POST https://api.withflintpay.com/v1/orders \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: order-ada-credits-0922" \
  -d '{
    "customer_id": "cus_1kmn0aExample",
    "line_items": [{
      "type": "custom",
      "name": "Credit pack, 1,000 credits",
      "quantity": 1,
      "unit_price_money": {"amount": 3200, "currency": "USD"},
      "fulfillment": {"requirement": "none"}
    }]
  }'

Show data.settlement_amounts.outstanding_money from the response as the total. When the customer confirms, pay the order with the card they chose:

<!-- docs-test {"scenario":"saved","status":200} -->

cURL
curl -X POST https://api.withflintpay.com/v1/orders/ord_1kmn0aExample/pay \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: pay-ada-credits-0922" \
  -d '{
    "action": "pay",
    "payment_source": {"credential_type": "payment_method", "payment_method_id": "pm_1kmn0aExample"},
    "expected_outstanding_money": {"amount": 3200, "currency": "USD"}
  }'
Response
{
  "data": {
    "order": {
      "order_id": "ord_1kmn0aExample",
      "payment_status": "paid",
      "settlement_amounts": {
        "paid_money": {"amount": 3200, "currency": "USD"},
        "outstanding_money": {"amount": 0, "currency": "USD"}
      }
    },
    "order_payment_attempt": {
      "order_payment_attempt_id": "opat_1kmn0aExample",
      "status": "succeeded",
      "is_resumable": false
    }
  }
}
  • payment_source.payment_method_id must be an active card with usage: "off_session". An unknown card returns 404 RESOURCE_NOT_FOUND with resource_type: payment_method. A pending, failed, or archived card returns 409 ACTION_NOT_ALLOWED with the card reference and current status. A card that belongs to a different customer returns 400 INVALID_REQUEST with detail code NOT_ALLOWED. A card the buyer saved in checkout returns 400 INVALID_REQUEST with detail code NOT_ALLOWED.
  • expected_outstanding_money is the total the customer approved. If tax, shipping, or a promotion changed the balance since, Flint returns VERSION_CONFLICT without charging. Show the new total and ask again.
  • Order payments never fall back to the default card. Without payment_source, the request fails with 400 INVALID_REQUEST and detail code REQUIRED on payment_source.

Read the result from data.order_payment_attempt.status, not the HTTP status, because a declined card also returns 200. succeeded means the order is paid. A saved card can still be challenged: the bank may ask for 3D Secure on any charge with the customer present, and the attempt comes back as requires_action. Open the pending action's Flint URL in a redirect, popup, or iframe, then resume the attempt with action: "resume". To use stripe.handleNextAction instead, explicitly send client_action_type: "stripe" when starting the payment. Use its secret only for that next-action call; it can also confirm the underlying payment with another card. Finish 3D Secure has the full sequence, and Handle a decline covers failed attempts.

To build the card picker, list the customer's cards with status=active, so the picker holds only cards you can charge, and show card.brand, card.last4, and the expiry, with the default, the card where is_default is true, preselected when it is still active. Flint does not merge duplicates, so a customer who saves the same card twice has two payment methods. Collapse cards with the same fingerprint in the picker.

If you would rather not build the picker, a hosted checkout session created for the customer, through the order's customer_id or, for a quick pay or subscription plan session, the session's customer_id, offers that customer's saved cards on the payment page. A session created without a customer offers saved cards only after the buyer confirms their email with a code in checkout; typing the email of an existing customer isn't enough. See Confirm the buyer's email.

When the customer is not there#

For a charge you decide on while the customer is away, such as a no-show fee, damages, or a top-up, create an order for the amount and pay it with the saved card and customer_presence: "absent":

<!-- docs-test {"scenario":"off-session","status":200,"fixtures":{"savedCard":true,"order":5000},"expect":{"data.order.payment_status":"paid","data.order_payment_attempt.status":"succeeded"}} -->

cURL
curl -X POST https://api.withflintpay.com/v1/orders/ord_1kmn0aExample/pay \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: no-show-fee-ada-1104" \
  -d '{
    "action": "pay",
    "payment_source": {
      "credential_type": "payment_method",
      "payment_method_id": "pm_1kmn0aExample",
      "customer_presence": "absent"
    },
    "expected_outstanding_money": {"amount": 5000, "currency": "USD"}
  }'

Flint confirms the charge as merchant-initiated on the card's stored credential, and the payment intent reports customer_presence: "absent", as renewals and automatic invoice charges do.

  • Only you can send it. customer_presence: "absent" works with your own credentials: an API key, a partner token, or a Dashboard session. The checkout credential gets 400 INVALID_REQUEST with detail code NOT_ALLOWED on payment_source.customer_presence, as does any credential_type other than payment_method.
  • The card must be reusable. Charge an active card with usage: "off_session". A card the buyer saved in checkout returns 409 ACTION_NOT_ALLOWED with reason payment_method_not_reusable. Cards, Apple Pay, and Google Pay can be charged this way; a saved bank account returns 400 INVALID_REQUEST with detail code NOT_ALLOWED.
  • The bank can still refuse. A decline or a bank that insists on authentication ends the attempt failed, with the payment intent in requires_payment_method and last_payment_error.code set, authentication_required in the second case. It never waits in requires_action, because nobody is there to authenticate. Don't charge the card again without the customer: ask them to pay while present, for example through a checkout session for the order.
  • A retry can't charge twice. Send the same Idempotency-Key to retry a request that timed out; Flint returns the first result.

To charge a standalone payment intent instead of an order, confirm it with credential_type: "payment_method", the card's payment_method_id, and customer_presence: "absent". The same rules apply, with errors on customer_presence and payment_method_id.

Bill usage with an automatic invoice#

For an amount you bill, such as usage or an overage, that should retry on your schedule if it declines, use an invoice in automatic collection mode. Flint charges the card as soon as you issue the invoice, sends it as a charge the customer is not present for, and retries on your schedule if it declines.

<!-- docs-test {"skip":"Automatic invoice collection uses hosted background workers; local API does not execute them."} -->

cURL
curl -X POST https://api.withflintpay.com/v1/invoices \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: invoice-ada-usage-sept" \
  -d '{
    "type": "quick_pay",
    "quick_pay": {
      "customer_id": "cus_1kmn0aExample",
      "line_items": [{
        "type": "custom",
        "name": "API usage, September 2026",
        "quantity": 1,
        "unit_price_money": {"amount": 4870, "currency": "USD"},
        "fulfillment": {"requirement": "none"}
      }]
    },
    "collection": {
      "mode": "automatic",
      "payment_method_id": "pm_1kmn0aExample"
    },
    "payment_due": {"type": "none"}
  }'

The invoice is a draft until you issue it. caller_managed skips Flint's invoice email when your app sends its own receipt:

<!-- docs-test {"skip":"Automatic invoice collection uses hosted background workers; local API does not execute them."} -->

cURL
curl -X POST https://api.withflintpay.com/v1/invoices/inv_1kmn0aExample/issue \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: issue-ada-usage-sept" \
  -d '{"delivery_mode": "caller_managed"}'
  • The card is chosen at issue. Flint uses collection.payment_method_id, or the customer's default card when you leave it out. With neither, the issue request fails with ACTION_NOT_ALLOWED and reason configuration_required. A card that is not active fails with ACTION_NOT_ALLOWED with reason unsupported_state.
  • The charge runs moments after issue, not inside the issue response. Watch invoice.paid for success and invoice_payment_attempt.failed for a decline. An invoice with a payment schedule charges each installment on its due date instead.
  • Declines retry on your schedule, set in invoices.autopay_retry_policy.retry_day_offsets and fixed for the invoice when it is issued. To try again sooner, call POST /v1/invoices/{invoice_id}/collect with a new Idempotency-Key.
  • A different card can pay an outstanding amount. Pass another active saved card in payment_method_id when calling collect, or ask the customer to pay by card from the hosted invoice. Future automatic charges still use the card selected at issue.

Automatic collection in the invoicing guide covers the attempt history.

Manage saved cards#

List a customer's cards#

<!-- docs-test {"scenario":"saved","status":200,"list":true,"expect":{"request_id":"req_..."}} -->

cURL
curl "https://api.withflintpay.com/v1/payment-methods?customer_id=cus_1kmn0aExample" \
  -H "Authorization: Bearer YOUR_API_KEY"
Response
{
  "data": [
    {
      "payment_method_id": "pm_1kmn0aExample",
      "customer_id": "cus_1kmn0aExample",
      "type": "card",
      "status": "active",
      "usage": "off_session",
      "is_default": true,
      "fingerprint": "9f3a6c1e0b7d4a58c2e1f06b3d94a7c5",
      "card": {"brand": "visa", "last4": "4242", "exp_month": 12, "exp_year": 2030},
      "created_at": "2026-09-22T17:04:05Z",
      "updated_at": "2026-09-22T17:04:09Z"
    }
  ]
}

The list returns cards in every status except archived, newest first, so it includes pending, failed, and expired cards along with active ones. Pass status=active for a card picker or anywhere else you need cards you can charge. Pass another status to list just that status, such as status=expired for cards past their expiration month, status=pending to find saves the customer abandoned, or status=archived for deleted cards. Pass usage=off_session to leave out cards buyers saved in checkout, for example in a picker for a subscription or an automatic invoice. Page with page_size (up to 100, default 20) and page_token; the last page has no next_page_token. Leave out customer_id to list every saved card in the environment. See Pagination.

Find duplicate cards#

Two payment methods with the same fingerprint are saved copies of one card number. The value is the same across all your customers in one environment, and it differs between your sandbox and live environments and from any other business's value for the same card. It identifies the card nowhere else, so it can't be used to look a card up outside Flint.

A card added through Apple Pay or Google Pay can have a different fingerprint from the same card entered directly, so equal fingerprints prove a match and different ones don't prove a difference. A payment method has no fingerprint until its card details are known, and loses it when the customer is deleted. Buyers never receive it: /v1/me responses and the checkout credential leave it out.

Flint doesn't merge duplicates for you. You decide which copy to keep. Deleting a copy that a subscription uses is refused, so move the subscription to the card you keep first.

Replace the card on a subscription#

A subscription charges the card it was created with, even after the customer's default changes. To move a subscription to a new card, save the card first, then send its ID as payment_method_id in an update:

<!-- docs-test {"skip":"Updating a subscription needs an existing subscription and second saved-card fixture; outside one-time payment coverage."} -->

cURL
curl -X PATCH https://api.withflintpay.com/v1/subscriptions/sub_1kmn0aExample \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: sub-ada-new-card-001" \
  -d '{"payment_method_id": "pm_2kmn0aExample"}'

The card must belong to the subscription's customer, or the request fails with 400 INVALID_REQUEST, detail code NOT_ALLOWED, and param: payment_method_id. A card that is still pending returns 409 ACTION_NOT_ALLOWED with reason status_not_reached and changes nothing; once payment_method.activated arrives, send the request again to attach the card. A card the buyer saved in checkout returns 400 INVALID_REQUEST with detail code NOT_ALLOWED. Either refusal's next_steps says whether you can reuse its Idempotency-Key.

Changing the card does not retry a past_due renewal. Follow up with a payment retry; see When a renewal payment fails.

Delete a card#

A card with is_removing: true is being deleted. Keep it in the account card list as Removing, offer the same delete request as a retry, and leave it out of card pickers. New payments and subscription bindings refuse that card with 409 ACTION_NOT_ALLOWED; use another card. Payments already confirmed can finish. Flint restores a card if removal never started, or finishes a stalled removal automatically.

<!-- docs-test {"scenario":"saved","status":200,"expect":{"data.status":"archived"}} -->

cURL
curl -X DELETE https://api.withflintpay.com/v1/payment-methods/pm_1kmn0aExample \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: delete-card-ada-001"
Response
{
  "data": {
    "payment_method_id": "pm_1kmn0aExample",
    "customer_id": "cus_1kmn0aExample",
    "type": "card",
    "status": "archived",
    "usage": "off_session",
    "is_default": false,
    "fingerprint": "9f3a6c1e0b7d4a58c2e1f06b3d94a7c5",
    "card": {"brand": "visa", "last4": "4242", "exp_month": 12, "exp_year": 2030},
    "created_at": "2026-09-22T17:04:05Z",
    "updated_at": "2026-10-01T09:12:44Z"
  }
}

The response is the card with status archived. Deleting a card that is already archived returns it again, still archived.

Deleting a card:

  • Detaches it from the processor so it can never be charged again, and sets its status to archived. The card stays readable by ID, and lists leave it out unless you filter for status=archived.
  • Clears the customer's default_payment_method_id if it pointed at this card. That advances the customer's version and sends customer.updated. An archived card is never the default, so is_default is false in the response.
  • Sends payment_method.archived.
  • Succeeds again, with no second event, if the card is already archived.

A subscription that can still charge the card blocks deletion with RESOURCE_IN_USE. A scheduled cancellation releases the card once no setup fee, payment, unpaid subscription order, or retry remains. Fully prepaid deliveries, including held deliveries, can finish without the card. Change the subscription's payment_method_id, or cancel it and resolve any remaining payment. Deletion refusal reasons distinguish future renewal, a pending payment or retry, and an unpaid balance.

Open invoices do not block deletion, but an automatic invoice issued against the card can no longer collect with it. Void and reissue those invoices for another card.

pending cards can be deleted too. Flint does not expire an abandoned save, so it stays pending until you delete it, and a customer deletion request cannot be approved while the customer has any active or pending card.

Card details that change on their own#

When a bank reissues a card, the card network can update the saved card. Flint applies the new brand, last4, exp_month, and exp_year without changing the status or the payment_method_id, and sends payment_method.updated. Its data.previous_attributes.card holds the card details from before the update. A card whose expiry date passes shows status: "expired" when you read it, with no event, so compare exp_month and exp_year with the date if you schedule your own check. An expired card that gets a new expiry this way reads as active again, with payment_method.updated rather than payment_method.activated.

Let customers manage their own cards#

If customers manage their cards in an account page you build, call the /v1/me/payment-methods routes with a customer session instead of your API key. They list, read, save, and delete cards for the signed-in customer only, with the same statuses, list default, and webhooks. The buyer chooses a default card with PATCH /v1/me and {"default_payment_method_id": "pm_1kmn0aExample"}, or clears it with null, under the rules in Choose a default card. Optional expected_version works there too. Three things differ from the routes above:

  • The save request takes no customer_id. Send the optional type field as you would on the merchant route.
  • GET /v1/me/payment-methods/{payment_method_id} takes no expand, and answers 404 for a card that belongs to another customer. While a new card is pending, poll it until status is active.
  • Payment methods include is_default but never fingerprint.

Build your own customer account walks through that page. Flint's hosted customer account includes card management with no code.

Webhooks#

  1. What happens: The customer submits the card
  2. Flint sends: payment_method.activatedorpayment_method.failed
    Activated when the processor confirms the setup and the card is active and can be charged. Failed when the bank refuses it.
  3. What happens: The customer tries again in the same form
  4. Flint sends: payment_method.activated
    Same payment_method_id as the earlier payment_method.failed.
  5. What happens: You or the customer delete the card
  6. Flint sends: payment_method.archived
    The card can no longer be charged. It stays readable with status archived.
  7. What happens: You or the customer change the default card, or delete the default card
  8. Flint sends: customer.updated
    Carries the customer with the new default_payment_method_id and version.
  9. What happens: You issue an automatic invoice
  10. Flint sends: invoice.paidorinvoice_payment_attempt.failed
    The charge succeeded, or it declined and waits for a retry.

Every payment_method event carries the payment method as GET /v1/payment-methods/{payment_method_id} returns it when the event is created, so data.object has payment_method_id, customer_id, status, usage, card, is_default, and fingerprint. payment_method.failed adds failure_code and failure_message when the bank gave a reason. payment_method.archived carries the card after the deletion, with status: "archived" and is_default: false. Each event fires at most once per card.

is_default and fingerprint are the values when the event was created. Read the payment method or the customer when you need the current default.

The default belongs to the customer, so a change to it sends customer.updated, not a payment_method event. Subscribe to customer.updated to keep your own copy of the default current. That includes the change Flint makes when the default card is deleted, which arrives with payment_method.archived. The passing of a card's expiration month and a network update to its details send no event.

Subscription signup through hosted checkout, headless checkout, and payment links also saves a card and sends payment_method.activated, so your handler sees cards from every surface. So does an order payment or standalone payment sent with save_payment_method: true, once the payment is approved. So does a buyer who saves their card in checkout, with usage: "on_session", once they confirm it when they saved it with a mobile phone number. None of these cards become the default.

Test it#

Use a sandbox API key and these cards. Any future expiry and any CVC work.

Card numberWhile savingOne-click order paymentAutomatic invoice
4242 4242 4242 4242Saves.Succeeds.Succeeds.
4000 0025 0000 31553D Secure challenge, then saves.Challenges again with requires_action.Succeeds with no challenge.
4000 0027 6000 31843D Secure challenge, then saves.Challenges with requires_action.Declines because the bank requires authentication.
4000 0000 0000 0341Saves.Declines.Declines, then retries on your schedule.
4000 0000 0000 0002Refused. The card becomes failed with card_declined.Not chargeable.Not chargeable.

To save a card while paying an order, send save_payment_method: true with pm_card_visa as payment_source.stripe.payment_method (credential_type: "stripe_payment_method"), or with a ConfirmationToken created from a test card in payment_source.stripe.confirmation_token. The 3D Secure card 4000 0025 0000 3155 challenges once on the order and saves, and a later customer_presence: "absent" order payment with that card goes through with no challenge. A payment that declines saves nothing.

In the sandbox 3D Secure dialog, choose Fail to rehearse a refused save, then enter in the same form to watch the same card move from failed to active. Subscription renewals behave like the automatic invoice column. The test card reference lists every Stripe test card, and Testing covers checkout.

A sandbox sends no texts, so a card saved with a mobile phone number is confirmed with a test code. Give any valid US or Canadian mobile phone number, such as +14155552671, then enter one of these codes where the buyer types the texted code:

CodeResult
000000Wrong code. It counts as a wrong try.
999999503 SERVICE_UNAVAILABLE, as when texts can't be checked.
Any other six digitsConfirms the code.

The same codes work for the code texted to a returning buyer. Emailed codes arrive as in live mode.

Errors#

  • HTTP 409
    Reason capability_not_requested. The account never requested card payments, so it cannot save cards. Check accept_card_payments in readiness.capabilities on GET /v1/merchant, then ask Flint support to request it.
  • HTTP 409
    Reason unsupported_state. Setting a default, issuing an automatic invoice, or changing a subscription's card needs an active card. Wait for payment_method.activated, or save a new card if this one is expired, failed, or archived.
  • HTTP 409
    VERSION_CONFLICTRefresh, then retry
    The customer changed since the version you sent as expected_version, for example because its default card was deleted. Read the customer again and retry with its current version.
  • HTTP 409
    An order payment named a card that is not active. The detail names the payment_method and its current status. Use an active card. An unknown card returns 404 RESOURCE_NOT_FOUND instead.
  • HTTP 400
    param names the input. Detail code NOT_ALLOWED means the saved card belongs to another customer, or the buyer saved it in checkout and this request needs a card with usage: "off_session". Choose an active card owned by the customer with usage: "off_session". An order payment with no payment_source returns detail code REQUIRED. Orders never fall back to the default card.
  • HTTP 409
    VERSION_CONFLICTRefresh, then retry
    The order total changed after the customer approved it. Show the new total and ask again.
  • HTTP 409
    Reason configuration_required means an automatic invoice has no card to charge. Update the draft's collection.payment_method_id or set a default card, then issue again.
  • HTTP 409
    Reason status_not_reached. A subscription was given a card that is still pending. Wait for payment_method.activated, then send the request again; next_steps says whether you can reuse its Idempotency-Key.
  • HTTP 409
    A subscription can still charge the card. Change its payment_method_id, or cancel it and resolve any remaining payment before deleting the card.
  • HTTP 400
    Only card can be saved. Leave type out or send card.
  • HTTP 409
    details[0].reason: in_progress. The customer is being deleted or was deleted, so new cards cannot be saved or made the default.

Error handling covers the envelope these arrive in.

Common mistakes#

  • Charging the card when the browser confirms. The card is pending until payment_method.activated arrives.
  • Treating payment_method.failed as final. The customer can fix the card in the same form, and the same card becomes active.
  • Assuming the first card becomes the default. Flint never sets a default on its own. PATCH the customer with default_payment_method_id.
  • Waiting for a payment method event when the default changes. The default belongs to the customer, so the event is customer.updated.
  • Paying orders for a customer who is not there. An order payment is sent with the customer present, and a 3D Secure request has nobody to answer it. Use an automatic invoice or a subscription.
  • Expecting a new default to move existing charges. Subscriptions and issued invoices keep their own card.
  • Offering every saved card for a subscription. Cards buyers saved in checkout have usage: "on_session" and are refused. List with usage=off_session.
  • Leaving abandoned saves behind. A pending card never expires, and it blocks a customer deletion request until you delete it.

Next steps#

Charge a paid-order edit's balance#

Create the order edit with balance_due_behavior: "collect", then confirm its payment_intent_id with the saved card. Send customer_presence: "absent" when the buyer is away, using a method saved for off-session use. If the bank requires authentication, bring the buyer back to complete it. The edit stays pending until payment succeeds, and cancellation or expiry leaves the original order's items and money unchanged.

Was this helpful?