Card on File

Use the Card on File (CoF) feature for processing recurring payments, subscriptions, and one-click transactions. This helps merchants comply with Visa and Mastercard regulations and improves approval rates.

Card on File (CoF) is a feature that enables merchants to process transactions using customer card information for subsequent purchases. This capability facilitates various transaction types depending on the entity that initiates the transaction, be it the customer or the merchant.

Overview

Card networks require merchants to include specific identifiers when using stored card credentials in the payment request. Card on File helps establish trust, confirming that customers have authorized storing their card details and subsequent payments.

Card on File transactions can be categorized into three types:

Note

Please check with your account manager for Card on File availability per country.

CardOnFile Object

Request Fields

Parameter	Type	Mandatory?	Description
`CardOnFile`	`object`	No	Contains information about the Card on File transaction.
`CardOnFile` → `TransactionType`	`string`	Yes	Specifies the type of Card on File transaction. Possible values: `"CIT"`, `"FIT"`, `"MIT"`.
`CardOnFile` → `NetworkTransactionId`	`string`	No	Identifier for transaction tracking, can be either a network transaction or subscription agreement.

Note: The CardOnFile object is optional. Transactions will be processed normally if this object is not included in the request. However, including it helps improve approval rates by properly identifying the transaction type and complying with card network requirements.

Transaction Types

	CIT	FIT	MIT
Initiator	Customer	Customer	Merchant
Use Cases	• One-click payments • Customer portal purchases • Manual subscription renewals	• Starting a subscription • Setting up recurring donations	• Subscription renewals • Recurring membership fees • Scheduled installment charges
Authentication	Authentication is recommended. You can pass 3DS results in the request	Authentication is recommended. You can pass 3DS results in the request	No additional authentication needed after FIT. Previous authentication data can be referenced using NetworkTransactionId
Authentication TransactionID	Optional	Optional, but the 3DS `TransactionId` from response should be stored	Optional (`TransactionId` from original FIT)

Request Example for CIT (Customer Initiated Transaction)

{
    "CardData": {
        "CardHolderName": "João Silva",
        "Pan": "4507990000004905",
        "Expiration": "08/30",
        "Email": "joao.silva@example.com",
        "Document": "86461657055"
    },
    "UniqueID": "CIT-2023-001",
    "Capture": true,
    "TargetCountryISO": "BR",
    "Currency": "BRL",
    "Amount": 25000,
    "Order": "ORD-2023-001",
    "Description": "One-click purchase",
    "Customer": {
        "FirstName": "João",
        "LastName": "Silva",
        "ReferenceCode": "JS-001",
        "PhoneNumber": "11987654321",
        "DocumentNumber": "86461657055",
        "DocumentType": "CPF.BR",
        "Email": "joao.silva@example.com",
        "Address": {
            "Country": "BR",
            "City": "São Paulo",
            "State": "SP",
            "PostalCode": "01310-200",
            "AddressDetail": "Avenida Paulista 1000"
        }
    },
    "CardOnFile": {
        "TransactionType": "CIT"
    }
}

Request Example for FIT (First Initial Transaction)

{
    "CardData": {
        "CardHolderName": "João Silva",
        "Pan": "4507990000004905",
        "CVV": "123",
        "Expiration": "08/30",
        "Email": "joao.silva@example.com",
        "Document": "86461657055"
    },
    "UniqueID": "FIT-2023-001",
    "Capture": true,
    "TargetCountryISO": "BR",
    "Currency": "BRL",
    "Amount": 25000,
    "Order": "ORD-2023-002",
    "Description": "Subscription initial payment",
    "Customer": {
        "FirstName": "João",
        "LastName": "Silva",
        "ReferenceCode": "JS-001",
        "PhoneNumber": "11987654321",
        "DocumentNumber": "86461657055",
        "DocumentType": "CPF.BR",
        "Email": "joao.silva@example.com",
        "Address": {
            "Country": "BR",
            "City": "São Paulo",
            "State": "SP",
            "PostalCode": "01310-200",
            "AddressDetail": "Avenida Paulista 1000"
        }
    },
    "ThreeDSAuthMethod": "EXTERNAL",
    "ThreeDS": {
        "Eci": "05",
        "Xid": "MDAwMDAwMDAwMDAwMDAwMDAwMDE=",
        "Cavv": "kBNcxqbmcXUxhAE1yKRHAAAAAAA=",
        "Version": "2.2.0",
        "TransactionId": "97267598-FAE6-48F2-8083-C23433990FBC"
    },
    "CardOnFile": {
        "TransactionType": "FIT"
    }
}

Request Example for MIT (Merchant Initiated Transaction)

{
    "CardData": {
        "CardHolderName": "João Silva",
        "Pan": "4507990000004905",
        "Expiration": "08/30",
        "Email": "joao.silva@example.com",
        "Document": "86461657055"
    },
    "UniqueID": "MIT-2023-001",
    "Capture": true,
    "TargetCountryISO": "BR",
    "Currency": "BRL",
    "Amount": 25000,
    "Order": "ORD-2023-003",
    "Description": "Subscription renewal payment",
    "Customer": {
        "FirstName": "João",
        "LastName": "Silva",
        "ReferenceCode": "JS-001",
        "PhoneNumber": "11987654321",
        "DocumentNumber": "86461657055",
        "DocumentType": "CPF.BR",
        "Email": "joao.silva@example.com",
        "Address": {
            "Country": "BR",
            "City": "São Paulo",
            "State": "SP",
            "PostalCode": "01310-200",
            "AddressDetail": "Avenida Paulista 1000"
        }
    },
    "CardOnFile": {
        "TransactionType": "MIT",
        "NetworkTransactionId": "97267598-FAE6-48F2-8083-C23433990FBC"
    }
}

The response follows the standard response format. See Create a Purchase for details.

Last modified December 20, 2024