Card on file transactions (COF)

A card-on-file transaction is a transaction where a cardholder authorizes a merchant to store the cardholder’s payment details, and also authorizes that same merchant to bill the cardholder’s stored account.

Transactions are either initiated by a consumer, or by a merchant based on the instructions given to them by the consumer. It is possible for a merchant to initiate a transaction without consumer action.

Consumer-Initiated Transactions (CIT): where the consumer is present and provides their payment credentials. This can be through a terminal in-store, or online through a checkout experience. A consumer-initiated transaction contains proof (such as track data, chip data with cryptograms, cardholder verification methods, and online through the presence of Card Verification Value 2 (CVV2) or Verified by Visa (VBV) authentication data) that the cardholder was involved in the transaction.

Merchant-Initiated Transactions (MIT): a transaction that depends to a previous consumer-initiated transaction, but it is conducted without the consumer being present and without any additional cardholder validation performed. It’s a transaction based on a previous agreement between the consumer and the merchant for a recurring product or service or an automated billing or unscheduled transactions etc.

Don’t miss out the below examples with CardOnFile object used for the initial transaction and also for a subsequent one.

Card On File (COF) Transaction Types
Type Description
Installments Deferred payment. Always referring to an INDIVIDUAL purchase, the amount of the several transactions is fixed, and with a definite time interval.
Recurring Recurring payment. The amount of transactions can be fixed or variable, and with a defined time interval.
Reauthorization Normally before partial shipments. Also, when the client extends the stay in hotel / rental of the vehicle or when, having an estimated authorization, the final amount is requested (“settlement”).
Resubmission Original denied because of “balance”; only for certain sectors of activity (for more details check the regulations of the brands) and with a maximum number of days from the purchase. Relevant example:”Transport”.
Delayed Those that happen after the transaction for services rendered / used unknown at the beginning. (Minibar, vehicle damage, fines ….)
Incremental When additional services are incurred during the contract period.
No Show When the merchant charges services to which the owner committed, but then failed to comply with the agreed terms. Relevant example: unattended reservations at hotels without cancellation.
Other The rest of COF transactions that do not fit with any of the previous ones.
  • For an initial transaction from a subsequent payments chain the IsInitial parameter from CardOnFile object needs to be set to true.

    Request:

    POST https://securetest.smart2pay.com/v1/payments
Authorization: Basic MTAxMDpnYWJp

{
  "Payment": {
  "MerchantTransactionID": "s2ptest_11a",
  "Amount": "100",
  "Currency": "EUR",
  "ReturnURL": "http://demo.smart2pay.com/redirect.php",
  "Description": "Test Description",
  "StatementDescriptor1": "Dynamic Test Description",
  "Card": {
    "HolderName": "Test Person",
    "Number": "4012005162084369",
    "ExpirationMonth": "05",
    "ExpirationYear": "2021",
    "SecurityCode": "123",
    "RequireSecurityCode": true
    },
  "Capture": false,
  "GenerateCreditCardToken": false,
  "PaymentTokenLifetime": 10,
  "3DSecure": true,
  "DeviceInfo": {
    "BrowserAcceptHeader": "application/json, text/javascript, */*; q=0.01",
    "BrowserUserAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/76.0.3809.132 Safari/537.36",
    "BrowserJavaEnabled": false,
    "BrowserJavaScriptEnabled": true,
    "BrowserLanguage": "ro-RO",
    "BrowserColorDepth": "24",
    "BrowserScreenHeight": "1080",
    "BrowserScreenWidth": "1920",
    "BrowserTimeZone": "-180"
    },
  "CardOnFile":{
         "IsInitial": true,
         "TransactionType": "Recurring"
      },
  "Language": "ro-RO",
  "SkinID": 200
  }
}

    Response:

    HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8

