Cielo OAUTH

Cielo OAUTH is an authentication process used in Cielo APIs that are correlated to E-commerce products. It uses the OAUTH2 protocol, where it is first necessary to obtain an access token, using its credentials, which should then be sent to the CieloOAuth API.

To get the ClientID and ClientSecret, contact the Cielo Products team. Credentials are released only to selected merchants.

To use Cielo Oauth you need the following credentials:

Access token

To gain access to Cielo services that use Cielo Oauth, you will need to obtain an access token, according to the steps below:

1. Concatenate the ClientId and ClientSecret, ClientId: ClientSecret
2. Encode the result in Base64
3. Submit a request using the HTTP POST method

Concatenation

Request

Request must be sent only in the Request Header.

x-www-form-urlencoded
--header "Authorization: Basic {base64}"
--header "Content-Type: application/x-www-form-urlencoded"
grant_type=client_credentials

Response

The response will have the Token used for new requests in Cielo Services

{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJjbGllbnRfbmFtZSI6Ik1ldUNoZWNrb3V0IE1hc3RlciBLZXkiLCJjbGllbnRfaWQiOiJjODlmZGasdasdasdmUyLTRlNzctODA2YS02ZDc1Y2QzOTdkYWMiLCJzY29wZXMiOiJ7XCJTY29wZVwiOlwiQ2hlY2tvdXRBcGlcIixcIkNsYWltc1wiOltdfSIsInJvbGUiOiJasdasdasd291dEFwaSIsImlzc47I6Imh0dHBzOi8vYXV0aGhvbasdasdnJhc3BhZy5jb20uYnIiLCJhdWQiOiJVVlF4Y1VBMmNTSjFma1EzSVVFbk9pSTNkbTl0ZmasdsadQjVKVVV1UVdnPSIsImV4cCI6MTQ5Nzk5NjY3NywibmJmIjoxNDk3OTEwMjc3fQ.ozj4xnH9PA3dji-ARPSbI7Nakn9dw5I8w6myBRkF-uA",
  "token_type": "bearer",
  "expires_in": 1199
}

The returned token (access_token) must be used in every request as an authorization key, emphasizing that it has a lifetime of 20 minutes (1200 seconds) and after this interval, it will be necessary to obtain a new token to access Cielo services.

Transactional control

The Transactional Control API allows the merchant to modify the status of orders without accessing the Checkout Cielo Backoffice.

The possible operations are:

• Query – Search a transaction
• Capture – capturar uma transação com valor total/Parcial
• Cancellation – cancelar uma transação com valor total/Parcial

Its main goal is to enable stores and platforms to automate operations through their own systems.

Central Endpoint https://cieloecommerce.cielo.com.br/api/public/v2/orders/

Authentication

The Payment Link API Authentication Process is the Cielo OAUTH

Prerequisites

In order to carry out the transaction control in Checkout Cielo it is MANDATORY that the store has one of the two notification templates configured below:

• Notification URL via POST
• Notification URL via JSON

Notification is required because all API commands (Query / Capture / Cancellation) use the unique identifier of the transaction, called Checkout_Cielo_Order_Number.

The Checkout_Cielo_Order_Number is only generated when payment is completed on the transactional screen. It is sent only by the Notification URL and not by the Transactional Screen Creation Response.

Query transaction

Consultation of transactions via API can be done up to 45 days after the sale has been made.

By Merchant_Order_Number

Querying transactions by Merchant_Order_Number returns a list of transactions with the same number of orders. This is because Checkout Cielo does not prevent the duplication of OrderNumbers by the merchant. The response will have the Checkout_Cielo_Order_Number that should be used to query a specific transaction.

Request

To query a transaction by Merchant_Order_Number, just perform a GET.

Header: Authorization: Bearer {access_token}

Response

“HTTP Status”: 200 – OK

[
  {
    "$id": "1",
    "checkoutOrderNumber": "a58995ce24fd4f1cb025701e95a51478",
    "createdDate": "2018-04-30T12:09:33.57",
    "links": [
      {
        "$id": "2",
        "method": "GET",
        "rel": "self",
        "href": "https://cieloecommerce.cielo.com.br/api/public/v2/orders/a58995ce24fd4f1cb025701e95a51478"
      }
    ]
  },
  {
    "$id": "3",
    "checkoutOrderNumber": "438f3391860a4bedbae9a868180dda6e",
    "createdDate": "2018-04-30T12:05:41.317",
    "links": [
      {
        "$id": "4",
        "method": "GET",
        "rel": "self",
        "href": "https://cieloecommerce.cielo.com.br/api/public/v2/orders/438f3391860a4bedbae9a868180dda6e"
      }
    ]
  }
]

By Checkout_Cielo_Order_Number

Request

To query a transaction by Checkout_Cielo_Order_Number, just perform GET.

Header: Authorization: Bearer {access_token}

Response

