Important

16/01/2024 - V15 - New version of electronic statements - Documentation and test files

Aiming to bring greater transparency and fluidity in the conciliation of extracts, our files will have a new structure in their demonstration.

This change is expected to be implemented in 01/16/2024

Below is the communication sent with the details of the changes, test files and complementary documentation to support the homologation.

PT-BR

EN

ES

Arquivos de Teste

It is important that the approval of the new structure takes place by the indicated date so as not to impact the reading of the extracts.

Important! The current version of the extracts will no longer be supported and generated from Apr/24

Change History

Production Version

Here you will find the documentation relating to the productive version of the EDI Statement, updated on: 09/06/2023

Manual Portuguese version

Manual English version

Note: the updates below will be available from June 7, 2021.

Electronic Statement Manual

Electronic Statement Manual - Versão Portuguesa

EE Layout Update - Receivables Registration + PIX

Test files - Announcement 12/09/2022

01/09/2023 - V14 - Inclusion of new Pix fields (CIELO16) - Documentation and test files

This change was implemented in 9/1/2023

CIELO_Electronic_Statement_-_English_-_Version_14_v2(pix)

Massa_PIX_Cenarios_EDI_V2

Introduction

This API makes possible to register groups and maintain their registration to receive Electronic Data Interchange (EDI) files

Description

The Electronic Statement is a service provided by Cielo to merchants that need an automatic in the reconciliation process. Through it, information is transmitted in a standardized manner, with no manual intervention via SFG channel (sterling file gateway), enabling agile and secure traffic of information/data. The macro flow of the service is as follows:

Benefits

• Enables automated accounting and financial reconciliation
• Increased agility and operational efficiency
• Integration with the sales automation
• Security in receiving information
• Specialized support

Consent Flow

Step 1 - Login

1 - The partner redirects the client to {cielo-login-url}.
2 - The customer enters with their credentials and clicks on ‘Login’.
3 - Cielo shows the authorization terms and the customer approves this access by clicking on ‘Allow Access. 4 - Cielo redirects the customer to the partner again at {partner-call-back-url}`.

What is cielo-login-url?

https://{base-login-url}?response_type=code&client_id={client_id}&redirect_uri={redirect_uri}&scope={scope}&state={state}`

• base-login-url: Base URL that changes by the environment, will be sent at design time
• response_type: The value must be fixed “code”
• client_id: Customer identifier, will be sent by Cielo at project time
• redirect_uri: Partner URL for Cielo to redirect the user when the login process ends, or if there is an error in the process
• scope: A comma-separated list of the APIs that the partner wants to access, the possible scopes will be sent by API.
• state: A value that the customer wants to receive in return to maintain the state between the request and the return

What is partner-callback-url?

https://{partner-callback-url}?code={code}&state={state}

• partner-callback-url: The partner URL will be redirected when the login process ends.
• code: The authorization code generated by Cielo. With this code the partner will be able to exchange for an access_token to make calls on behalf of the customer.
• state: The same amount that the partner sent in the requisition.

Step 2 - Requesting an Access Token

• The partner service requests an access_token.
• Cielo returns an acess_token, a refresh_token and an expiration_time.

Request

POST {cielo-api-base-url}/consent/v1/oauth/access-token

Key	Value
Authorization	Basic Base64(client_id do parceiro concatenado com “:” e o client_secret codificado em base64)

curl --location --request POST 'https://{cielo-api-base-url}/consent/v1/oauth/access-token' \
--header 'Basic Base64'
--header 'Content-Type: application/json' \
--data-raw '{
    "grant_type": "authorization_code",
    "code": "{}"
}'

Response

{
"access_token": "{access_token}",
"refresh_token": "{refresh_token}",
"token_type": "access_token",
"expires_in": {expiration_time}
}

Observações

• The authorization_code needs to be replaced with an access_token in less than 10 minutes.
• This type of access_token is mandatory to call APIs that return sensitive customer data.
• The partner needs to store access_token and refresh_token in a safe place.
• When the access_token expires, the partner will no longer be able to call the APIs until they request a new acess_token using the refresh_token flow.
• The acess_token generated in this flow will be unique per Cielo customer, as it must be approved by the customer.
• The partner is NOT able to generate an access_token without the customer’s consent.
• The partner is NOT able to use the authorization code, received in the first step, more than once.

Step 3 - Requesting the APIs

At this point, the partner will be able to call Cielo’s APIs without the need for customer approval, as this has already been granted.

The only requirement to call Cielo’s APIs is to send the following HTTP header: ** Authorization: Bearer {access_token} ** In all calls to the APIs.

