Skip to main content
Card on file

The Card on File (COF) feature provides you with a comprehensive approach to implementing secure and seamless recurring payment functionality using tokenized card data. It involves securely tokenizing a customer’s card information during the initial transaction. This token can be reused for future transactions, eliminating the need for customers to re-enter their card details. This guide outlines the steps necessary to save customer card details for future transactions, ensuring compliance with security standards and offering customers a streamlined checkout experience.

The Card on File (COF) process involves two key scenarios:

  • Initial transaction (tokenization) - In the initial transaction, the customer’s card details are used to create a payment. During this process, EBANX generates a card token that can be stored and reused for subsequent transactions.
  • Subsequent transactions (using token)
    • Once the card is securely stored by the merchant, any future payments with the same card are processed as “stored” transactions, with no CVV. This informs the acquirer that the transaction is being made with a card securely stored by the merchant.
    • Stored transactions can be triggered by the merchant without user involvement, such as for recurring payments like a monthly subscription. In these cases, the merchant can process payments automatically using the stored card.

Requirements​

  • Existing EBANX Direct Integration - You must have an active EBANX Direct integration before implementing the Card on File (COF) functionality. COF enhances your existing Direct API setup by allowing you to securely store customer card details for future transactions.
  • API credentials - Ensure you have an EBANX integration key. If not, complete the Merchant Signup Form.

Instructions​

Follow the steps below.

  1. Select your environment

    Select the appropriate environment for your integration. Use the sandbox environment for testing, or the production environment for live transactions. Use the URL for your HTTP requests based on your selection.

    https://sandbox.ebanx.com/ws/direct

  2. Prepare your request

    Add the following parameters to the payment property in your ws/direct requests.


    ParameterTypeDescription
    cof_typestring
    initial - Use this value for the first payment in which the card details will be stored for future use. This payment includes the card verification and the user's consent to securely store the card information for subsequent transactions.
    stored - Use this value for all subsequent transactions where the card details have already been securely stored. The card is charged without requiring the user to re-enter their information or provide CVV, as the card is stored on file.
    		Required
    initiatorstringIndicates who is initiating the transaction:

    cit - Customer-Initiated Transaction. This is used when the customer initiates the transaction. It typically applies to situations where the customer actively decides to make a payment, such as purchasing a product or service through an online checkout.

    mit - Merchant-Initiated Transaction. Often performed without the direct involvement of the customer at the time of payment. This is common for recurring payments or subscriptions where the merchant charges the customer automatically at regular intervals
    		Required
    trans_typestringType of COF transaction. See detailed descriptions

    scheduled_reccuring - Regular, predictable payments.
    unscheduled_reccuring - Flexible, as-needed payments.
    installment - Fixed sequence of payments for a single purchase.
    customer_cof - Customer-initiated, ad-hoc transactions.
    merchant_cof - Merchant-initiated, agreement-based transactions.
    		Required
    mandate_idstring
    Links the transaction with a previous agreement (or mandate) that allows merchant to charge customer repeatedly without requiring them to re-enter card info

    If used, cof_type must be set to stored
    		Optional

  3. Sample request

    Use the following example to initiate a payment request.

    curl -X POST \
        --location 'https://sandbox.ebanx.com/ws/direct' \
        --header 'Content-Type: application/json' \
        --data '{
          "integration_key": "****************", // Your EBANX integration_key.
          "operation": "request",
          "payment": {
            "merchant_payment_code": "abc_123456", // Unique merchant code.
            "amount_total": 100,
            "currency_code": "BRL",
            "name": "test customer",
            "email": "abc@ebanx.com",
            "birth_date": "17/03/1997",
            "document": "10020030088",
            "address": "AV MIRACATU",
            "street_number": "2993",
            "street_complement": "CJ 5",
            "city": "CURITIBA",
            "state": "PR",
            "zipcode": "81500000",
            "country": "br",  // Country code.
            "phone_number": "4111111111",
            "payment_type_code": "mastercard",
            "card": {
              "auto_capture": false,
              "card_number": "5555555555554444",
              "card_name": "Master Card",
              "card_due_date": "11/2026",
              "card_cvv": "123"
            },
            "cof_info": {
              "cof_type": "initial", // Initial payment.
              "initiator": "CIT", // Initiated by customer.
              "trans_type": "CUSTOMER_COF" // Initiated by customer.
            }
          }
        }'

  4. Sample response

    Each request returns a response similar to the example below.

    {
        "payment": {
            "hash": "674750743fa2337e74d4fa965312e0f95219bfae5045b127",
            "country": "br",
            "merchant_payment_code": "abc_123456", // Unique merchant code.
            "order_number": null,
            "status": "PE",
            "status_date": null,
            "open_date": "2024-11-27 17:01:40",
            "confirm_date": null,
            "transfer_date": null,
            "amount_br": "100.38",
            "amount_ext": "100.00",
            "amount_iof": "0.38",
            "currency_rate": "1.0000",
            "currency_ext": "BRL",
            "due_date": "2024-11-30",
            "instalments": "1",
            "payment_type_code": "mastercard",
            "details": {
                "billing_descriptor": ""
            },
            "transaction_status": {
                "acquirer": "EBANX",
                "code": "OK",
                "description": "Accepted",
                "authcode": "62313"
            },
            "pre_approved": true,
            "capture_available": true,
            "cof_info": {
                "cof_type": "INITIAL",
                "initiator": "CIT",
                "mandate_id": "tid_67475074dee19", // Tracks/authorizes recurring payments
                "trans_type": "CUSTOMER_COF"
            }
        },
        "status": "SUCCESS"
    }

  5. Tokenize card for subsequent transactions

    For future transactions, you must utilize the card tokenization feature to generate a unique card token. This token, once obtained, should be securely stored within your system and used for subsequent transactions without requiring the customer to re-enter card details.

    For more information about tokenization, refer to the
    Card Tokenization Guidechevron_right

  6. Subsequent transactions

    For subsequent transactions, utilize the securely stored tokenized card in your system to generate and submit payment requests.

    Example

    curl -X POST \
        --location 'https://sandbox.ebanx.com/ws/direct' \
        --header 'Content-Type: application/json' \
        --data '{
          "integration_key": "****************", // Your EBANX integration_key.
          "operation": "request",
          "payment": {
            "merchant_payment_code": "abc_123456", // Unique merchant code.
            "amount_total": 100,
            "currency_code": "BRL",
            "name": "test customer",
            "email": "abc@ebanx.com",
            "birth_date": "17/03/1997",
            "document": "10020030088",
            "address": "AV MIRACATU",
            "street_number": "2993",
            "street_complement": "CJ 5",
            "city": "CURITIBA",
            "state": "PR",
            "zipcode": "81500000",
            "country": "br",  // Country code.
            "phone_number": "4111111111",
            "payment_type_code": "mastercard",
            "card": {
              "token": "8ef8467b95942e4da41b71dab129e794805fad8c32698fbd3da652b1baef7cd1b8e02ed4841da637c3baa399801f6a3def287a2051d1c79a596b6ae8d921b454"
            },
            "cof_info": {
              "cof_type": "stored", // Initial payment.
              "initiator": "MIT", // Initiated by merchant.
              "trans_type": "CUSTOMER_COF" // Initiated by customer.
            }
          }
        }'

  7. Congratulations!

    You have succesfully integrated Card on File.