{
    "Payment": {
        "ID": 1234,
        "ClientIP": null,
        "SkinID": 200,
        "Created": "20190828091954",
        "MerchantTransactionID": "s2ptest_11a",
        "OriginatorTransactionID": null,
        "Amount": "100",
        "Currency": "EUR",
        "CapturedAmount": "0",
        "ReturnURL": "http://demo.smart2pay.com/redirect.php",
        "Description": "Test Description",
        "StatementDescriptor": "Static Description",
        "MethodID": 6,
        "MethodOptionID": null,
        "SiteID": 1010,
        "NotificationDateTime": null,
        "Customer": null,
        "BillingAddress": null,
        "ShippingAddress": null,
        "Articles": null,
        "Card": {
            "HolderName": "Test Person",
            "Number": "VISA-4369",
            "ExpirationMonth": "05",
            "ExpirationYear": "2021",
            "IssuingBankCountry": null
        },
        "CreditCardToken": null,
        "Status": {
            "ID": 9,
            "Info": "Authorized",
            "Reasons": []
        },
        "MethodTransactionID": null,
        "AuthorizationCode": "591659",
        "PaymentTokenLifetime": 10,
        "Capture": false,
        "RedirectURL": null,
        "3DSecure": true,
        "DeviceInfo": {
            "BrowserAcceptHeader": "application/json, text/javascript, */*; q=0.01",
            "BrowserUserAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/76.0.3809.132 Safari/537.36",
            "BrowserJavaEnabled": false,
            "BrowserJavaScriptEnabled": true,
            "BrowserLanguage": "ro-RO",
            "BrowserColorDepth": "24",
            "BrowserScreenHeight": "1080",
            "BrowserScreenWidth": "19200",
            "BrowserTimeZone": "-180"
        },
        "ScaExemption": null,
        "CardOnFile": {
          "IsInitial": false,
          "TransactionType": "Recurring"
        },
        "Fraud": {
            "Status": "Accept",
            "Score": 31,
            "Reason": "No decision provided"
        }
    }
}
  • Transaction that depends to the previous consumer-initiated transaction. For a transaction from a subsequent payments chain the IsInitial parameter from CardOnFile object needs to be set to false.For subsequent payments always send in the request the InitialPaymentID parameter in the CardOnFile object.

    Request:

    POST https://securetest.smart2pay.com/v1/payments
Authorization: Basic MTAxMDpnYWJp

{
  "Payment": {
  "MerchantTransactionID": "s2ptest_12a",
  "Amount": "100",
  "Currency": "EUR",
  "ReturnURL": "http://demo.smart2pay.com/redirect.php",
  "Description": "Test Description",
  "StatementDescriptor1": "Dynamic Test Description",
  "Card": {
    "HolderName": "Test Person",
    "Number": "4012005162084369",
    "ExpirationMonth": "05",
    "ExpirationYear": "2021",
    "SecurityCode": "123",
    "RequireSecurityCode": true
    },
  "Capture": false,
  "GenerateCreditCardToken": false,
  "PaymentTokenLifetime": 10,
  "3DSecure": false,
  "DeviceInfo": {
    "BrowserAcceptHeader": "application/json, text/javascript, */*; q=0.01",
    "BrowserUserAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/76.0.3809.132 Safari/537.36",
    "BrowserJavaEnabled": false,
    "BrowserJavaScriptEnabled": true,
    "BrowserLanguage": "ro-RO",
    "BrowserColorDepth": "24",
    "BrowserScreenHeight": "1080",
    "BrowserScreenWidth": "1920",
    "BrowserTimeZone": "-180"
    },
  "ScaExemption": "MerchantInitiatedTransaction",
  "CardOnFile":{
    "IsInitial": false,
    "TransactionType": "Recurring",
    "InitialPaymentID": 1234        
    },
  "Language": "ro-RO",
  "SkinID": 200
  }
}

    Response:

    HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8

{
    "Payment": {
        "ID": 12345,
        "ClientIP": null,
        "SkinID": 200,
        "Created": "20190828091954",
        "MerchantTransactionID": "s2ptest_12a",
        "OriginatorTransactionID": null,
        "Amount": "100",
        "Currency": "EUR",
        "CapturedAmount": "0",
        "ReturnURL": "http://demo.smart2pay.com/redirect.php",
        "Description": "Test Description",
        "StatementDescriptor": "Static Description",
        "MethodID": 6,
        "MethodOptionID": null,
        "SiteID": 1010,
        "NotificationDateTime": null,
        "Customer": null,
        "BillingAddress": null,
        "ShippingAddress": null,
        "Articles": null,
        "Card": {
            "HolderName": "Test Person",
            "Number": "VISA-4369",
            "ExpirationMonth": "05",
            "ExpirationYear": "2021",
            "IssuingBankCountry": null
        },
        "CreditCardToken": null,
        "Status": {
            "ID": 9,
            "Info": "Authorized",
            "Reasons": []
        },
        "MethodTransactionID": null,
        "AuthorizationCode": "591659",
        "PaymentTokenLifetime": 10,
        "Capture": false,
        "RedirectURL": null,
        "3DSecure": false,
        "DeviceInfo": {
            "BrowserAcceptHeader": "application/json, text/javascript, */*; q=0.01",
            "BrowserUserAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/76.0.3809.132 Safari/537.36",
            "BrowserJavaEnabled": false,
            "BrowserJavaScriptEnabled": true,
            "BrowserLanguage": "ro-RO",
            "BrowserColorDepth": "24",
            "BrowserScreenHeight": "1080",
            "BrowserScreenWidth": "19200",
            "BrowserTimeZone": "-180"
        },
        "ScaExemption": "MerchantInitiatedTransaction",
        "CardOnFile": {
          "IsInitial": false,
          "TransactionType": "Recurring",
          "InitialPaymentID": 1234
          },
        "Fraud": {
            "Status": "Accept",
            "Score": 31,
            "Reason": "No decision provided"
        }
    }
}