Authorization flags

Card networks and issuers mandate merchants to state each transaction type sent to them (i.e. first transaction of a subscription, subsequent payment of a subscription cycle, etc.). The way that each transaction is sent affects the chances of its success.

Each provider has its own way of defining these parameters, however, Payrails handles the further complexity for the merchants and manage it in a provider-agnostic way.

There are 2 main parameters to be determined when making a payment:

1. Payment Processing Type

Parameter used to define the payment type that the card details are used for within a particular payment.

Regular: a customer-initiated payment, that the user inserts the card details and has the option to store them or not.
CardOnFile: a customer-initiated payment using a stored instrument.
Subscription: a merchant-initiated payment using a stored instrument as part of a series of payments on a fixed schedule and with a fixed or variable amount.
Note: If you would like to send Subscription payments where the first payment was not processed by Payrails please align with the Payrails Payment Strategy team on designing the optimal implementation solution for your business needs.
UnscheduledCardOnFile: a merchant-initiated payment using a stored instrument that occurs on a not fixed schedule and/or without a set amount.

2. Instrument Future Usage

Parameter used to define in which payment flows you intend to use the stored or to be stored instrument in the future.
When the customer requests to store card details, an instrument will be created and an instrumentFutureUsage with the below values will be assigned to the instrument.

CardOnFile: The instrument will be used in payments that will be initiated by the customer.
Subscription: The instrument will be used in merchant-initiated payments on a fixed schedule and with a fixed or variable amount.
UnscheduledCardOnFile: The instrument will be used in the future for payments that will be initiated by the merchant in a not fixed schedule and with a fixed or flexible amount.

Instrument future usage value can be assigned to an instrument in one of the below ways.
These are in the priority order to override one another:

It is sent by the merchant while tokenizing an instrument by the backend or client-side encryption SDK.
(If #1 is not sent) It is assigned the default value in the workflow configuration.

Below you can find a table that summarizes the usage of flags:

Use case	Schedule	Amount	Initiation	Save instrument	Instrument Future Usage	Payment Processing Type
Pay once without save	-	Variable	Customer-initiated	No	-	`Regular`
Save card while paying	-	Variable	Customer-initiated	Yes	`CardOnFile`	`Regular`
Pay with a previously stored card	-	Variable	Customer-initiated	Yes	`CardOnFile`	`CardOnFile`
Store your card while paying for the first subscription of a series	-	Variable	Customer-initiated	Yes	`Subscription`	`Regular`
Subsequent payments of a subscription series	Fixed schedule	Fixed or variable	Merchant-initiated	Yes	`Subscription`	`Subscription`
Merchant-initiated Payments that are not part of a fixed schedule and amount Eg Auto Top Ups	Non-Fixed schedule	Fixed or variable	Merchant-initiated	Yes	`Unscheduled CardOnFile`	`Unscheduled CardOnFile`

To differentiate between the current payment and future ones, Payrails has 2 new enumerations on Payment and Instrument.

PaymentProcessingType is used to describe the payment flow that is being processed now (Enum: Regular, CardOnFile, Subscription, Unscheduled CardOnFile)

InstrumentFutureUsage is used to specify the payment flows that the stored instrument will be used for in the future (Enum: CardonFile, Subscription, Unscheduled CardOnFile).

If a customer already has an existing card used with a certain future usage (i.e. Subscription) but wants to make a different type of payment (i.e. single time pay with the same card used in subscription), you need to determine and send the paymentProcessingType in the execution.payment composition. Find an example here:

"paymentComposition": [
  {
    "amount":{
      "currency": "EUR",
      "value": "12.50"
    },
    "integrationType": "api",
    "paymentInstrumentId": "bc53d6d7-3ef5-4906-abf7-704a29ff593b",
    "paymentMethodCode": "card",
    "paymentProcessingType": "CardOnFile"
  }
]