Credentials on File

A Credential on File (CoF) transaction is when 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 service provider.

🚧
Please reach our Risk department, 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 if possible globally.

For such a transaction, besides the authorization request parameters or hosted payment page request parameter the following field needs to be included:

ccn: The ccn field contains the customer's credit card number. The payment gateway is capable of processing any credit card type. The credit card types the merchant can process will depend on the contract with their bank.
exp_month
exp_year
cvc_code
cardholder_name
token_id: INIT
cof: cit, mit.

Request example

merchantid=gateway_test&amount=1.23&currency=USD&orderid=PowerCash21-Test&language=en&
gender=M&lastname=Mann&street=An+der+Welle+4&zip=60322&city=Frankfurt&country=DEU&customerid=&
salutation=Herr&title=&firstname=Muster&company=PowerCash21&birthday=07071971&house=19&postbox=&
state=HE&[email protected]&phone=00496975938501&fax=&mobile=&customerip=127.0.0.1&
custom1=123456&payment_method=1&ccn=4242424242424242&
cvc_code=123&cardholder_name=Gateway+Test&exp_month=12&exp_year=2020&
token_id=INIT&signature=8d35d5971d9e47bb89b2a34cafd1604690492e15

Response example

transactionid=80780000&transid=80780000&status=0&errormessage=&
errmsg=&amount=1.23&price=1.23&currency=USD&orderid=PowerCash21-Test&
user_id=10088265

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 onboarding or account manager.

Step 2a: CIT with cvc_code 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

POST data: 
merchantid=gateway_test&amount=1.23&currency=USD&orderid=PowerCash21-Test&language=en&
gender=M&lastname=Mann&street=An+der+Welle+4&zip=60322&city=Frankfurt&country=DEU&
customerid=&salutation=Herr&title=&firstname=Muster&company=PowerCash21&birthday=07071971&
house=19&postbox=&state=HE&[email protected]&phone=00496975938501&fax=&mobile=&
customerip=127.0.0.1&custom1=123456&payment_method=1&token_id=80780000&cvc_code=123
&signature=90fc328b8ede3f3a4275ec0d213e93d342a0fa5c

Response example

transactionid=80780001&transid=80780001&status=0&errormessage=&errmsg=&amount=1.23&
price=1.23&currency=USD&orderid=PowerCash21-Test&user_id=10088265

Step 2b: CIT with CoF 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

POST data: 
merchantid=gateway_test&amount=1.23&currency=USD&orderid=PowerCash21-Test&
language=en&gender=M&lastname=Mann&street=An+der+Welle+4&zip=60322&
city=Frankfurt&country=DEU&customerid=&salutation=Herr&title=&
firstname=Muster&company=PowerCash21&birthday=07071971&house=19&
postbox=&state=HE&[email protected]&phone=00496975938501&
fax=&mobile=&customerip=127.0.0.1&custom1=123456&
payment_method=1&token_id=80780000&cof=cit&
signature=90fc328b8ede3f3a4275ec0d213e93d342a0fa5c

Response example

transactionid=80780001&transid=80780001&status=0&
errormessage=&errmsg=&amount=1.23&price=1.23&
currency=USD&orderid=PowerCash21-Test&user_id=10088265

Step 2C: MIT

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

POST data: 
merchantid=gateway_test&amount=1.23&currency=USD&orderid=PowerCash21-Test&
language=en&gender=M&lastname=Mann&street=An+der+Welle+4&zip=60322&
city=Frankfurt&country=DEU&customerid=&salutation=Herr&title=&
firstname=Muster&company=PowerCash21&birthday=07071971&house=19&
postbox=&state=HE&[email protected]&phone=00496975938501&
fax=&mobile=&customerip=127.0.0.1&custom1=123456&
payment_method=1&token_id=80780000&cof=mit&
signature=8bfd791a16d247d2c26b5d07acc98d17fe3227a3

Response example

transactionid=80780002&transid=80780002&status=0&
errormessage=&errmsg=&amount=1.23&price=1.23&
currency=USD&orderid=PowerCash21-Test&user_id=10088265

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:

Parameter name	Format	Length	Description
`banknet_date`	MMDD	4 digits	Mastercard Settlement date
`banknet_ref_number`	alphanumeric	up to 12 digits	Mastercard Financial Product Code and Banknet Reference
`visa_transaction_id`	numeric	15 digits	Visa transaction Identifier
+ full credit card data without CVC

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 Account manager or Technical support team to enable CoF migration function for your account