Cielo

This page provides a guide to integrate Cielo with DEUNA.

Supported Operations

Cielo integration in your payment strategy with DEUNA allows you to perform the following operations:

Authorization
Full capture
Partial captures
Purchase (auto-captured)
Partial refund (up to one per order)
Full refund
Void
3DS DEUNA

📘
Online multiple partial captures and refunds can be enabled through configuration. Contact DEUNA to activate these features if required

Supported Payment Methods

Cards

Visa
Mastercard
Diners
Amex
Elo

Active countries and currencies

Brasil (BRL)

Requirements

Contact your Cielo representative and request the following credentials:

Your Cielo credentials

📘
Make sure your account is properly configured on the Cielo side

Integrate Cielo

Integrate Cielo in DEUNA.

1. Look for Cielo in DEUNA

Look for Cielo in Connections and click it.

2. Configure Cielo in your store

After searching for Cielo in Connections, you must configure Cielo in your store.

In Connections, a window like the following will open:

Enter the following credentials:
- In Name enter a name to reference the credential.
- In Currency select the Currency of Merchant Processor available.
- In External Merchant ID enter the Cielo’s external merchant id.
- In Private API Key enter the Cielo’s private key.
Choose the type of operation you want to perform:
- Purchase
- Authorization
Choose if you want to activate 3DS.
Click Connect.

Once you complete the steps, you will see a success message.

3. Process payments with Cielo

You will see the Cielo connection within the Active Connections tab.

From this point on, you can now process transactions with Cielo through DEUNA.

Purchase v2 Example

{
    "payer_info": {
        "email": "[email protected]"
    },
    "order_type": "DEUNA_NOW",
    "payment_source": {
        "method_type": "credit_card",
        "card_info": {
            "expiry_month": "12",
            "expiry_year": "2026",
            "card_holder_dni": "12345678000195",
            "card_holder": "Omar Guzhnay",
            "card_number": "4024007197692931",
            "card_cvv": "123",
            "address1": "Rua Visconde de Pirajá, 123, apto 12",
            "address2": "apto 12",
            "zip": "22410001",
            "city": "MIGUEL HIDALGO",
            "state": "CIUDAD DE MÉXICO",
            "country": "BR",
            "phone": "+5511985176644",
            "installments": 1
        }
    },
    "order": {
        "order_id": "a7c1d6c6-9a36-49b1-8cee-dd5434f3d270",
        "currency": "BRL",
        "statement_descriptor":"test",
        "market_type": "ecommerce",
        "items": [
            {
                "id": "00ab2d23-f44a-4782-aa7c-bb4fadeddfe3",
                "name": "Item #1",
                "description": "Description Item #1",
                "total_amount": {
                    "original_amount": 115000,
                    "amount": 115000,
                    "total_discount": 0,
                    "currency": "BRL",
                    "currency_symbol": "R$"
                },
                "unit_price": {
                    "amount": 100000,
                    "currency": "BRL",
                    "currency_symbol": "R$"
                },
                "tax_amount": {
                    "amount": 15000,
                    "currency": "BRL",
                    "currency_symbol": "R$"
                },
                "quantity": 1,
                "image_url": "https://cdn.prod.website-files.com/66269d6696cb4969aa25e070/662d847fb61e3145e2b2f640_Logo%20DEUNA.svg",
                "taxable": true
            },
            {
                "id": "3cb41aec-1be8-4255-a386-94bb316a8157",
                "name": "Item #2",
                "description": "Description Item #2",
                "total_amount": {
                    "original_amount": 115000,
                    "amount": 115000,
                    "total_discount": 0,
                    "currency": "BRL",
                    "currency_symbol": "R$"
                },
                "unit_price": {
                    "amount": 100000,
                    "currency": "BRL",
                    "currency_symbol": "R$"
                },
                "tax_amount": {
                    "amount": 15000,
                    "currency": "BRL",
                    "currency_symbol": "R$"
                },
                "quantity": 1,
                "image_url": "https://cdn.prod.website-files.com/66269d6696cb4969aa25e070/662d847fb61e3145e2b2f640_Logo%20DEUNA.svg",
                "taxable": true
            }
        ],
        "sub_total": 200000,
        "tax_amount": 30000,
        "total_tax_amount": 30000,
        "total_amount": 230000,
        "store_code": "all",
        "billing_address": {
            "id": "4255",
            "first_name": "Omar",
            "last_name": "Guzhnay",
            "email": "[email protected]",
            "address1": "Rua Visconde de Pirajá, 123, apto 12",
            "address2": "apto 12",
            "zipcode": "22410001",
            "city": "Rio de Janeiro",
            "state_code": "RJ",
            "state_name": "Rio de Janeiro",
            "country_code": "BR",
            "identity_document": "12345678000195",
            "identity_document_type": "CNPJ",
            "phone": "+5511985176644",
            "lat": -22.943934,
            "lng": -43.182984,
            "additional_description": "confirm",
            "address_type": "home"
        }
    }
}

Request with initiator type

{
    "payer_info": {
        "email": "[email protected]"
    },
    "order_type": "DEUNA_NOW",
    "payment_source": {
        "method_type": "credit_card",
        "card_info": {
            "expiry_month": "12",
            "expiry_year": "2026",
            "card_holder_dni": "12345678000195",
            "card_holder": "Omar Guzhnay",
            "card_number": "4024007197692931",
            "card_cvv": "123",
            "address1": "Rua Visconde de Pirajá, 123, apto 12",
            "address2": "apto 12",
            "zip": "22410001",
            "city": "MIGUEL HIDALGO",
            "state": "CIUDAD DE MÉXICO",
            "country": "BR",
            "phone": "+5511985176644",
            "installments": 1
        }
    },
    "order": {
        "order_id": "6eab785f-c0c6-4e04-9021-b296b8a36611",
        "currency": "BRL",
        "statement_descriptor":"test",
        "market_type": "ecommerce",
        "initiator_type": "customer", //customer or merchant
        "items": [
            {
                "id": "00ab2d23-f44a-4782-aa7c-bb4fadeddfe3",
                "name": "Item #1",
                "description": "Description Item #1",
                "total_amount": {
                    "original_amount": 115000,
                    "amount": 115000,
                    "total_discount": 0,
                    "currency": "BRL",
                    "currency_symbol": "R$"
                },
                "unit_price": {
                    "amount": 100000,
                    "currency": "BRL",
                    "currency_symbol": "R$"
                },
                "tax_amount": {
                    "amount": 15000,
                    "currency": "BRL",
                    "currency_symbol": "R$"
                },
                "quantity": 1,
                "image_url": "https://cdn.prod.website-files.com/66269d6696cb4969aa25e070/662d847fb61e3145e2b2f640_Logo%20DEUNA.svg",
                "taxable": true
            },
            {
                "id": "3cb41aec-1be8-4255-a386-94bb316a8157",
                "name": "Item #2",
                "description": "Description Item #2",
                "total_amount": {
                    "original_amount": 115000,
                    "amount": 115000,
                    "total_discount": 0,
                    "currency": "BRL",
                    "currency_symbol": "R$"
                },
                "unit_price": {
                    "amount": 100000,
                    "currency": "BRL",
                    "currency_symbol": "R$"
                },
                "tax_amount": {
                    "amount": 15000,
                    "currency": "BRL",
                    "currency_symbol": "R$"
                },
                "quantity": 1,
                "image_url": "https://cdn.prod.website-files.com/66269d6696cb4969aa25e070/662d847fb61e3145e2b2f640_Logo%20DEUNA.svg",
                "taxable": true
            }
        ],
        "sub_total": 200000,
        "tax_amount": 30000,
        "total_tax_amount": 30000,
        "total_amount": 230000,
        "store_code": "all",
        "billing_address": {
            "id": "4255",
            "first_name": "Omar",
            "last_name": "Guzhnay",
            "email": "[email protected]",
            "address1": "Rua Visconde de Pirajá, 123, apto 12",
            "address2": "apto 12",
            "zipcode": "22410001",
            "city": "Rio de Janeiro",
            "state_code": "RJ",
            "state_name": "Rio de Janeiro",
            "country_code": "BR",
            "identity_document": "12345678000195",
            "identity_document_type": "CNPJ",
            "phone": "+5511985176644",
            "lat": -22.943934,
            "lng": -43.182984,
            "additional_description": "confirm",
            "address_type": "home"
        }
    }
}

Request with recurrence

{
    "payer_info": {
        "email": "[email protected]"
    },
    "order_type": "DEUNA_NOW",
    "payment_source": {
        "method_type": "credit_card",
        "card_info": {
            "expiry_month": "12",
            "expiry_year": "2026",
            "card_holder_dni": "12345678000195",
            "card_holder": "Omar Guzhnay",
            "card_number": "4024007197692931",
            "card_cvv": "123",
            "address1": "Rua Visconde de Pirajá, 123, apto 12",
            "address2": "apto 12",
            "zip": "22410001",
            "city": "MIGUEL HIDALGO",
            "state": "CIUDAD DE MÉXICO",
            "country": "BR",
            "phone": "+5511985176644",
            "installments": 1
        }
    },
    "order": {
        "order_id": "6eab785f-c0c6-4e04-9021-b296b8a36611",
        "currency": "BRL",
        "statement_descriptor":"test",
        "market_type": "ecommerce",
        "recurrence": {
            "first_time_use": true   //true = first or false=subsequent
        },
        "items": [
            {
                "id": "00ab2d23-f44a-4782-aa7c-bb4fadeddfe3",
                "name": "Item #1",
                "description": "Description Item #1",
                "total_amount": {
                    "original_amount": 115000,
                    "amount": 115000,
                    "total_discount": 0,
                    "currency": "BRL",
                    "currency_symbol": "R$"
                },
                "unit_price": {
                    "amount": 100000,
                    "currency": "BRL",
                    "currency_symbol": "R$"
                },
                "tax_amount": {
                    "amount": 15000,
                    "currency": "BRL",
                    "currency_symbol": "R$"
                },
                "quantity": 1,
                "image_url": "https://cdn.prod.website-files.com/66269d6696cb4969aa25e070/662d847fb61e3145e2b2f640_Logo%20DEUNA.svg",
                "taxable": true
            },
            {
                "id": "3cb41aec-1be8-4255-a386-94bb316a8157",
                "name": "Item #2",
                "description": "Description Item #2",
                "total_amount": {
                    "original_amount": 115000,
                    "amount": 115000,
                    "total_discount": 0,
                    "currency": "BRL",
                    "currency_symbol": "R$"
                },
                "unit_price": {
                    "amount": 100000,
                    "currency": "BRL",
                    "currency_symbol": "R$"
                },
                "tax_amount": {
                    "amount": 15000,
                    "currency": "BRL",
                    "currency_symbol": "R$"
                },
                "quantity": 1,
                "image_url": "https://cdn.prod.website-files.com/66269d6696cb4969aa25e070/662d847fb61e3145e2b2f640_Logo%20DEUNA.svg",
                "taxable": true
            }
        ],
        "sub_total": 200000,
        "tax_amount": 30000,
        "total_tax_amount": 30000,
        "total_amount": 230000,
        "store_code": "all",
        "billing_address": {
            "id": "4255",
            "first_name": "Omar",
            "last_name": "Guzhnay",
            "email": "[email protected]",
            "address1": "Rua Visconde de Pirajá, 123, apto 12",
            "address2": "apto 12",
            "zipcode": "22410001",
            "city": "Rio de Janeiro",
            "state_code": "RJ",
            "state_name": "Rio de Janeiro",
            "country_code": "BR",
            "identity_document": "12345678000195",
            "identity_document_type": "CNPJ",
            "phone": "+5511985176644",
            "lat": -22.943934,
            "lng": -43.182984,
            "additional_description": "confirm",
            "address_type": "home"
        }
    }
}

