Version: current

Card on File

About this guide

This page explains how to add COF, to your existing Direct API integration. Direct API integration is basically the same for all payment methods, only varying the payment_type_code and some additional required fields.

If you are not integrated with EBANX Direct API yet, please take a look in this basic guide about it. Are you not sure if EBANX Direct API is the best option for your e-commerce? Please, talk with one of our integration specialists.

What you will need

Before starting your integration, please make sure that you have:

  1. An EBANX Sandbox account. That's not the case? Please sign up for an Sandbox Account here;
  2. Credit Cards or Debit Cards enabled in your EBANX Dashboard.

How it works

You have to add in the ws/direct and ws/cardverify API, new fields for the merchant to inform the COF information.

Fields and possible values:

  • "cof_type" = "initial" for the first payment that will save the card information. "stored" for payments or sequence of payments with a stored card.
  • "initiator" = Indicates who is requesting the transaction. (CIT/MIT)
  • "mandate_id" [OPTIONAL] = Id that allows you to use the card in future payments. Acquirers normally calls it "Network transaction ID"
  • "transType" = That can have different values depending on the transaction.
ParameterData TypeDescription
cof_typestringIndicates if the card it is being stored or it is a card already stored. Possible values:
  • Initial
  • Stored
InitiatorstringIndicates who is initiating the transaction. Possible Values:
  • CIT
  • MIT
Trans_TypestringIndicates what kind of COF transaction it is. Possible Values:
  • SCHEDULED_RECURRING: Recurring Transaction with fixed values
  • UNSCHEDULED_RECURRING: Recurring Transaction with variable values
  • INSTALLMENT: Sales in installment with fixed values
  • MERCHANT_COF: Merchant initiated transaction, unscheduled
  • CUSTOMER_COF: Customer initiated transaction, unscheduled
Mandate_idstring[OPTIONAL] Indicates brand transaction ID of the COF transaction

Request example

{
"integration_key": "********************************",
"operation": "request",
"mode": "full",
"payment": {
"merchant_payment_code": "xxxxxxxxxxxxxxxxxxxx",
"order_number": "xxxxxxxxxx",
"amount_total": 100,
"currency_code": "COP",
"name": "test customer",
"email": "abc@ebanx.com",
"birth_date": "17/03/1997",
"document": "xxxxxxxxxxx",
"address": "AV MIRACATU",
"street_number": "2993",
"street_complement": "CJ 5",
"city": "CURITIBA",
"state": "PR",
"zipcode": "81500000",
"country": "co",
"phone_number": "4111111111",
"payment_type_code": "mastercard",
"card": {
"auto_capture": false,
"card_number": "1234567891011",
"card_name": "Master Card",
"card_due_date": "11/2026",
"card_cvv": "123"
},
"cof_info": {
"cof_type": "initial",
"initiator": "CIT",
"trans_type": "CUSTOMER_COF"
}
}
}

Response example

{
"payment": {
"hash": "xxxxxxxxxxxxxxxxxxx",
"country": "co",
"merchant_payment_code": "xxxxxxxxxxxxxx",
"order_number": "xxxxxxxxxx",
"status": "CO",
"status_date": "2024-08-06 17:57:28",
"open_date": "2024-08-06 17:57:26",
"confirm_date": null,
"transfer_date": null,
"amount_br": "100.00",
"amount_ext": "100.00",
"amount_iof": "0.00",
"currency_rate": "1.0000",
"currency_ext": "COP",
"due_date": "2024-08-09",
"instalments": "1",
"payment_type_code": "mastercard",
"details": {
"billing_descriptor": "EBN*DEMONSTRATION"
},
"transaction_status": {
"acquirer": "EBANX",
"code": "OK",
"description": "Accepted"
},
"customer": {
"document": "xxxxxxxxx",
"email": "abc@ebanx.com",
"name": "TEST CUSTOMER",
"birth_date": "1997-03-17"
},
"single_transaction": {
"amount_local": "0.00",
"amount_crossborder": "100.00"
},
"requested_currency": "COP",
"currency_ext_base": "COP",
"cof_info": {
"cof_type": "initial",
"initiator": "CIT",
"mandate_id": "abc123",
"trans_type": "CUSTOMER_COF"
}
},
"status": "SUCCESS"
}

Getting help

We hope this article was enlightening, but in case we’ve failed to take out your doubts you have the following options to keep on seeking for answers:

  • If you’re not our partner yet and would like to know more about our prices and conditions please fill our this form and our commercial team will get in touch with you.
  • In case you’re already our partner please get in touch with our support team at integration@ebanx.com.
Last updated on by Fabio Bandacheski