Skip to main content
Recurring payments use both Customer‑Initiated (CIT) and Merchant‑Initiated (MIT) transactions. The overall flow is:
  1. Create a checkout session with the recurring_payment object.
  2. Perform a CIT to authorize and vault the customer’s payment method.
  3. Then use the returned vaulted_token for subsequent MIT charges.

​
Create checkout session for recurring payments

Before creating the transaction, you need to create the checkout session with the recurring_payment object populated in your checkout session request: Free trial: When offering a free trial period, set the root amount.value to 0 and include the trial_billing object as shown in the example below. The actual recurring charge is defined in regular_billing, which informs the customer of the amount they will be billed once the trial ends.

​
Customer Initiated Transaction (CIT)

The CIT is the initial transaction where the customer authorizes recurring payments, such as when they subscribe to a monthly service. This transaction requires customer interaction and generates a token for future MIT transactions. The following example shows a complete CIT request:
The key parameters for a CIT are:
  • vault_on_success: true: This parameter indicates this is a recurring payment setup and generates the token for future MIT transactions
  • customer_payer.id: Required together with vault_on_success. It must reference an existing customer (create it first with Create Customer). Without it the payment still succeeds but nothing is vaulted: the response carries an empty vaulted_token and no error
  • detail.wallet.stored_credentials.usage: "FIRST": Indicates this is the initial transaction in a recurring series
  • verify: When true, enables a card verification flow through the wallet (for example, a zero-dollar authorization) instead of a regular payment charge.
Set verify: true for free trial flows where amount is 0. Omit the field for standard paid CITs.
Do not place stored_credentials under detail.card on the CIT. It is not validated for a wallet payment, and the two-step Apple Pay flow does not carry it into the saved payment method, which leaves the record without stored-credential flags and without a network_transaction_id.
The vaulted_token is returned only in the CIT payment response. Wallet-vaulted instruments are intentionally not included in Retrieve Enrolled Payment Methods, so don’t rely on the customer’s payment-methods list to rediscover the token — store it (with any display metadata you need) when the CIT succeeds. A stored token can still be resolved individually with Retrieve Enrolled Payment Method by ID. See Stored Credentials.

​
Merchant Initiated Transaction (MIT)

MIT transactions are processed automatically for subsequent billing cycles using the token generated during the CIT. The following example shows a complete MIT request:
The key parameters for an MIT are:
  • vaulted_token: The token returned in the CIT response; used to charge the customer in subsequent billing cycles without requiring re-authorization
  • type: "CARD": The vaulted instrument is a card record. "APPLE_PAY" is also accepted together with a vaulted_token
  • detail.card.stored_credentials.usage: "USED": Indicates this is a subsequent transaction in a recurring series
  • workflow: "DIRECT": A server-to-server charge; no checkout session and no payment_token are needed
Monitor payment status through webhooks to handle edge cases and provide customer notifications.

​
Subscription management URL

For SDK recurring payments, you must provide a subscription management URL where customers can manage and cancel their subscription. Include it in your customer communications.