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:
- An EBANX Sandbox account. That's not the case? Please sign up for an Sandbox Account here;
- 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.
| Parameter | Data Type | Description |
|---|---|---|
| cof_type | string | Indicates if the card it is being stored or it is a card already stored. Possible values:
|
| Initiator | string | Indicates who is initiating the transaction. Possible Values:
|
| Trans_Type | string | Indicates what kind of COF transaction it is. Possible Values:
|
| Mandate_id | string | [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.