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 we support three properties 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 will be ignored for other values or if payment_source is not present.

We will automatically map these 3 properties to your downstream payment service’s properties, where they apply. Currently, these mostly only apply to card processors.

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 will then be identified as being authorized by this first transaction.
  • When doing an MIT transaction, it’s recommended to provide the previous_scheme_transaction_id where possible. This should represent a previous CIT to relate to. If you use a stored payment method we will attempt to use the right ID from a previous transaction with the same payment method.