> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gr4vy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Recurring payments

> Flag recurring card payments correctly, and learn how Gr4vy stores and sends scheme transaction IDs for stored cards.

To support recurring billing some connections (mainly card processors)
require transactions to be marked accordingly to properly indicate if a transaction
is part of a recurring sequence of transactions. It is important to set these
indicators correctly to ensure a successful authorization for subsequent transactions.

Recurring transactions can generally be categorized as scheduled payments,
unscheduled payments, subscriptions, or installments.

## Recurring payment flags

To facilitate recurring payments, three properties are supported that can be set
[when creating a new card transaction](/reference/transactions/new-transaction).

* `payment_source` - The source of the transaction. This defaults to `ecommerce` and
  can be set to `recurring`, `installment`, or `card_on_file`.
* `merchant_initiated` - Indicates whether the transaction was initiated by the
  merchant (`true`) or if the customer was present (`false`).
* `is_subsequent_payment` - Indicates whether the transaction represents a
  subsequent payment. Please note this flag is only compatible when the
  `payment_source` is set to `recurring`, `installment`, or `card_on_file` and
  is ignored for other values or if `payment_source` is not present.

These 3 properties are automatically mapped to your downstream payment
service's properties, where they apply. Currently, these mostly only apply to card
processors.

<Warning>
  When you charge card details that aren't stored with Gr4vy, provide `previous_scheme_transaction_id` and
  `previous_transaction_link_id` on each subsequent merchant-initiated transaction (MIT) where possible. Use the
  `scheme_transaction_id` and `transaction_link_id` returned on the customer-initiated transaction that set up the series.

  If you use a stored payment method, Gr4vy keeps these IDs on the payment method and sends them for you. See
  [Scheme transaction IDs on stored payment methods](#scheme-transaction-ids-on-stored-payment-methods) for the rules,
  and [Mastercard Transaction Link Identifier (TLID)](/guides/features/recurring-payments/mastercard-tlid) for how the
  `transaction_link_id` is captured and which connectors support it.
</Warning>

## Scheme transaction IDs on stored payment methods

Card schemes link a merchant-initiated transaction back to the customer-initiated transaction that set up the
stored credential. The link is the scheme transaction ID, also known as the Visa Transaction Identifier or
Mastercard trace ID, and for Mastercard also the [Transaction Link Identifier (TLID)](/guides/features/recurring-payments/mastercard-tlid).
Gr4vy stores both on the payment method, as `scheme_transaction_id` and `transaction_link_id`, and you can read them
with [Get payment method](/reference/payment-methods/get-payment-method).

### Which transactions store an ID

Gr4vy saves the IDs that the payment service returns on a successful transaction, following these rules.

* Only transactions with `payment_source` set to `recurring`, `installment`, or `card_on_file` store an ID.
  A transaction with any other `payment_source`, such as `ecommerce` or `moto`, stores nothing, even when it
  stores the card with `store: true`.
* A customer-initiated transaction (`merchant_initiated: false`) replaces the stored IDs with the ones it returns.
* A merchant-initiated transaction only stores an ID when the payment method doesn't have one yet.
* When the payment service doesn't return an ID, the stored value stays as it is.

After the transaction that sets up a series, check `scheme_transaction_id` on the transaction to confirm that the
payment service returned one.

<Note>
  A payment service may not return a scheme transaction ID for a payment processed on a domestic co-badged network.
  A card stored with such a payment has no reference for later merchant-initiated transactions. See
  [co-badged routing](/guides/dashboard/flow/card-transactions#message-transformations) in Flow.
</Note>

### When Gr4vy sends the stored ID

Gr4vy sends the stored IDs as the previous scheme transaction ID and previous transaction link ID on:

* Every merchant-initiated transaction with the payment method.
* Subsequent card-on-file customer-initiated transactions, with `payment_source` set to `card_on_file`,
  `merchant_initiated` set to `false`, and `is_subsequent_payment` set to `true`.

A `previous_scheme_transaction_id` or `previous_transaction_link_id` in the transaction request takes precedence
over the stored value. Gr4vy doesn't save these request values on the payment method.

An ID belongs to the card network of the transaction that returned it. Gr4vy leaves the scheme transaction ID out of
an attempt that's processed on a different network, with one exception for domestic co-badged networks. See
[co-badged routing](/guides/dashboard/flow/card-transactions#message-transformations) in Flow.

### Keep a specific scheme transaction ID

Because every qualifying customer-initiated transaction replaces the stored IDs, the payment method holds the IDs
from the most recent one. To reference a specific transaction instead, such as the first one in a series, use one
of these options.

* Pass its IDs as `previous_scheme_transaction_id` and `previous_transaction_link_id` on each merchant-initiated
  transaction.
* Set `scheme_transaction_id` and `transaction_link_id` on the payment method with
  [Update payment method](/reference/payment-methods/update-payment-method). A later customer-initiated transaction
  with `payment_source` set to `recurring`, `installment`, or `card_on_file` replaces these values again.

## Best practices

Follow these best practices when creating recurring payments.

* When creating a customer-initiated transaction (CIT), with
  `merchant_initiated=false`, providing the `security_code` (CVV) is highly
  recommended. Not doing so could result in declined transactions.
* Before creating a merchant-initiated transaction (MIT), with
  `merchant_initiated=true`, it's highly recommended to make an initial CIT first so the
  customer gives their authorization. Any subsequent transaction is then identified as being authorized by this first transaction.
* Before each merchant-initiated transaction with a stored payment method, check the payment method's `status` with
  [Get payment method](/reference/payment-methods/get-payment-method). Only charge payment methods with the status
  `succeeded`. A transaction with a payment method in any other status fails with a validation error. See
  [payment method statuses](/guides/api/statuses/payment-methods).
* When performing a subsequent MIT transaction without storing the card data in the vault, provide the
  `previous_scheme_transaction_id` and `previous_transaction_link_id` where possible. With a stored payment method,
  Gr4vy sends these for you, as described in
  [Scheme transaction IDs on stored payment methods](#scheme-transaction-ids-on-stored-payment-methods).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.