Skip to main content

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.

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 performing an subsequent MIT transaction without storing the card data in the vault, it’s recommended to provide the previous_scheme_transaction_id where possible. This should represent the scheme_transaction_id returned in the initial transaction.If you use a stored payment method, this logic is handled for you automatically.

​
Best practices

Please follow the following best practices when creating recurring payments.
  • When created 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.
  • When performing a subsequent MIT transaction without storing the card data in the vault, it’s recommended to provide the previous_scheme_transaction_id where possible. This should represent the scheme_transaction_id returned in the initial transaction. If you use a stored payment method, this logic is handled for you automatically.