Skip to main content
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.
  • 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.
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 for the rules, and Mastercard Transaction Link Identifier (TLID) for how the transaction_link_id is captured and which connectors support it.

​
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). Gr4vy stores both on the payment method, as scheme_transaction_id and transaction_link_id, and you can read them with 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.
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 in Flow.

​
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 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. 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. 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.
  • 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.