COF Integration Types

COF Contract

Within the Payengine all credential-on-file related information will be assigned to an existing payment instrument of the corresponding card in the cofContract object.

The cofContract object consists of the following parameters.

The object can be passed either as part of a card check after payment credentials have been tokenized or as part of an order request, e.g. in the preauth or debit request.

A card payment instrument in the Payengine could have multiple assigned cofContracts.

The most typical use case would be that only one cofContract is assigned to a payment instrument. In this case the Payengine will automatically trace initial and subsequent transactions. For recurring payments the Payengine will also automatically extract the card scheme transaction identifier for the initial recurring payment and forward it as part of the subsequent transactions.

In case a merchant would like to use the same payment instrument for multiple cofContracts the id would always be a required input parameter for each payment transaction!

{
    "paymentInstrumentId": "111",
    "type": "creditcard",
    ...

API - Card Check

POST /payment-instruments/{paymentInstrumentId}/card-check

This service can be used to initiate a card check which will results in a 0,00€ authorization.

• If cofContract object is passed - the card check authorization will trigger an initial credential-on-file transaction, which can also be linked to a 3DS authentication. This option can be used in case the merchant only wants to store the payment credentials and at this point no real payment should be initiated.
• If cofContractobject is not passed (POST with empty request body) - a simple card check will be triggered with 0 amount via MOTO channel and will return the status of the card.

Once a 3DS autentication has been initiated the returned threeDsAuthenticationId should be provided as an input in order to link the authentication to the initial card check authorization.

Supported brands:

• Visa
• Mastercard
• AMEX
• JCB
• Diners/Discover

{
                "threeDsAuthenticationId": "threedsauthentication_123",
                "cofContract": {
                  "type": "UNSCHEDULED",

{
                "id": "cardcheck_123",
                "createdAt": 1561555495930,
                "modifiedAt": 1561555495977,

API - Order (CoF)

The cofContract information can be passed as part of the order request (preauth or debit).

For initial transactions the type has to be provided.

{
    ...
    "payment": {
      ...

The Payengine will assign the cofContract to the payment instrument and log the usage including the required scheme identifiers returned for the initial transaction.

Each cofContract will generate a unique Payengine identifier which is returned in the order response in the meta object.

In case multiple cofContract are assigned to a payment instrument a corresponding list will be returned as part of the paymentInstrument attributes.

{
    ...
    "paymentInstrument": {
      "paymentInstrumentId": "111",

Once a subsequent transaction will be initiated the id of the cofContract should be provided in the request.

{
    ...
    "payment": {
      ...

API - Widget Solutions

Affected widget solutions:

• Modal Widget
• Inline Widget
• Widget as a Bridge

In order to flag the credential-on-file usage in the Payengine widget solutions a new cofContract.type has to be provided as part of the optionalFields.

Supported values:

• ONECLICK
• SCHEDULED
• UNSCHEDULED

var optionalParameters = {
    ...,
    "optionalFields": {
      ...,

Whenever a cofContract.type will be provided the widget will show a new additional checkbox to "Store payment data for future payments".

This checkbox should be used by the cardholder to give his consent for storing the payment credentials for future payments.

A sample from the Modal Widget can be found below.

Modal & Inline Widget Validations

For the Modal and Inline Widget the following validations will be done based on the checkbox.

Widget as a Bridge Validations

For the Widget as a bridget the following validations will be done based on the checkbox.

Type: ONECLICK, SCHEDULED, UNSCHEDULED

Checkbox Validation: If checkbox is checked the checkout can proceed and the cofContract should be assigned to the payment instrument by the integrator either via card check or order. If checkbox is NOT checked - the PAY button will be inactive. In case the integrator implemented an own button an error would be returned instead.

JavaScript SDK (JS Bridge)

In order to assign the cofContract to a payment instrument and initiate a card check a new function cardCheck(paymentInstrumentId, cofType, channel, authenticationId, callback) is available in the JavaScript SDK (JS Bridge).

function callback(error, result) {...};
  var cofType = 'SCHEDULED';
  var channel = 'ECOM';
  window.PayEngine.cardCheck(paymentInstrumentId, cofType, channel, authenticationId, callback);