• The access_token was obtained in the second step

Step 3.1 - Updating an Access Token

1. The partner calls the service refresh_token.
2. Cielo returns a new access_token, a new refresh_token and a new expiration_time.

The response data will be the same as in step 2 when the partner requests an acess_token, however all data returned is new and needs to be stored in place of the old ones.

Request

curl --location --request POST 'https://{cielo-api-base-url}/consent/v1/oauth/access-token' \
--header 'Basic Base64'
--header 'Content-Type: application/json' \
--data-raw '{
    "grant_type": "refresh_token",
    "refresh_token": "{}"
}'

A point of attention in the request because now the partner needs to send grant_type as refresh_token and in the refresh_token field a valid refresh_token should be sent (and no longer an access_token).

Response

{
"access_token": "{access_token}",
"refresh_token": "{refresh_token}",
"token_type": "access_token",
"expires_in": {expiration_time}
}

Errors

If an error occurs on the Cielo side, the customer will be redirected to the partner’s call-back URL with the error parameter in the URL, for example https: // {partner-callback-url}? Error = {error}.

Possible values for {error}:

• lid_request: The request is missing some mandatory parameter, or it has an invalid parameter, or any other possibility that makes the URL incorrect.
• unauthorized_client: The partner is not authorized to make a request using this method.
• access_denied: The resource owner or authorization server denied the request.
• unsupported_response_type: The authorization server does not support obtaining an authorization code using this method.
• invalid_scope: The scope is invalid, unknown or malformed.
• server_error: The authorization server encountered an unexpected condition and is unable to complete this request. (This error is necessary because it is not possible to return an HTTP status code 500 Internal Server Error via HTTP redirect)
• temporarily_unavailable: The authorization server is unable to handle the request due to temporary overhead or is undergoing maintenance. (This error is necessary as it is not possible to return an HTTP Status 503 Service Unavailable to the partner via HTTP redirect)

Optionally, another parameter error_description can be returned with a detail of the error, just plain text.

Note

• All tokens (access_token and refresh_token) must be stored in a safe place.
• The partner needs to start a new concession flow if they lose the tokens or both expire (The refresh_token expires 90 days from generation).
• If you generate a new refresh_token it has another 90 days from the generation to expire.
• The partner needs to start a new concession flow for each Cielo client that the partner wants to consult the data.

Environment

Collection

We make the Collections used to perform all API operations available. You only need to configure the URL and credentials.

Collections Download

Operations

POST Register Merchant ID

Register Merchant ID (just one, a list or all), based on a Entity Number.

Request

POST /edi/registers

Headers

Key	Value
Authorization	Bearer + access_token

{
  "mainMerchantId": "9999111222",
  "merchants": [
    "9999111111",
    "9999111333"
  ],
  "merchantEMail": "customer@customer.com",
  "type": [
    "SELL"
  ]
}

Response

{
  "legalEntityNumber": 1234567890,
  "mainMerchantId": 2008983,
  "registerID": 12345,
  "merchants": [
    823958412384701,
    679809436576210
  ],
  "type": [
    "SELL"
  ],
  "status": "PROCESSING"
}

GET Retrieve status

Retrieve the EDI registration status.

Response

GET /edi/registers/{registerID}

Headers

Key	Value
Authorization	Bearer + access_token

{
  "legalEntityNumber": "01234567890",
  "registerID": 12345,
  "merchants": [
    9999222111,
    9999222222
  ],
  "status": "PROCESSING"
}

GET Consult Register Merchant ID

Consult Merchant ID based on a Register ID or a Main Merchant ID.

Response

GET /edi

Headers

Key	Value
Authorization	Bearer + access_token
registerID	Registration ID provided by /edi/registers when registering. Can be used in place of mainMerchantID if preferred (only one needs to be informed).
mainMerchantID	Main Customer ID. The most usual way to retrieve an EDI register in the company. Can be used instead of registerID mainly in cases of registration not performed by /edi/registers.

{
  "legalEntityNumer": "12314314",
  "mainMerchantId": 9999111222,
  "registerID": 12345,
  "merchants": [
    9999111111,
    9999111333
  ],
  "type": [
    "SELL"
  ],
  "acknowledge": "COMPLETED"
}

PUT Update Register Merchant ID

Update Merchant ID based on a Register ID or a Main Merchant ID.

Request

PUT /edi

Headers

Key	Value
Authorization	Bearer + access_token

{
  "registerID": "string",
  "mainMerchantId": "9999222333",
  "merchants": [
    "9999222111",
    "9999222222"
  ],
  "type": [
    "SELL"
  ]
}

Response

{
  "legalEntityNumber": "01234567890",
  "mainMerchantId": 9999111222,
  "registerID": 12345,
  "merchants": [
    9999222333,
    9999111222
  ],
  "type": [
    "SELL"
  ]
}

DELETE Delete Register Merchant ID

Delete MerchantID based on a Register ID or a Main Merchant ID.

Response

DELETE /edi

Headers

Key	Value
Authorization	Bearer + access_token
registerID	Registration ID provided by /edi/registers when registering. Can be used in place of mainMerchantID if preferred (only one needs to be informed).
mainMerchantID	Main Customer ID. The most usual way to retrieve an EDI register in the company. Can be used instead of registerID mainly in cases of registration not performed by /edi/registers.

{
  "legalEntityNumer": "12314314",
  "mainMerchantId": 9999111222,
  "registerID": 12345,
  "acknowledge": "COMPLETED"
}

GET List of branches

Performs the list of customers below the informed access_token. The filter can be used to list only those available or unavailable. Unavailable means that the branch already participates in another register. In the register and editing services, there is validation to allow only those available to be informed.

Response

GET /edi/merchantgroup

Headers

Key	Value
Authorization	Bearer + access_token

{
  "legalEntityNumber": "string",
  "branches": [
    {
      "merchantID": "9999111222",
      "legalEntityNumber": "01234567890",
      "businessName": "V",
      "status": "UNAVAILABLE"
    }
  ]
}

Types Of Electronic Statements

Table A - File Types

Layout For The Types Of Records

Record 0 - Header

It identifies the header of each file, by chain of electronic statement*.

• (*) register that allows the inclusion of all establishments controlled by the customer, regardless of the type of payment (centralized, decentralized, individual). All establishment numbers must be reported in the registration form.

Record 1 - Sales Summary

Group of sales, adjustments, or service charges. It enables the identification of the origin of the entries and the possible maintenance actions.

• (*) Only 2 decimal places should be considered, with no commas, periods, or any other characters.

Record 2 - Detailed Sales

Sales or adjustments of sale summary available in the sales or payment file. Pursuant to the security rules, all records containing a card number will show it truncated.

• (*) Only 2 decimal places should be considered, with no commas, periods, or any other characters.

Record 5 - Prepayment Operation

It displays the prepayment conducted at Cielo / Alelo or assignment of receivables (only for the Bradesco) on the day that precedes the generation of the file.

(*) Only 3 decimal places should be considered, with no commas, periods, or any other characters.

Record 6 - Assignment Sales Summary

It displays the sales summary of prepayment or assigned of receivables.

• (*) Only 2 decimal places should be considered, with no commas, periods, or any other characters.

Record 7 - Withheld Prepayment by Debits - Sales Summary

It displays the withheld prepayment by debits.

Record 9 - Trailer

It indicates the end of the file.

Note: The fields reserved for Cielo may be used to include new information. It may also be necessary to include new types of records. Therefore, we suggest that the reconciliation solution should disregard the records that are not listed in this specification.

Tables

Table I - File Types

Table II - Type Of Statement

Table III - Transaction Type

Table IV - Payment Status

When a credit amount is being offset against a debit amount, both will be sent in the payment file, on the offsetting date subsequent to the scheduled payment date. The status to the may appear again in the payment statement, when the merchant bank returns a credit transfer (resend of payment).

Table V - Product Code

• Codes referring to the following cards: Construcard, Minha Casa Melhor, Producard, and Moveiscard

Table VI - Origin Of Adjustment

Table VII - Card Brand

Table VIII - Capture Method

Table IX - Reason For Decline

Table X - Entry Mode

Table XI - Group Of Cards

Table XII - Card Type

File Transmission and Resending

In order to receive the Electronic Statement, the client must contact the EDI Service and complete the service acquisition form. The files will be made available in the Inbox daily, except for the remaining balance file, which will be sent monthly. In the absence of transactions, the file sent will contain only the and the . In the case of any inconsistency in the transmission of the file(s), the client should inform Cielo, contacting the EDI Service (edi@cielo.com.br).

File Resending

In case of loss of the file or not receiving, the Cielo will make available in the Inbox the same file sent daily (backup file). The client may contact EDI Service to request resending of the file.

File Recovery

• Allows for the recovery of a previous transaction, updating the status of the entries.
• The files will be made available separately from the daily file.
• Recovery is not available for the Remaining Balance file (09).
• The request can be made to EDI Service.

Financial Concepts/Glossary

Adjustment: debit or credit entry made by Cielo in order to settle undue charges, to refund a sale, or issue a reversal to the merchant.

