ELECTRONIC STATEMENT v15

Documentation

CIELO_Extrato_Eletronico_Manual_Versao_15.9-erratum

• Current version: 15.8.1
• Next update: 07/23/2024 to version 15.9.erratum

Test files

Test Files

15.7 Financial Reserve

15.8 Receivable negotiation update

The inclusion of the fields TID and Order/Reference Code will not happen in the Record Type 8. The size increase to 400 positions is maintained. Therefore, from position 240 to 400, it will be reserved for Uso Cielo.

Last updates

• Version: 15.9 – Addition of new fields for Pix transaction demonstration
  • Inclusion of the NSU/DOC field with 8 positions (positions 62 to 67 will continue to be filled)
  • Identifier of scheduled transfer for Pix sales
  • Increase in the size of Record Type 8 from 250 to 400 positions
  • Inclusion of the Scheduled transfer service for Pix transactions item in the topic RECONCILIATION THROUGH THE ELECTRONIC STATEMENT

The manual also highlighted additional information about the fields Posting types, Payment method, Batch number, Adjustment code, and data type in the Bank agency field.

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"
    }
  ]
}

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.