Skip to main content

Payment instrument lifecycle

A payment instrument moves through a defined set of states. The state decides whether Payments AI can auto-charge it, meaning charge it as a merchant-initiated transaction, without the customer present. No state makes an instrument usable for a customer-present charge; those always run on a fresh token. See Card on file.

For what a payment instrument is and how it is created from a token, see Payment instruments.

Payment cards​

StateMeaningCan be auto-charged (MIT)?
inactive (or verification-needed)Card is registered but has not completed a payment.No
activeOne or more payments have succeeded on the card.Yes
expiredThe card's expiration date has been reached.No
deactivatedThe card has been manually deactivated.No

Alternative payment methods​

For bank accounts, PayPal, and similar:

StateMeaningCan be auto-charged (MIT)?
inactive (or verification-needed)Method is registered but has not completed a payment.No
activeOne or more payments have succeeded on the method.Yes
deactivatedThe method has been manually deactivated.No

Alternative methods do not have an expired state — they do not carry an expiration date.

Transitions​

  • inactive → active: a transaction succeeds against the instrument. Payments AI owns this transition; no API endpoint flips it directly. For subscription instruments seeded by attach, that first successful transaction happens on the hosted payment form.
  • active → expired (cards only): the card's expiration date is reached.
  • active → deactivated: manual deactivation.

Once an instrument moves to expired or deactivated, it cannot be re-activated. The customer adds a new instrument.

State diagram​

Why it matters for subscriptions​

When you create a subscription against an inactive instrument, Payments AI does not auto-charge it. Instead:

  1. The create response returns status: "pending" and a recentInvoicePaymentFormUrl.
  2. Your frontend redirects the customer to that URL.
  3. The customer completes the first payment on the hosted form. The form handles 3DS internally and activates the instrument on success.
  4. From then on the subscription is active and renewals auto-charge without a redirect.

When you create a subscription against an active instrument (a returning customer with a previously used card), the first charge happens immediately. The subscription goes straight to active — no pending, no redirect.

Activating an attach-seeded subscription instrument​

An instrument created by the attach call starts inactive. It becomes active when a payment actually succeeds on it. In the subscription flow, that is the payment the customer completes on the hosted payment form.

There is no merchant-side shortcut around that successful payment. In particular:

  • Calling the transactions endpoint with an invoiceId for a pending subscription invoice does not activate the instrument.
  • There is no endpoint that pays a customer invoice directly from the merchant side.
  • The instrument does not self-activate over time.

See Subscription troubleshooting for the patterns to avoid.

An instrument created by an approved customer-initiated transaction never sits in this state: the CIT is itself the successful payment, so the instrument it returns is already usable for merchant-initiated charges with no hosted-form step. See Card on file.