Credentials On File(Cards API)
Overview
Credentials-On-File, also known as Card-On-File or simply COF payments, include subsequent merchant-initiated (MIT) billing payment plans, such as subscriptions and membership fees, or customer-initiated transactions (CIT) that are using an already saved payment information for the processing. The Credentials-On-File are often referred to as recurring payments.
A Credentials-On-File payment can be for fixed, regular intervals with predefined amount or for an unknown date with variable amount, where the amount cannot be higher than the one for which the cardholder was originally authenticated. In all instances where credentials-on-file payments are set up, the cardholder must have given their explicit consent for the payment information storing and repeated rebilling.
Credentials-On-File payments are supported via the Paysafe Customer Vault API and Card Payments API. Merchants can use the Customer Vault API to create a customer profile and link a card or payment method to the profile. The Paysafe platform returns a payment token that can then be included in subsequent payment authorization and settlement requests, without requiring the merchant to collect card details again from the cardholder.
Supported Credentials-On-File payments
Paysafe supports the following Credentials-On-File payments:
| Transaction type | authenticationPurpose via the Paysafe 3D Secure REST API | Initial and Subsequent authorization in object ‘storedCredential’ -> field ‘type’ | Description | Examples |
| Cardholder-Initiated Credentials-On-File (CIT COF) | PAYMENT_TRANSACTION | ADHOC | Cardholder payment information is stored from a previous transaction, but the cardholders themselves are the ones who initiate the payment. Depending on the region or merchant preferences, the transaction is often authenticated with 3D Secure. | Customer that saved their card for subsequent one-click payments with an online store. |
| Merchant-Initiated Unscheduled Credentials-On-File (MIT UCOF) | PAYMENT_TRANSACTION | TOPUP | Merchant-initiated payment that doesn’t occur on a predefined rebilling date. The amount can vary but never be above the one for which the cardholder was originally authenticated. If the amount is higher than the originally authenticated one, a new payment plan must be established. | Account top-up transaction |
| Merchant-Initiated Credentials-On-File (MIT COF) | RECURRING_TRANSACTION | RECURRING | Merchant-initiated payment for fixed, regular rebilling date and predefined amount. | Utility payments, streaming service subscription |
When setting up a payment plan with your customer, you must provide the customer with the following details:
- The frequency of the recurring transactions
- The period over which the recurring payments will be taken
The above is not needed if the card is only being stored for future payments that will only be initiated by the cardholder themselves.
- If your customers are based in UK or EEA - The card schemes require that the initial transaction that establishes a payment plan mush have passed a challenged 3D secure authentication.
- If your customers are based in USA or Canada - Although strong customer authentication is not mandatory in USA and Canada, as it is in EU/UK, its usage can improve the authorization rate of the subsequent merchant-initiated payments.
Key Notes
It is important to remember that the subsequent transactions must always be processed with the same Merchant Account IDs that processed the initial transactions, otherwise the transaction will be declined.
Payment plans should never be established with non-reloadable prepaid cards (ex: gift card).
If the initial cardholder-initiated transaction is failed, no payment plan was established and subsequent rebills cannot be done unless another successful cardholder-initiated transaction occurs.
If a subsequent merchant-initiated transaction fails multiple times, the merchant may need to establish a new payment plan with new successful cardholder-initiated transaction.
For RECURRING, the amount in the initial and the subsequent authorizations must always be equal to the amount for which the cardholder was authenticated.
For TOPUP, the subsequent authorization amount must never be higher than the amount for which the cardholder was authenticated during the payment plan establishment.
The storedCredential type of the subsequent transaction must always match the type of the initial transaction.
Paysafe has developed the Payment Scheduler - a solution that allows you to integrate subscriptions, memberships, repeat services and more into your website, and then manage their recurring payment plans and customer subscriptions within Paysafe’s payment platform.
Which flow is suitable for my business?
If your business model is based on rebilling your customers on their behalf (without them being present at checkout) with transactions that are going to occur on fixed, regular intervals with predefined amount (Example: $15 rebilled on the first day of the month), you need to use the Merchant-Initiated Credentials-On-File (MIT COF) flow with type RECURRING in the storedCredential object of the authorization request and authentication purpose RECURRING_TRANSACTION in the authentication request.
If your business model is based on rebilling your customers on their behalf (without them being present at checkout) with transactions that are going to occur on an unknown date with variable amount (but not higher than the one for which the cardholder was originally authenticated), you need to use the Merchant-Initiated Unscheduled Credentials-On-File (MIT UCOF) flow with type TOPUP in the storedCredential object of the authorization request and authentication purpose PAYMENT_TRANSACTION in the authentication request.
If your business model is based on processing transactions from returning customers where the customer is initiating the payment via stored payment information, you need to use the Cardholder-Initiated Credentials-On-File (CIT COF) flow with type ADHOC in the storedCredential object of the authorization request and authentication purpose PAYMENT_TRANSACTION in the authentication request.
What is an Initial Transaction ID and why it is important?
An Initial Transaction ID is sent to you when you set up a recurring payment plan with a cardholder with their first successful payment. This is the ID you need to provide for all subsequent Merchant-Initiated Transaction (MIT) payments associated with this payment plan. Please note that different payment plans associated with an existing cardholder will have different Initial Transaction IDs.
In the Paysafe processing environment, the Initial Transaction ID is a Paysafe Transaction ID. The added security of an Initial Transaction ID provides a better customer and merchant experience, leads to increased transaction approval rate and revenue retention.
Is the Card Verification Value (CVV/CVV2/CVD) Required?
Under PSI DSS requirements, the Card Verification Value (CVV/CVV2/CVD) cannot be stored on merchant or payment service provider premises. Depending on the type of transaction, you may need to obtain this value from the customer and include it in your authorization request. For example:
- Regular/Cardholder-Initiated Credentials-On-File payment (e.g., customer returning to your website for an additional purchase) - You should obtain the CVV from the customer and include it together with the card details or the token obtained from the Customer Vault.
- Transaction flagged as subsequent recurring payment – Regular or subscription payments can be flagged by including the storedCredential object and setting it to RECURRING or TOPUP type in your authorization request. If you set the occurrence value to INITIAL you may need to obtain the customer's CVV before processing the request. If the occurrence is SUBSEQUENT then you do not need to provide the CVV.
While providing the CVV value with the initial request to establish a payment plan may not always be necessary, including it can enhance the likelihood of the transaction being approved, especially if the business vertical is considered a high-risk one.