Skip to main content

Payment instruments

A payment instrument is any way a customer makes a digital payment: credit card, debit card, direct debit, payment service provider (PayPal and similar), or digital wallet (Apple Pay, Google Pay).

In PaymentsAI a payment instrument lives on a customer record and you reference it by paymentInstrumentId on subscriptions and transactions.

Tokenization​

Card data never reaches your server. The browser tokenizes the card details (typically with FramePay), and the resulting token is exchanged for a payment instrument attached to the customer. From there your code refers to the instrument by ID; the raw card data lives only inside PaymentsAI.

See Create customer with payment instrument for the full tutorial.

Lifecycle​

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

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 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 is expired or deactivated, it cannot be re-activated. The customer adds a new instrument instead.

Why this matters for subscriptions​

A subscription created against an inactive instrument returns:

  • status: "pending"
  • recentInvoicePaymentFormUrl: the hosted payment form URL

Your frontend redirects the customer to that URL. The hosted form processes the first payment, runs 3DS if needed, activates the instrument, and redirects the customer back. From then on, renewals on that instrument auto-charge without a redirect.

See Create a subscription for the full flow.