Skip to main content

Payment instrument lifecycle

A payment instrument moves through a defined set of states. The state decides whether PaymentsAI can auto-charge it.

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

Payment cards​

StateMeaningCan be auto-charged?
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?
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. PaymentsAI owns this transition; no API endpoint flips it directly.
  • 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, PaymentsAI 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.

What you cannot do programmatically​

There is no supported way to move inactive → active without a customer-driven payment on the hosted form. 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.