Change in Installment Plan: it occurs when the cardholder requests the client to modify the original installment plan, such as the total or partial sale refund and the change in the number or amount of the installments.

Prepayment: service offered by Cielo or Alelo to clients that wish to prepayment their credit and installment transactions.

Chain Centralized Payment: is a group of customers with the same CNPJ root, rules locks and anticipation, bank address and the same commercial terms and commission term. A chain has only one matrix, chosen by the customer, where are registered all products and rates applied in the branches.

Assignment of Receivables: operation concerning the assignment of receivables, conducted at the merchant bank account, only available for Bradesco.

Chargeback: refund, made by the issuer bank, of a transaction disputed or challenged by the cardholder.

Assignment: advance payment operation carried out with Cielo or with the market. Counterpart records of operations carried out with the market within the sales files depend on the financier sending data to Cielo in a timely manner. Transactions sent late will not be demonstrated in the sales files, being necessary to request the reprocessing of the extracts to the service channels.

Date of Sale: day on which the sale was made by the Cielo client. For clients that operate using e-commerce solutions, this is the date on which the cardholder made a purchase on the website and not the date on which the sale was confirmed by the Cielo client.

Date of Submission: day on which the sale was submitted to Cielo for processing, which may be Saturdays, Sundays, or holidays. This is the reference date used in the calculation of the payment schedule and may differ from the date of sale, depending on the capture solution used.

Date of Capture: date on which the transaction was captured in the Cielo system. For Cielo clients that operate using ecommerce solutions, this is the date on which the transaction was confirmed by the client.

Date of Submission to the Bank: date on which the (credit or debit) payment file was submitted to the bank.

Payment Date: date on which payment is effectively credited to the bank account, considering the payment period agreed upon. If the date calculated is not a business day, payment will be made on the next business day. Initially, once the sale is captured, the scheduled payment date is provided; however, it may be postponed if the amount is used to offset any debit concerning the sale refund, reversal, or service charges. Payment may also be made in advance, if the client conducts a prepayment operation.

Chain of Electronic Statement: register that allows the inclusion of all establishments controlled by the customer, regardless of the type of payment (centralized, decentralized, individual).

Encumbrance: credit operation in the guarantee model carried out with a financing agent. It does not entail the anticipation of the date of payment of the amounts, only the exchange of ownership of the recipient.

Exclusive Transaction Number: it is assigned by Cielo and exclusively identifies each transaction, enabling the reconciliation of the adjustments, prepayment operations, and assignment of receivables conducted in the sales summary and in the detailed sales through this key. To this end, the reconciliation solution should only consider the fixed parts of the exclusive number, according to the following composition.

Merchant Installment Transaction - Period: in the sales file with the option for future installments, all installments will be sent with the original presentation date. However, the payment file will display the clearance date of the respective installment. The payment date of all installments is calculated based on the date on which the first installment was submitted, and its logic differs for each card brand, as shown below:

VISA, ELO, DINERS and other brands: the installments will be cleared monthly on the same day as the 1st installment, regardless of whether or not it is a business day. In this way, a sale in four installments submitted on 01/10/2015 will have the following clearance plan (payment term: 30 days):

The only exception to the rule above occurs whenever a date does not exist in the month in which the installment is cleared. For example: a sale whose 1st installment was presented on January 31, 2015. Since February 31 does not exist, the installment for this month will be submitted on the last day of the month; that is, on February 28, 2015.

MASTERCARD: the date of submission of the 1st installment will be used as the reference date for clearance of all installments in the plan; however, the date of the future installments will always fall 30 days after the submission of the first installment, a logic that will be maintained until the end of the plan. In the example of the sale submitted on January 10, 2014 used previously, notice that the installments are cleared 30, 60, and 90 days after submission of the first installment (payment term: 30 days):

Declined Transaction: it occurs whenever the client or the sale does not match the attributes required for the proper processing and scheduling of payment data. Resale: it occurs whenever a change is made to the payment plan of an installment transaction, whether in relation to the number of installments or to the total amount of the transaction. Capture Solution: device and/or processing software (POS, PDV, E-commerce, mobile payment, EDI, etc.) that connects to the Cielo network to authorize and capture transactions.

Sales Summary: identifies a sales group on a certain date. It has 7 positions and will be formatted as follows.

Remaining Balance: it comprises all releases to receive from Cielo. They should be considered Cielo payments not made in the past due to refund and chargeback.

Types of registration: with registration by the Commercial Group, which uses the CNPJ root, all new merchants from the root are automatically included in the electronic statement, avoiding the loss of information.