DocumentationAPI Reference
Documentation

Subscriptions

Card-on-File (CoF) Transactions

A Credential-on-File (CoF) transaction allows merchants to securely store a cardholder’s payment credentials for future payments.

CoF transactions are commonly used to streamline the checkout experience for returning customers and support use cases such as:

  • One-click payments
  • Recurring subscriptions
  • Automatic balance top-ups
  • Pay-per-use services
  • Unscheduled recurring payments

To initiate a cardholder-absent transaction, the following stages must be completed.


Initial Transaction

The initial transaction must be a cardholder-present transaction completed with explicit cardholder consent. According to card scheme requirements, the first transaction in a CoF series must be authenticated using 3D Secure (3DS). This is mandatory for EEA transactions and strongly recommended globally.

During Session generation, please include the following parameter:

token_id: INIT

https://pay4.sandbox.payabl.com/pay/payment/get_payment_widget_session?merchantid=gateway_test&orderid=Payabl%20Test&amount=5&currency=EUR&notification_url=https://webhook.site/3d0d04fe-f572-4b39-bdb5-9e9551b853c8&shop_url=https://127.0.0.1:5500&[email protected]&customerip=127.0.0.1&token_id=INIT&firstname=Test&lastname=Test&signature=5bde11263144818611c8b1c57d48ed21ee387ff3

Subsequent Transaction

Subsequent CoF transactions can be performed as either:

  1. Cardholder Initiated Transaction (CIT): The cardholder is actively involved in the payment process.

    Examples:

    1. One-click checkout
    2. Quick checkout using a previously stored card
    3. Transactions where the customer enters the CVV/CVC again

  2. Merchant Initiation Transaction (MIT): The merchant initiates the transaction without the cardholder being present.

    Examples:

    1. Subscription renewals
    2. Automatic balance top-ups
    3. Usage-based billing

For all subsequent transactions, please use the /authorize API endpoint..

https://sandbox.payabl.com/pay/backoffice/payment_authorize

🚧

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

Option 1: CIT with cvc_code

Use this option when the customer actively participates in the transaction and provides the card CVV/CVC.

Required Parameters

  • 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

Option 2: CIT with cof=cit

Use this option for customer-initiated payments where the cardholder is present but CVV/CVC collection is not required, such as one-click payments.

Required Parameters

  • 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

3DS for Subsequent CIT Transactions

📘

By default, subsequent Customer-Initiated Transactions (CIT) in a Card-on-File (COF) flow do not require a 3DS authentication. If needed, you can enable 3DS CIT transactions upon request. Please contact your Client Relations Manager

Flow Overview

When 3DS is enabled for subsequent CIT transactions:

  • The /authorize response returns a url_3ds
  • Redirect the cardholder to the provided URL
  • The cardholder completes 3DS authentication
  • A final callback is sent to your notification URL

You can test using the following public Sandbox credentials:

  • Merchant ID: gateway_test_3d
  • Secret: b185

Please see below API request and response examples:

Request example

https://sandbox.payabl.com/pay/backoffice/payment_authorize?merchantid=gateway_test_3d&amount=5&payment_method=1&currency=EUR&orderid=Payabl-Test&notification_url=https://webhook.site/d17ae7e3-4e6f-4f2c-b74f-25bc16b3773f&[email protected]&customerip=127.0.0.1&ccn=5232050000010003&cvc_code=325&exp_month=09&exp_year=2025&url_return=https://payabl.com/&token_id=216195626&cof=cit&signature=235e74928d5382ce09cbf685b17cb34f4fd9e438

Response example

transactionid=80780001&transid=80780001&status=0&
errormessage=&errmsg=&amount=1.23&price=1.23&
currency=USD&orderid=PowerCash21-Test&user_id=10088265
transactionid=216195635&transid=216195635&status=2000&errormessage=pending&errmsg=pending&amount=5&price=5&currency=EUR&orderid=Payabl-Test&bin=523205&payment_method=1&ccn_four=0003&card_type=Mastercard&cardholder=&expiry_month=09&expiry_year=2025&bin_country=USA&user_id=1085679&url_3ds=https%3A%2F%2Fpay4.sandbox.payabl.com%2F3dss%2Ftest%2Fv2%2FBB80FAFCB833469F98E7B6789973778D%2Fredirect

Final callback example

type=capture&transactionid=216195635&security=5b758e9d347227773196fcb7778997fc53878a33&orderid=Payabl-Test&errorcode=0&errormessage=
type=capture&transactionid=216195635&security=5b758e9d347227773196fcb7778997fc53878a33&orderid=Payabl-Test&errorcode=0&errormessage=

Option 3: MIT

Use this option for merchant-initiated transactions where the cardholder is not actively involved in the payment flow.

Required Parameters

  • 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

🚧

Please contact your Client Relations Manager to enable CoF function for your account

Updated about 6 hours ago