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.

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

Did this page help you?