Special considerations and limitants

Billing address

Domestic transactions acquired by Cielo must include the following shopper information in the authorization request:

billing_address.zipcode
billing_address.state-name
billing_address.country_code

This follows the local regulation to withhold tax in the shopper's province. When this data is not supplied, Cielo withholds tax based on the merchant location.

Submit either one of the codes:

Province code COMARB	Province code ISO	Province Name
901	AR-C	CABA
909	AR-P	Formosa
919	AR-D	San Luis
908	AR-E	Entre Rios
911	AR-L	La Pampa
917	AR-A	Salta
906	AR-H	Chaco
907	AR-U	Chubut
910	AR-Y	Jujuy
920	AR-Z	Santa Cruz
903	AR-K	Catamarca
904	AR-X	Cordoba
912	AR-F	La Rioja
922	AR-G	Santiago del Estero
918	AR-J	San Juan
913	AR-M	Mendoza
914	AR-N	Misiones
915	AR-Q	Neuquén
916	AR-R	Rio Negro
923	AR-V	Tierra del Fuego
902	AR-B	Buenos Aires
921	AR-S	Santa Fe
924	AR-T	Tucumán
905	AR-W	Corrientes

Currency Code: Specifies the currency (ISO 4217) code for the relevant country.
Country Code: Specifies the ISO Country Codes
The number of installments is validated against the maximum number of installments agreed with the acquirer.
A payment that is AUTHORIZED can be captured.
A partial capture can be performed if necessary.
Each authorized payment allows for either a partial or full capture.
It is recommended to capture an order within 5 days of the authorization to prevent expiration.
A refund can be requested only after a payment reaches the CAPTURED status.
Refunds cannot exceed the original captured amount, but one or more partial refunds of the captured amount can be performed.
Only one partial refund can be sent per order.
A payment can be canceled (Void) only after it reaches the AUTHORIZED status.
Cancellation is no longer possible once the payment reaches the CAPTURED status.
Full cancel (void) can be sent per order.
The initiator type field is crucial for indicating who initiated the transaction, which has implications for the transaction flow and improves the conversion rate. The two possible values are:
1. customer: This value refers to a transaction where the cardholder (the customer) is present and interacts to initiate the purchase.
2. merchant: This value refers to a transaction where the merchant (or service provider) initiates the use of the customer's stored card, without direct customer interaction at that moment.
Orders with the recurrence object present differentiation between the first and subsequent payments.
1. The first payment is categorized by type recurrence.first_time_use = true.
2. Subsequent payments are identified by the type recurrence.first_time_use = false.
3. Note: The addition of the parameter recurrence.first_time_use is not linked or conditioned to the Recurring Payment API.
Before taking payments in Latin America a legal entity and an acquirer in the country of operation are required

Testing Resources

Cielo credentials

External Merchant ID: 8937bd5b-9796-494d-9fe5-f76b3e4da633
Private API Key: XKGHUBSBKIRXKAVPSKWLVXYCLVJUGTNZLIHPUSYV

Postman collection

Cielo.postman_environment.json

Cielo_2025.postman_collection.json

Testing cards

Brand	Type	Card Number	Expiry Month	Expiry Year	CVV
Visa	Approved	4024007197692931	12	2026	123
Master	Approved	5555666677778884	12	2026	123
Visa	Rejected	4000000000002503	12	2026	123
Master	Rejected	5200000000002235	12	2026	123