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.
- Your backend sends POST /v1/payment-methods with the customer_id to Flint
- Flint returns a pending payment method and client_setup to Your backend
- Your backend sends account_id, publishable_key, and client_secret to Browser
- Browser sends the customer enters the card, and stripe.confirmSetup runs any 3D Secure check to Browser
- 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, andpayment_method.archived, and tocustomer.updatedif 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#
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 withPATCH /v1/orders/{order_id}before you pay. Without it, the request returns409 ACTION_NOT_ALLOWEDwith reasonconfiguration_requiredandparam: 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 inpayment_source.stripe.confirmation_token, created withsetupFutureUsage: "off_session"on Elements, orcredential_type: "stripe_payment_method"with a raw payment method such aspm_card_visainpayment_source.stripe.payment_method. A raw payment method needs no setup flag, so a native app can save without Stripe's PaymentSheet. Withaction: "confirm_payment_intents", send the credential inpayment_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 usestripe.handleNextActioninstead, explicitly sendclient_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.activatedwith the card alreadyactive. Then read the payment intent:payment_source.card.payment_method_idnames 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 -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_SCOPEwithparam: save_payment_method: the key lackspayments.payment_methods.write.400 INVALID_REQUESTwith detail codeREQUIREDandparam: save_payment_method: the request doesn't collect exactly one new card. A request with only a savedpayment_methodor anattachedsource, with two new cards, or with anattachedselection next to the new card is refused. A savedpayment_methodselection next to the new card is allowed.400 INVALID_REQUESTwith detail codeNOT_ALLOWED:paramis the ConfirmationToken path (payment_source.stripe.confirmation_token, orpayment_intents[i].payment_source.stripe.confirmation_token) when the token wasn't created withsetupFutureUsage: "off_session". The reverse also fails: a ConfirmationToken created to save the card, sent withoutsave_payment_method: true, is refused on any order that doesn't start a subscription.paramis the ConfirmationToken path or thepayment_methodpath (payment_source.stripe.payment_method, orpayment_intents[i].payment_source.stripe.payment_method) when the credential is a bank account or Affirm, which can't be saved.paramis thepayment_methodpath when the raw payment method is a card Flint holds ason_sessiononly.paramissave_payment_methodwhen the payment usessplits, which can't save a card.
404 RESOURCE_NOT_FOUNDfor the order's customer, or409 ACTION_NOT_ALLOWEDwith reasonin_progresswhile that customer is being deleted.409 MERCHANT_NOT_READYwith reasoncapability_not_requestedoronboarding_required, which carries acapabilityfield instead of aparam, or409 PAYMENT_OPTION_UNAVAILABLEwithparam: save_payment_method: card payments or card saving aren't enabled for your account.403 FORBIDDENwith reasonnot_checkout_sessionandparam: save_payment_method_phone: that option belongs to the checkout credential, with or withoutsave_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#
- 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 methodTreat 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:
usage | Saved by | Can pay |
|---|---|---|
off_session | POST /v1/payment-methods, an order payment or standalone payment confirmed with save_payment_method: true, or a subscription signup | Anything: order payments, checkouts, subscriptions, automatic invoices, and the customer's default |
on_session | The buyer, by checking "Save my details for faster checkout" in hosted checkout | Only 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_REQUESTand detail codeNOT_ALLOWED. - Making it the customer's default returns
400 INVALID_REQUESTwith detail codeNOT_ALLOWEDandparam: default_payment_method_id, because subscriptions and automatic invoices charge the default. - Paying an order with it using your API key returns
400 INVALID_REQUESTwith detail codeNOT_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 "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 -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"}'
{
"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":
| Problem | Response |
|---|---|
| No payment method with that ID | 404 RESOURCE_NOT_FOUND, with param: "default_payment_method_id" |
| The card belongs to another customer | 400 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 archived | 409 ACTION_NOT_ALLOWED with reason unsupported_state |
| The customer is being deleted | 409 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:
| Charge | Uses the default |
|---|---|
New subscription with no payment_method_id | Yes, at creation. The subscription keeps that card afterward. |
Automatic invoice with no collection.payment_method_id | Yes, when the invoice is issued. The invoice keeps that card afterward. |
| Order payment | No. 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 "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 -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 -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"}
}'
{
"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_idmust be anactivecard withusage: "off_session". An unknown card returns404 RESOURCE_NOT_FOUNDwithresource_type: payment_method. Apending,failed, orarchivedcard returns409 ACTION_NOT_ALLOWEDwith the card reference and current status. A card that belongs to a different customer returns400 INVALID_REQUESTwith detail codeNOT_ALLOWED. A card the buyer saved in checkout returns400 INVALID_REQUESTwith detail codeNOT_ALLOWED.expected_outstanding_moneyis the total the customer approved. If tax, shipping, or a promotion changed the balance since, Flint returnsVERSION_CONFLICTwithout charging. Show the new total and ask again.- Order payments never fall back to the default card. Without
payment_source, the request fails with400 INVALID_REQUESTand detail codeREQUIREDonpayment_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 -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 gets400 INVALID_REQUESTwith detail codeNOT_ALLOWEDonpayment_source.customer_presence, as does anycredential_typeother thanpayment_method. - The card must be reusable. Charge an
activecard withusage: "off_session". A card the buyer saved in checkout returns409 ACTION_NOT_ALLOWEDwith reasonpayment_method_not_reusable. Cards, Apple Pay, and Google Pay can be charged this way; a saved bank account returns400 INVALID_REQUESTwith detail codeNOT_ALLOWED. - The bank can still refuse. A decline or a bank that insists on authentication ends the attempt
failed, with the payment intent inrequires_payment_methodandlast_payment_error.codeset,authentication_requiredin the second case. It never waits inrequires_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-Keyto 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 -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 -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 withACTION_NOT_ALLOWEDand reasonconfiguration_required. A card that is notactivefails withACTION_NOT_ALLOWEDwith reasonunsupported_state. - The charge runs moments after issue, not inside the issue response. Watch
invoice.paidfor success andinvoice_payment_attempt.failedfor 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_offsetsand fixed for the invoice when it is issued. To try again sooner, callPOST /v1/invoices/{invoice_id}/collectwith a newIdempotency-Key. - A different card can pay an outstanding amount. Pass another active saved card in
payment_method_idwhen callingcollect, 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 "https://api.withflintpay.com/v1/payment-methods?customer_id=cus_1kmn0aExample" \
-H "Authorization: Bearer YOUR_API_KEY"
{
"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 -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 -X DELETE https://api.withflintpay.com/v1/payment-methods/pm_1kmn0aExample \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Idempotency-Key: delete-card-ada-001"
{
"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 forstatus=archived. - Clears the customer's
default_payment_method_idif it pointed at this card. That advances the customer'sversionand sendscustomer.updated. An archived card is never the default, sois_defaultisfalsein 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 optionaltypefield as you would on the merchant route. GET /v1/me/payment-methods/{payment_method_id}takes noexpand, and answers 404 for a card that belongs to another customer. While a new card ispending, poll it untilstatusisactive.- Payment methods include
is_defaultbut neverfingerprint.
Build your own customer account walks through that page. Flint's hosted customer account includes card management with no code.
Webhooks#
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 number | While saving | One-click order payment | Automatic invoice |
|---|---|---|---|
4242 4242 4242 4242 | Saves. | Succeeds. | Succeeds. |
4000 0025 0000 3155 | 3D Secure challenge, then saves. | Challenges again with requires_action. | Succeeds with no challenge. |
4000 0027 6000 3184 | 3D Secure challenge, then saves. | Challenges with requires_action. | Declines because the bank requires authentication. |
4000 0000 0000 0341 | Saves. | Declines. | Declines, then retries on your schedule. |
4000 0000 0000 0002 | Refused. 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:
| Code | Result |
|---|---|
000000 | Wrong code. It counts as a wrong try. |
999999 | 503 SERVICE_UNAVAILABLE, as when texts can't be checked. |
| Any other six digits | Confirms the code. |
The same codes work for the code texted to a returning buyer. Emailed codes arrive as in live mode.
Errors#
Error handling covers the envelope these arrive in.
Common mistakes#
- Charging the card when the browser confirms. The card is
pendinguntilpayment_method.activatedarrives. - Treating
payment_method.failedas final. The customer can fix the card in the same form, and the same card becomesactive. - Assuming the first card becomes the default. Flint never sets a default on its own.
PATCHthe customer withdefault_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 withusage=off_session. - Leaving abandoned saves behind. A
pendingcard never expires, and it blocks a customer deletion request until you delete it.
Next steps#
- Declines and payment attempts: decline codes, 3D Secure, and resuming an attempt.
- 3D Secure: when the bank challenges a saved card, and what happens when nobody can answer.
- Invoicing: automatic collection, retry schedules, and attempt history.
- Subscription billing: charge a saved card on a recurring schedule.
- Customer deletion requests: delete a customer's cards and data on request.
- Payment Methods API reference: every field on every route.
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.