Resources​

Use the following resources when testing in your sandbox environment.

Credit Card Icon

Sample Cards

Click here to view mock card data to validate your payment integration.

Click to explorechevron_right
Globe Icon

API Reference

Click here to access detailed API documentation to integrate efficiently.

Click to explorechevron_right
Mock Data Icon

Mock Customer Data

Click here to view mock customer data for testing and validating user flows.

Click to explorechevron_right
Debit Card Icon

Error Codes

Click here to review common error codes to troubleshoot and resolve issues quickly.

Click to explorechevron_right


Types of COF transactions​

  • Scheduled recurring
    These are recurring payments initiated automatically by the merchant at predetermined intervals (e.g., monthly, annually). The customer provides consent to store their card details and agrees to a fixed payment schedule.

    • Subscriptions to streaming services, gym memberships, or insurance premiums, etc.
    • Characteristics
      • Fixed schedule (e.g., same day each month).
      • Consistent or pre-agreed amounts.
      • Classified as a Merchant-Initiated Transaction (MIT).

  • Unscheduled recurring
    Payments initiated by the merchant without a fixed schedule, but based on a pre-established agreement with the customer. The amounts and timing may vary depending on the customer's usage or balance.

    • Utility bills (electricity, water) or pay-as-you-go services where the bill fluctuates based on consumption, etc.
    • Characteristics
      • No fixed timing.
      • Variable amounts.
      • Requires explicit prior consent for each payment type.

  • Installment
    These are payments split into multiple installments for a single purchase, with the customer authorizing the merchant to charge their stored card periodically.

    • Purchasing a laptop in three monthly payments or financing a trip over six months. (not bank installments), etc.
    • Characteristics
      • Fixed number of payments.
      • Fixed schedule and amount.
      • Often linked to credit products.

  • Customer COF
    Transactions initiated directly by the cardholder using previously stored card details. These are typically one-time purchases.

    • A customer making an online purchase, or booking a hotel using their stored card, etc.
    • Characteristics
      • Cardholder-Initiated Transaction (CIT).
      • Customer explicitly triggers the transaction.

  • Merchant COF
    Transactions initiated by the merchant without real-time interaction from the customer, leveraging stored card details as per a prior agreement. Commonly associated with recurring billing or adjustments.

    • A merchant charging a subscription fee after the customer’s Card on File consent, or processing late fees, etc.
    • Characteristics
      • Merchant-Initiated Transaction (MIT).
      • May include retries, recurring charges, or agreed modifications.

Still need help?

Help Image

We hope this article was helpful. If you still have questions, you can explore the following options: