Card-on-File

Card-on-File

You can perform credential on file (COF) payments by adding standingInstruction set of parameters to the payment request.

A typical COF workflow consists of two phases:

  1. CIT payment request - Cardholder creates a recurring payment agreement along with the payment (or zero amount authorization) request with the merchant
  2. MIT payment request - Merchant initiates a recurring payment referencing the agreement created in CIT request.

CIT payment

During the initial payment, marked by the parameter standingInstruction.mode with the value INITIAL, standingInstruction.type with the value UNSCHEDULED or RECURRING or INSTALLMENT and standingInstruction.source with the value CIT, the cardholder is present. Therefore this initial request should contain additional parameters that authenticate the customer like card.cvv for card payments. Also, depending on the region, additional checks like 3D-Secure can be executed.

In COPYandPAY you get this behaviour out of the box, so all you have to do is to follow the COPYandPAY Integration guide and add to the /checkouts request in step 1 one of below set of parameters:

Exemptions can be used to reduce friction during cardholder authentication. The Payments Orchestration Platform offers a simple way to handle these use-cases.

  • As a passthrough each merchant can determine which exemption to use.
  • As an addition to transaction processing the Payments Orchestration Platform determines if an exemption is applicable and applies it to the payment transaction.
  • As a standalone service the Payments Orchestration Platform determines if an exemption is applicable and returns the suggested exemption flag.
  • standingInstruction.mode=INITIAL 
    •  
  • standingInstruction.type=UNSCHEDULED 
    •  
  • standingInstruction.source=CIT
  • standingInstruction.mode=INITIAL 
    •  
  • standingInstruction.type=RECURRING 
  • standingInstruction.recurringType=SUBSCRIPTION 
    •  
  • standingInstruction.source=CIT
  • standingInstruction.mode=INITIAL 
    •  
  • standingInstruction.type=RECURRING 
  • standingInstruction.recurringType=STANDING_ORDER 
    •  
  • standingInstruction.source=CIT
  • standingInstruction.mode=INITIAL 
    •  
  • standingInstruction.type=INSTALLMENT 
    •  
  • standingInstruction.source=CIT

    • Using the server-to-server integration, you either have the option to append the parameter standingInstruction to the initial /payments request that also stores the token like in this example:

    For some cases you might want to use an alternative approach: If the cardholder just registered his data without sending a payment at the same time you would have sent his payment directly to the /registrations endpoint as described here. In the same way as described above, the standingInstruction.mode=INITIAL, standingInstruction.type=UNSCHEDULED and standingInstruction.source=CIT parameters can be added to the request to indicate that this is the first in a series of recurring payments.

    You can find more details on the server-to-server option using either /payments or /registrations in the the tokenisation tutorial.

    MIT payment

    Any MIT payment request referencing the previously stored credentials has to have the parameter standingInstruction.mode with the value REPEATED, standingInstruction.type with the value UNSCHEDULED or RECURRING or INSTALLMENT, standingInstruction.source with the value MIT and standingInstruction.initialTransactionId with a value as ID received in the response of the initial CIT transaction. This flag not only indicates that the request is part of a series of payments on this account, but also tells the payment system that no user is present and therefore parameters like card.cvv or the 3D authentication data shouldn't be present. This fact in combination with the stored payment data of the registration greatly reduces the number of parameters of such a request: