Credentials on File2

The Credentials on File (CoF) interface allows you store the cardholder's card data to make a payment later. CoF used to store card details to streamline the checkout process for returning customers. This can be used for one-click payments, pay-per-use services, or any recurring payment that does not follow a fixed schedule.

If you are PCI-Compliant at Level 1/Level 2, you can store card details by yourself. Otherwise, you must store card details using a payment services provider.

🚧

Please reach out your Client Relations manager, if you want to use CoF.

In order to initiate a cardholder-absent transaction, the following stages have to be followed.

Step 1. Initiate a cardholder present transaction

Initiate a cardholder present transaction with explicit cardholder consent. The first in the series transaction needs to go through 3DS as per card scheme guidelines. This is enforced for EEA countries, but we recommend using it globally, if possible.

For such a transaction, besides the Authorization2 request parameters or hosted payment page request parameter the following fields need to be included:

• token_id: INIT
• cof: cit, mit.

check with Ala if cit mit is needed for initiation

! HPP use auth !

Request example:

merchantid=gateway_test&orderid=Payabl-Test&amount=14.99&currency=EUR&payment_method=1&language=en&customerip=93.109.250.238&
[email protected]&firstname=John&lastname=Doe&zip=3035&street=Olympion&house=23&city=Limassol&country=CYP&ccn=4012001036298889&
exp_month=07&exp_year=2028&cvc_code=924&cardholder_name=John Doe&param_3d=try3d&url_return=https://yourshop.example/thank_you&
notification_url=https://yourshop.example/notification&token_id=INIT&signature=bb1fcdda5c71ba5e8feed4236900f0297ba3dc44

COPY from recurring

Subsequent card on file transactions can then be of two forms:

• Cardholder Initiated Transaction (CIT): In this type of transaction the cardholder is actively participating in the transaction. Example: During quick checkout where the customer is shown the masked PAN and required to only enter the cvc_code. Another example is when a cardholder uses the one-click pay button. A cardholder would not need to enter a cvc_code. In the last case, the parameter ‘cof=cit’ is recommended to be used to properly flag the transaction as CIT.
• Merchant Initiation Transaction (MIT): Merchant initiates the transaction without the cardholder needing to be present. Example usage is when the customer is instructed on an automatic balance top-up.

The below you can find examples of transactions with a different flow and how to handle them properly.

🚧

CVV/CVC is mandatory for further CoF transactions by default. If you want to disable this feature, please contact your Client Relations manager.

Step 2a: Subscription payment with CVV/CVC present

You need to send additional parameters in your request to payabl when the customer initiates a transaction with CVC code present.

• cvc_code: Card validation code.
• token_id: The initial transaction id from step 1.

Request example

merchantid=gateway_test&orderid=Payabl-Test&amount=14.99&currency=EUR&payment_method=1&language=en&customerip=93.109.250.238&
[email protected]&firstname=John&lastname=Doe&zip=3035&street=Olympion&house=23&city=Limassol&country=CYP&token_id=105101094&
cvc_code=924&url_return=https://yourshop.example/thank_you&notification_url=https://yourshop.example/notification&
signature=e3f357688bb15b7295fb29c717967deeb24a8ae1

Response example

transactionid=105101125&transid=105101125&status=0&errormessage=&errmsg=&amount=14.99&
price=14.99&currency=EUR&orderid=Payabl-Test&user_id=466838

Step 2b: CoF with CIT parameter

You need to send additional parameters in your request to payabl. when the customer initiates a transaction with CVC code present.

• cof: cit.
• token_id: The initial transaction id from step 1.

Request example

merchantid=gateway_test&orderid=Payabl-Test&amount=14.99&currency=EUR&payment_method=1&language=en&customerip=93.109.250.238&
[email protected]&firstname=John&lastname=Doe&zip=3035&street=Olympion&house=23&city=Limassol&country=CYP&token_id=105101094&
cof=cit&url_return=http://yourshop.example/thank_you&notification_url=http://yourshop.example/notification&
signature=156c429b76f3a44e44f5f5853513d0b16abf5c5c

Response example

transactionid=105101126&transid=105101126&status=0&errormessage=&errmsg=&amount=14.99&
price=14.99&currency=EUR&orderid=Payabl-Test&user_id=466838

Step 2c: CoF with MIT parameter

You need to send additional parameters in your request to payabl when the customer initiates a transaction with CVC code present.

• cof: mit.
• token_id: The initial transaction id from step 1.

Request example

merchantid=gateway_test&orderid=Payabl-Test&amount=14.99&currency=EUR&payment_method=1&language=en&customerip=93.109.250.238&
[email protected]&firstname=John&lastname=Doe&zip=3035&street=Olympion&house=23&city=Limassol&country=CYP&token_id=105101094&
cof=mit&url_return=https://yourshop.example/thank_you&notification_url=https://yourshop.example/notification&
signature=63bb010415893785811d89067e07b515f97195c8

Response example

transactionid=105101127&transid=105101127&status=0&errormessage=&errmsg=&amount=14.99&
price=14.99&currency=EUR&orderid=Payabl-Test&user_id=466838

CoF migration

Now you can migrate your CoF subscriptions from the previous acquirer to payabl..
To move your CoF payment you need to request a few parameters from your current/previous provider + cardholder card details. This will allow you to continue payments without cardholder participation and passing 3DS again.

You need to send a transaction with token_id = INIT (see previous chapter) to /payment_authorize link with additional parameters in request below:

• Amount: with 0.00 value for only migration
• Amount: > 0.00 value for migration and authorization

When payabl. receives the token_id = INIT for the initial transaction and validates the request. If all fields present with correct values, payable. will register an initial transaction that will not be sent to any scheme. All the provided data will be stored for future recurring transactions.
With this, you will need to retrieve our transaction_id and use it for subsequent CoF transactions by now sending token_id = transaction_id and indication MIT or CIT.

🚧

Please contact your Client Relations manager or Technical support team to enable CoF migration function for your account

---

Our Technical Support team is there to help you:
Email: [email protected]
Available Monday – Friday between 09:00 and 17:00 CET/CEST