{
  "merchantId": "c89fdfbb-dbe2-4e77-806a-6d75cd397dac",
  "orderNumber": "054f5b509f7149d6aec3b4023a6a2957",
  "softDescriptor": "Pedido1234",
  "cart": {
    "items": [
      {
        "name": "Pedido ABC",
        "description": "50 canetas - R$30,00 | 10 cadernos - R$50,00 | 10 Borrachas - R$10,00",
        "unitPrice": 9000,
        "quantity": 1,
        "type": "1"
      }
    ]
  },
  "shipping": {
    "type": "FixedAmount",
    "services": [
      {
        "name": "Entrega Rápida",
        "price": 2000
      }
    ],
    "address": {
      "street": "Estrada Caetano Monteiro",
      "number": "391A",
      "complement": "BL 10 AP 208",
      "district": "Badu",
      "city": "Niterói",
      "state": "RJ"
    }
  },
  "payment": {
    "status": "Paid",
    "tid": "10127355487AK2C3EOTB",
    "nsu": "149111",
    "authorizationCode": "294551",
    "numberOfPayments": 1,
    "createdDate": "2018-03-02T14:29:43.767",
    "finishedDate": "2018-03-02T14:29:46.117",
    "cardMaskedNumber": "123456******2007",
    "brand": "Visa",
    "antifraud": {
      "antifraudeResult": 0,
      "description": "Lojista optou não realizar a análise do antifraude."
    }
  },
  "customer": {
    "identity": "12345678911",
    "fullName": "Fulano da Silva",
    "email": "exemplo@email.com.br",
    "phone": "11123456789"
  },
  "links": [
    {
      "method": "GET",
      "rel": "self",
      "href": "https://cieloecommerce.cielo.com.br/api/public/v2/orders/054f5b509f7149d6aec3b4023a6a2957"
    },
    {
      "method": "PUT",
      "rel": "void",
      "href": "https://cieloecommerce.cielo.com.br/api/public/v2/orders/054f5b509f7149d6aec3b4023a6a2957/void"
    }
  ]
}

By Payment Link ID

Request

To query a transaction by id, just perform GET.

Header: Authorization: Bearer {access_token}

Response

{
  "$id": "1",
  "productId": "9487e3a9-f204-4188-96c5-a5a3013b2517",
  "createdDate": "2019-07-11T10:35:04.947",
  "orders": [
    {
      "$id": "2",
      "orderNumber": "b74df3e3c1ac49ccb7ad89fde2d787f7",
      "createdDate": "2019-07-11T10:37:23.447",
      "payment": {
        "$id": "3",
        "price": 11500,
        "numberOfPayments": 6,
        "createdDate": "2019-07-11T10:37:23.447",
        "status": "Denied"
      },
      "links": [
        {
          "$id": "4",
          "method": "GET",
          "rel": "self",
          "href": "https://cieloecommerce.cielo.com.br/api/public/v2/orders/b74df3e3c1ac49ccb7ad89fde2d787f7"
        }
      ]
    }
  ]
}

Capture transaction

Request

To capture a transaction by Checkout_Cielo_Order_Number, just perform a PUT.

Total Capture

Partial Capture

OBS: Partial capture can only be performed once and is exclusive to credit card.

Header: Authorization: Bearer {access_token}

Response

HTTP Status: 200 – OK

{
  "success": true,
  "status": 2,
  "returnCode": "6",
  "returnMessage": "Operation Successful",
  "links": [
    {
      "method": "GET",
      "rel": "self",
      "href": "https://cieloecommerce.cielo.com.br/api/public/v2/orders/a9d517d81fb24b98b2d16eae2744be96"
    },
    {
      "method": "PUT",
      "rel": "void",
      "href": "https://cieloecommerce.cielo.com.br/api/public/v2/orders/a9d517d81fb24b98b2d16eae2744be96/void"
    }
  ]
}

Cancel transaction

Request

To cancel a transaction by Checkout_Cielo_Order_Number, just perform a PUT.

For cancellation requests for the same transaction, it is necessary to wait a period of 5 seconds between one request and another, so that the balance inquiry is carried out, the amount is reserved in the financial agenda and the balance is sensitized. Thus avoiding duplicate cancellation. This rule applies to total and/or partial cancellations.

To identify that cancellation requests are from the same transaction, we consider the EC number, cancellation authorization number, date of sale, sale amount, and NSU.

It is important to note that in order to make any cancellation request, it is necessary that the establishment has sufficient balance in the transaction/on the schedule

Total Cancellation

Partial Cancellation

OBS: The partial cancellation can be performed only after the capture. Partial cancellation can be performed countless times until the total amount is canceled.

Header: Authorization: Bearer {access_token}

Response

HTTP Status: 200 – OK

{
  "success": true,
  "status": 2,
  "returnCode": "6",
  "returnMessage": "Operation Successful",
  "links": [
    {
      "method": "GET",
      "rel": "self",
      "href": "https://cieloecommerce.cielo.com.br/api/public/v2/orders/a9d517d81fb24b98b2d16eae2744be96"
    },
    {
      "method": "PUT",
      "rel": "void",
      "href": "https://cieloecommerce.cielo.com.br/api/public/v2/orders/a9d517d81fb24b98b2d16eae2744be96/void"
    }
  ]
}

Status and Codes

Transactional status

The Checkout has its own Status, Unlike the CIELO SITE or the Cielo ecommerce API. Check the complete list below.

ABECS return codes

The Brazilian Association of Credit Card and Services Companies (ABECS) establishes as of July 15, 2020, the standardization of the return codes for denied sales authorizations for both the in store and and e-commerce payment solutions of the Brazilian market.

Please refer to ABECS Return Codes table to get the complete list of return codes.

Antifraud’s status list