Link de Pagamento API

Redirecionando para https://docs.cielo.com.br/link-en/docs/about-link-de-pagamento ...

The documentation for Link de Pagamento Cielo is now on a new portal

Access the new E-commerce developers portal at docs.cielo.com.br.

Warning: The content on this page is being discontinued and will not receive updates after 09/04/2024. Please visit the new documentation at docs.cielo.br.

Link de Pagamento Cielo

About this documentation

This manual will guide the developer in the integration with Link de Pagamento Cielo API. By integrating the Link de Pagamento API, you will be able to:

• Set up your store and customize your payment links;
• Create and edit payment links via API;
• Receive payment notifications;
• Consult payments.

You can also use Link de Pagamento through the Cielo website or through the Cielo Gestão app.

About Link de Pagamento Cielo

Link de Pagamento allows you to send a payment link for an order to your customers via social media or any other channel you prefer. When opening the payment link, the shopper will see a page customized with your store logo and payment options.

You can sell different types of products:

• Physical Material: Any physical product that needs delivery via shipping, such as clothing, electronics, cosmetics, furniture, etc;
• Digital: any digital product that does not need to be shipped, such as online media or games, software, etc.;
• Service: any service that does not require shipping, such as maintenance and delivery services or dental appointments, among others;
• Payment: single payments;
• Recurrence: sales that are repeated within a certain period, such as gym membership or language classes.

How to create a Link de Pagamento?

You can create a Link de Pagamento through the Cielo website, the Cielo Gestão app or through the Link de Pagamento API. In this manual, we will talk about the integration of the Link de Pagamento API.

Who can use Link de Pagamento?

Any store that wants to sell online can create a payment link and share this link through social media. You don’t need to have an e-commerce to use Link de Pagamento.

Link de Pagamento API

Link de Pagamento API is a REST API that allows creating, editing and querying payment links. The main advantage of the API is that it allows stores to create payment links (via buttons or QR Codes) through their own systems and share the Link de Pagamento with their customers, without the need to access the Cielo website.

The following image represents the general flow of how the Link de Pagamento API works:

1. The merchant sends a payment link creation request to the Link de Pagamento API;
2. Link de Pagamento API returns a payment link URL and a link ID;
3. The merchant shares the payment link with the shopper;
4. The shopper makes the payment;
5. Cielo (as the acquirer) authorizes the payment and sends confirmation to Link de Pagamento;
6. The Link de Pagamento API sends a transaction completion notification or status change notification to the store. If desired, the merchant can develop a process for sending a confirmation email to the shopper (not available through the Link de Pagamento API).

Payment methods and brands

With Link de Pagamento you can sell your products and services using the main payment methods, such as credit and debit cards or digital wallets

Quick Start

To start your integration with the Link de Pagamento API, you will need:

1. Request the establishment number (EC) for the Link de Pagamento;
2. Configure the store settings (customization of the page, choosing payment methods and a contract with the Post Office, if there is one);
3. Set up a notification and status change URL for your store;
4. Get the API access credentials (ClientId and Client Secret);
5. Request an access token via API using the credentials;
6. With the token, create a payment link;
7. When there is a payment attempt on the link, you will receive a notification* with all data filled in at checkout;
8. If the transaction changes status, you will receive a notification* of the status change;
9. To perform tests, use Link de Pagamento’s Test Mode.

*If you have configured the notification URL.

Merchant Settings

Before setting up, you need to enable Link de Pagamento for your store.

Enabling the establishment number (EC) for the Link de Pagamento

• If you are not yet a Cielo client or if you only use the POS terminal, go to the Cielo website to enable the establishment number (EC) for the Link de Pagamento;
• If you are already a Cielo E-commerce client, contact your commercial manager or Cielo Support.

Setting up your store

Access the Store Settings on the Cielo website

Go to the Cielo website and login. Go to E-commerce > Link de Pagamento > Configurações > Configurações da loja.

1. Customize the appearance of the payment page

Insert your store logo image and choose a background color. Click Salvar.

2. Set up sending the checkout confirmation email to the shopper

If you don’t want your end customer to receive an order completion email after payment, disable this option. Then click on Salvar.

3. Define the desired payment methods

Select the payment methods you would like to make available to your customers. For credit card, also choose the maximum number of installments allowed. Then click Salvar.

Warning

• To use boleto, request authorization to the E-commerce Support;
• The number of installments chosen by payment methods must be the same as that shown in your Cielo registration. Consult the E-commerce Support if you have any questions.

Enabling Pix on the Cielo portal
To use Pix, your registration must be enabled with the Pix payment method. To confirm the qualification, access the Cielo portal and click on Meu Cadastro > Authorizações > Pix.
If Pix is not enabled in your registration, the adding screen will be displayed if your establishment (EC) is eligible; after completing the Pix adding process, it will be possible to use Pix at Checkout Cielo.

For more details see the Link de Pagamento and Checkout Cielo tutorial.

4. Configure your store’s return, notification, and status change URLs

You will be asked to fill in the return, notification, and status change URLs. URLs must be created and defined by the merchant. Then click on Salvar.

• Return URL: after completing the payment, the shopper can be redirected to a web page defined by the store. No data is exchanged or sent to this URL and its configuration is optional;
• Notification URL: is the URL through which you will receive the notification with all the cart data when the transaction is completed;
• Status Change URL: is the URL through which you will receive notification when an order has its status changed. The status change notification does not contain cart data, only order identification data.

5. Configure Capture and Antifraude

When accessing your store’s settings, look for the Antifraude and automatic capture section. Select the desired option:

• Nunca fazer a Captura Automática (Never do the Automatic Capture);
• Sempre fazer Captura Automática (Always do Automatic Capture);
• Somente fazer captura Automática das transações de Baixo Risco no Antifraude. (Only automatically capture Low Risk transactions in Antifraude)

6. Configure Correios shipping options

If your store works with the delivery of physical products (those that need shipping), enter your Correios login and password and select the desired services, such as the types of Sedex and PAC.

If your store works with digital materials, services or payments, that is, sales that do not require shipping, skip this step.

Default settings

If you don’t fill in the Store Settings, Link de Pagamento will default to the following:

• The option of sending e-mail to the shopper will be turned on;
• The option to accept international cards will be on;
• The minimum installment amount will be R$5.00;
• Credit and debit payment methods will have 12 installments enabled (if your Cielo registration allows it);
• The QR Code Credit payment method will have an installment enabled;
• The ticket will not have a defined minimum value or discount (zeroed);
• The Always do Automatic Capture option will only be enabled for transactions that are not considered high risk;
• Correios shipping login will be disabled.

Test Mode

Sandbox

As it is a non-financial request, the Link de Pagamento API does not have a Sandbox to test the creation of links. Links must be created from the production environment. Accreditation can be done through the cielo website or through the ecommerce center.

Suporte Cielo E-commerce

cieloecommerce@cielo.com.br

+55 11 4002-5472

0800 570 8472

Financial tests can be performed by activating the test mode in your store settings.

Enabling Test Mode

Test mode can be activated in the Settings tab by enabling the Test Mode checkbox. Test mode will only start when the selection is saved.

When the option is saved, a red stripe will appear at the top of the screen. It will be displayed on all Link de Pagamento screens.

This stripe indicates that your store is now operating in a test environment, that is, all transactions carried out in this mode will be considered as a test.

Test Transactions

All transactions carried out in test mode will be displayed as normal transactions on the Cielo Checkout Orders tab, however, they will be marked as test transactions and will not be counted together with transactions carried out outside the test environment.

These transactions will have the test symbol differentiating them from your other transactions. They can be captured or canceled using the same procedures as for real transactions.

WARNING: When opening your store for sales to your customers, make sure Test Mode is disabled.
Transactions carried out in Test Mode can be finalized normally, but will not be deducted from the customer’s card and cannot be “transferred” to the standard sales environment.

How to make a transaction on test mode

After activating test mode, transactions are carried out normally. The creation of the link can be done using the same parameters as in the production environment, however, the payment methods to be used will be simulated methods.

To carry out test transactions with different payment methods, follow these rules:

Credit or debit card transactions

To test credit or debit cards, it is necessary to use a card that follows the Luhn algorithm and has the final number corresponding to the desired authorization status of the card (see details in the table below).

Credit or debit card authorization status

Example: 5404434242930100 = Authorized

Boleto

Simply carry out the purchase process normally without any changes to the procedure. The boleto generated in test mode will always be a simulated boleto.

Endpoints

The endpoints for integration with Link de Pagamento are presented in the following table:

Important: The Link de Pagamento API does not have a sandbox, but you can create test links by activating Test Mode on the Cielo website.

Transactions created with Test Mode enabled can be queried by the Transactional Control API.

Cielo OAUTH Authentication

Cielo OAUTH is an authentication process for Cielo APIs related to e-commerce. Cielo OAUTH uses the OAUTH2 protocol as security, in which it is first necessary to obtain an access token using your credentials and then send it to the Link de Pagamento API.

To use Cielo OAUTH the following credentials are required:

To generate the Client ID and Client Secret, see Obtaining the Credentials topic below.

Obtaining the credentials

To obtain the ClientId and ClientSecret credentials for authentication in the Link de Pagamento API, follow the steps below:

1. After receiving the establishment number (EC) with Link de Pagamento enabled, access the Cielo website and log in;
2. Go to the Ecommerce tab > Link de Pagamento > Configurações > Dados Cadastrais;
3. In the Contato técnico section, fill in the contact details of the person responsible for receiving the keys to your store. ATTENTION: only enter the data of the person who can actually have access to the keys to your store, which are confidential information for each establishment;
4. Click on Gerar Credenciais de Acessos às APIs;
5. You will receive an email with the credentials

Obtaining the access token

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

1. Concatenate the Client Id and Client Secret, **ClientId:ClientSecret**
2. Encode the result in Base64
3. Send the token creation request, using the HTTP POST method.

Concatenation Example

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 contain the access_token, which should be used in Link de Pagamento API requests.

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

The token returned (access_token) must be used in every request to the Link de Pagamento API as an authorization key. The access_token has a validity of 20 minutes (1200 seconds) and it is necessary to generate a new token every time the validity expires.

Payment Link

Creating a Link

To create a payment link, send a POST with product or service data.

Request

Header: Authorization: Bearer {access_token}

{
  "type": "Digital",
  "name": "Pedido",
  "description": "teste description",
  "price": "1000000",
  "weight": 2000000,
  "expirationDate": "2027-06-19 16:30:00",
  "maxNumberOfInstallments": "1",
  "quantity": 2,
  "sku": "teste",
  "shipping": {
    "type": "WithoutShipping",
    "name": "teste",
    "price": "1000000000"
  },
  "recurrent": {
    "interval": "Monthly",
    "endDate": "2024-02-06"
  },
  "softDescriptor": "Pedido1234"
}

Product data

Inside description you can use the pipe character | if you need to break the line when presenting the description on the payment link screen.

Shipping data

The data that must be filled in regarding shipping are in the shipping node.

Recurrence data

The recurrent node contains payment recurrence information. It can be informed if the product type (type) is “Recurrent”.

Response

The response will return the payment link in the shortUrl field and the id of the link, which can be used to query, update or delete the link.

“HTTP Status”: 201 – Created

{
  "id": "529aca91-2961-4976-8f7d-9e3f2fa8a0c9",
  "shortUrl": "http://bit.ly/2smqdhD",
  "type": "Asset",
  "name": "Pedido ABC",
  "description": "50 canetas - R$30,00 | 10 cadernos - R$50,00",
  "showDescription": false,
  "price": 8000,
  "weight": 4500,
  "shipping": {
    "type": "Correios",
    "originZipcode": "06455030"
  },
  "recurrent": {
    "interval": "Monthly",
    "endDate": "2024-02-06"
  },
  "softDescriptor": "Nome da Loja",
  "expirationDate": "2024-06-30T16:30:00",
  "maxNumberOfInstallments": 2,
  "links": [
    {
      "method": "GET",
      "rel": "self",
      "href":
        "https://cieloecommerce.cielo.com.br/Api/public/v1/product/529aca91-2961-4976-8f7d-9e3f2fa8a0c9"
    },
    {
      "method": "PUT",
      "rel": "update",
      "href":
        "https://cieloecommerce.cielo.com.br/Api/public/v1/product/529aca91-2961-4976-8f7d-9e3f2fa8a0c9"
    },
    {
      "method": "DELETE",
      "rel": "delete",
      "href":
        "https://cieloecommerce.cielo.com.br/Api/public/v1/product/529aca91-2961-4976-8f7d-9e3f2fa8a0c9"
    }
  ]
}

The data returned in the response includes all data sent in the request and additional data regarding the creation of the link.

Querying a Link

To consult an existing link, just perform a GET informing the id of the link.

Important: The query response contains the link itself (shortUrl) and the same data returned when creating the link.
The link is not the transaction yet. A transaction will only be initiated when the shopper attempts payment and may or may not be authorized.
To query a transaction, see the section Transaction Query.

Request

Header: Authorization: Bearer {access_token}

Response

HTTP Status: 200 – OK

{
  "id": "529aca91-2961-4976-8f7d-9e3f2fa8a0c9",
  "shortUrl": "http://bit.ly/2smqdhD",
  "type": "Asset",
  "name": "Pedido ABC",
  "description": "50 canetas - R$30,00 | 10 cadernos - R$50,00",
  "showDescription": false,
  "price": 8000,
  "weight": 4500,
  "shipping": {
    "type": "Correios",
    "originZipcode": "06455030"
  },
  "softDescriptor": "Pedido1234",
  "expirationDate": "2024-06-30 16:30:00",
  "maxNumberOfInstallments": 2,
  "links": [
    {
      "method": "GET",
      "rel": "self",
      "href":
        "https://cieloecommerce.cielo.com.br/Api/public/v1/products/529aca91-2961-4976-8f7d-9e3f2fa8a0c9"
    },
    {
      "method": "PUT",
      "rel": "update",
      "href":
        "https://cieloecommerce.cielo.com.br/Api/public/v1/products/529aca91-2961-4976-8f7d-9e3f2fa8a0c9"
    },
    {
      "method": "DELETE",
      "rel": "delete",
      "href":
        " https://cieloecommerce.cielo.com.br/Api/public/v1/products/529aca91-2961-4976-8f7d-9e3f2fa8a0c9"
    }
  ]
}

Updating a Link

To update an existing link, just make a PUT request, informing the id of the link.

You can update a link to change the payment method, insert a new item in the order, change the order description or change the type of recurrence, for example.

Request

Header: Authorization: Bearer {access_token}

{
  "Type": "Asset",
  "name": "Pedido ABC",
  "description":
    "50 canetas - R$30,00 | 10 cadernos - R$50,00 | 10 Borrachas - R$10,00",
  "price": 9000,
  "expirationDate": "2024-06-30 16:30:00",
  "weight": 4700,
  "sku": "abc123456",  
  "shipping": {
    "type": "FixedAmount",
    "name": "Entrega Rápida",
    "price": 1000
  },
  "SoftDescriptor": "Pedido1234",
  "maxNumberOfInstallments": 2
}

Response

HTTP Status: 200 – OK

{
  "id": "529aca91-2961-4976-8f7d-9e3f2fa8a0c9",
  "shortUrl": "http://bit.ly/2smqdhD",
  "type": "Asset",
  "name": "Pedido ABC",
  "description":
    "50 canetas - R$30,00 | 10 cadernos - R$50,00 | 10 Borrachas - R$10,00",
  "showDescription": false,
  "sku": "abc123456",
  "price": 9000,
  "weight": 4700,
  "shipping": {
    "type": "FixedAmount",
    "name": "Entrega Rápida",
    "price": 1000
  },
  "softDescriptor": "Pedido1234",
  "expirationDate": "2024-06-30 16:30:00",
  "maxNumberOfInstallments": 2,
  "links": [
    {
      "method": "GET",
      "rel": "self",
      "href":
        "https://cieloecommerce.cielo.com.br/Api/public/v1/products/529aca91-2961-4976-8f7d-9e3f2fa8a0c9"
    },
    {
      "method": "PUT",
      "rel": "update",
      "href":
        "https://cieloecommerce.cielo.com.br/Api/public/v1/products/529aca91-2961-4976-8f7d-9e3f2fa8a0c9"
    },
    {
      "method": "DELETE",
      "rel": "delete",
      "href":
        "https://cieloecommerce.cielo.com.br/Api/public/v1/products/529aca91-2961-4976-8f7d-9e3f2fa8a0c9"
    }
  ]
}

Attention: The query response contains the same data returned when creating the link.

Deleting a Link

To delete an existing link just perform a DELETE informing the Id of the link.

Request

Header: Authorization: Bearer {access_token}

Response

HTTP Status: 204 – No Content

Recurrence

Recurrence is an automatic scheduling process for credit transactions, that is, it is a transaction that will be repeated automatically, without the need for the shopper to access the transactional screen, in accordance with the rules defined at the time of scheduling.

If one of the transactions is not authorized, Checkout Cielo automatically retrys; for more details about automatic retry, see the Recurrence Retry section

Recurring transactions are ideal for business models that involve the concept of subscription, plan or monthly fee in their form of billing, such as:

• Schools;
• Gyms;
• Publishers;
• Hosting services.

The recurring transaction is different from an installment transaction. In the recurring transaction, the limit of the customer’s card is only committed by the amount of the subscription in the chosen period, that is, if it is monthly, only the amount of the monthly fee on the customer’s card will be committed. -Insurance subscription in the amount of R$ 100.00 and with monthly billing for one year: every month, only R$ 100.00 of the card limit will be committed.

In the installment transaction, the limit committed on the customer’s card is the It is the total amount of the sale, regardless of the amount of the value of each installment. -Sale of a refrigerator in the amount of R$ 2000.00 in 10 installments of R$ 200.00: the entire amount of the purchase will be committed - (R$ 2000.00) - even if only R$ 200.00 per month is charged on the customer’s card statement.

Creating a recurring Payment Link

A recurring Payment Link has two settings: Interval and End date.

• Interval: repetition pattern and time interval between each transaction. This time interval between transactions can be monthly, bimonthly, quarterly, semi-annual and annual;
• End date: date on which the recurrence process stops occurring.

}, 

  "recurrent": { 

    "interval": "Monthly", 

    "endDate": "2024-02-06" 

  }, 

The shopper’s credit card data is stored securely at Cielo, allowing it to be reused in a recurring transaction. This data is not accessed by the retailer and this intelligence is controlled by Link de Pagamento Cielo.

Request

{ 

  "OrderNumber": "123456",   

  "type": "Digital", 

  "name": "Pedido", 

  "description": "teste description", 

  "price": "1000000", 

  "weight": 2000000, 

  "expirationDate": "2027-06-19", 

  "maxNumberOfInstallments": "1", 

  "quantity": 2, 

  "sku": "teste", 

  "shipping": { 

    "type": "WithoutShipping", 

    "name": "teste", 

    "price": "1000000000" 

  }, 

  "recurrent": { 

    "interval": "Monthly", 

    "endDate": "2024-02-06" 

  }, 

  "softDescriptor": "Pedido1234" 

Example: physical asset

If the product type is physical asset (Cart.Items.Type = “Asset”), the API requires the shipping type (Shipping.Type) to be sent.

If there is a recurrence node in the technical contract, it is required to send the type WithoutShipping, otherwise the following response will be presented:

{ 

  "message": "The request is invalid.", 

  "modelState": { 

    "[Shipping.Type]": [ 

      "[Shipping.Type] pedidos com recorrência devem possuir o Shipping.Type 'WithoutShipping'." 

    ] 

  } 

} 

Important: The recurrence is only created if the transaction is authorized. Regardless of capture or not, once authorized, the recurrence process begins.

Recurrence Retry

If one of the recurrence transactions is not authorized, Checkout Cielo automatically performs the retry, sending a new transaction, considering:

• Time interval between attempts: four days;
• Number of retries: four retries, one per day, for four calendar days from the day following the original unauthorized transaction.

Note: This process aims to obtain a positive response from the authorization process, preventing the retailer from losing the sale. The retry process generates duplicate orders within the Backoffice, as the original denied order will be displayed in the Orders list, along with the new authorized transaction.

Attention: The retry rule cannot be modified by the merchant.

It is possible to query and cancel recurring transactions on the Cielo website.

Altering recurrence data

To change recurrence data, access the Cielo website, where you can change:

• Interval: interval between transactions;
• Recurrence day: day of the recurring transaction;
• Date of next transaction: date on which the next transaction will be made, following the configured interval setting and the day of recurrence;
• Recurrence value: value of the recurring charge on the shopper’s card;
• Recurrence end date: date on which the recurrence is deactivated.
  

These changes can be made through two channels. Check below what they are and the respective guidelines:

• Cielo website (manual alteration): Access the Cielo Checkout Backoffice Tutorial for more information.
• Link de Pagamento API (integrated alteration): follow the steps below to send recurrence edit requests in an integrated manner via the Link de Pagamento API.

Integrated alteration

To change data from a recurrence using the Link de Pagamento API, simply send a request with the information to be changed. Check out an example of this request.

Request

Parameters in the header

• Authorization: Bearer {access_token}
• Content-type: application/json

{ 

  "PagadorRecurrentPaymentId": "0207CE76-8144-48DC-8B17-876465BC3A6D", 

  "EndDate": "2030-12-31", 

  "Interval": 1, 

  "NextPaymentDate": "2024-12-31", 

  "Amount": "33333.33", 

  "Day": "31" 

} 

Response

HTTP Status: 200 - OK

{ 
" Recurrent Payment - {id} Updated Successfully" 
}

Querying a recurrence

To query the data for a recurrence and the transactions linked to it, you must use the recurrence ID sent after creating a recurrence.

The query must be made by sending the access_token as authentication.

Request

Parameters in the header

• Authorization: Bearer {access_token}
• Content-type: application/json

Response

{ 

    "$id": "1", 

    "id": 202, 

    "pagadorRecurrentPaymentId": "0207ce76-8144-48dc-8b17-876465bc3a6d", 

    "recurrentPaymentStatus": 1, 

    "recurrentPaymentStatusEnum": 1, 

    "isRecurrentPaymentExpired": false, 

    "allowEdit": true, 

    "startDate": "2024-02-05T15:05:44.423", 

    "endDate": "2026-03-30T00:00:00", 

    "formatedEndDate": "30/03/2026", 

    "day": 10, 

    "items": [ 

        { 

            "$id": "2", 

            "name": "teste leo", 

            "quantity": 1, 

            "unitPrice": 1000, 

            "totalPrice": 1000, 

            "formattedUnitPrice": "R$ 10,00", 

            "formattedTotalPrice": "R$ 10,00" 

        } 

    ], 

    "item": { 

        "$ref": "2" 

    }, 

    "history": [ 

        { 

            "$id": "3", 

            "orderId": "c748ef42-d1e7-4db3-9633-8d057bf874b0", 

            "orderNumber": "8245e94dcf4c4de3906118e38f376822", 

            "merchantOrderNumber": "12345", 

            "createdDate": "2024-02-05T15:05:44.457", 

            "paymentStatus": 7, 

            "paymentStatusDescription": "Autorizado" 

        } 

    ], 

    "lastPaymentDate": "0001-01-01T00:00:00", 

    "nextPaymentDate": "2026-02-05T00:00:00", 

    "formatedNextPaymentDate": "05/02/2026", 

    "intervalDescription": "Mensal", 

    "recurrentPaymentStatusDescription": "Ativa", 

    "amount": 4000.0 

}

Deactivating a recurrence

To deactivate a recurrence, send the following request.

Request

Parameters in the header

• Authorization: Bearer {access_token}
• Content-type: application/json

It is not necessary to send any parameters in the body.

Transaction notifications

The transactional notification process takes place in two steps, which are transaction completion notification and status change notification.

*Notifications are sent to the URLs defined by the establishment in [Store Settings] and contain data on transactions carried out through the Link de Pagamento.

It is worth noting that Link de Pagamento notifies only when a transaction is considered finalized, that is, the shopper has filled in all the details on the payment screen and clicked on Finalize.

Example: The shopper accesses the payment link and chooses to pay via Pix. When you click Finalize, Link de Pagamento generates the Pix key and sends the transaction completion notification to the store, which will have the status “Pendente (Pending)”. When the shopper makes the payment via Pix, the transaction will have the status “Pago (Paid)” and Link de Pagamento will send the status change notification.

Notification features

Notification URLs are webhooks that can receive a notification via POST or via JSON:

Format of notifications

In notifications supported by the Link de Pagamento API, the format sent is Form Data, broken down by the Content-Type header ‘x-www-form-urlencoded’.

Expected return

The store’s server must return HTTPStatus = 200 (OK) to the Link de Pagamento API, indicating that the notification was successfully received and processed.

IMPORTANT: If the registered URL returns an error or is unavailable, three new attempts will be made, with an interval of one hour between each POST.

If the notification is not received, it is possible to manually request a resend in Detalhes do Pedido (Order details), by clicking on the arrow icon.

Transaction completion notification

It is the notification sent to the Notification URL and can be in POST or JSON format.

Notification via POST

Contains all transaction data, including merchant_order_number and checkout_cielo_order_number, which can be used to query a transaction.

Example:

order_number: "40e00eefbf094763a147af713fa07ece",
amount: "5000",
checkout_cielo_order_number: "b9ab1956738d45cc88edf51d7d03b13e",
created_date: "02/02/2023 17:01:35", 
customer_name: "nome do cliente", 
customer_phone: "2222222222", 
customer_identity: "12312312344", 
customer_email: "nome@email.com.br", 
shipping_type: "5", 
shipping_price: "0", 
payment_method_type: "6", 
payment_installments: "1", 
payment_status: "1", 
test_transaction: "False", 
product_id: "0f48e580-d0a2-4e3b-a748-6704927f1725", 
product_type: "3", 
product_description: "123", 
nsu: "00339922"

See the description of transaction details in the Notification Content section.

Notification via JSON

Notification via JSON is a safer and more flexible method to perform a query on Link de Pagamento Cielo. In this mode, the store receives the MerchantId and the MerchantOrderNumber and a URL to perform a query (GET) against the Link de Pagamento Cielo database and access transaction details.

Notification content via JSON

MerchantId: "799g0de8-89c3-5d17-c670-6b29d7f00175", 
MerchantOrderNumber: "1db9226geg8b54e6b2972e9b745b89c7", 
Url: "https://cieloecommerce.cielo.com.br/api/public/v1/orders/799g0de8-89c3-5d17-c670-6b29d7f00175 /1db9226geg8b54e6b2972e9b745b89c7"

The store’s server must send the return HTTP Status = 200 (OK) to the Link de Pagamento API, indicating that the notification was received and processed successfully.

Example of a query to the URL returned via JSON

Response

{
    "order_number": "1db9226geg8b54e6b2972e9b745b89c7",
    "amount": 101,
    "discount_amount": 0,
    "checkout_cielo_order_number": "65930e7460bd4a849502ed14d7be6c03",
    "created_date": "10-03-2023 14:38:56",
    "customer_name": "Test Test",
    "customer_phone": "11987654321",
    "customer_identity": "445556667",
    "customer_email": "shopper@email.com.br",
    "shipping_type": 1,
    "shipping_name": "Motoboy",
    "shipping_price": 1,
    "shipping_address_zipcode": "06455-030",
    "shipping_address_district": "Alphaville",
    "shipping_address_city": "Barueri",
    "shipping_address_state": "SP",
    "shipping_address_line1": "Alameda Xingu",
    "shipping_address_line2": "Apto 25",
    "shipping_address_number": "512",
    "payment_method_type": 1,
    "payment_method_brand": 1,
    "payment_maskedcreditcard": "482852******6856",
    "payment_installments": 1,
    "payment_status": 3,
    "tid": "10558590697J62OH9BPB",
    "test_transaction": "False"
}

See the description of the sale details in the Notification Content section.

Notification Content

Both in the notification via POST or via JSON, the content of the returned data is the same. All returned fields are described below, as well as their definitions and sizes:

Types of productID

Payment_status

Link de Pagamento has its own status, different from the Cielo website or the Cielo E-commerce API. See the complete list below.

Note: For order inquiries, the payment.status field will be returned in text format, always in English (Transaction Status column).

Payment_antifrauderesult

Antifraude has the concept of Status and SubStatus, where the first represents the risk level that a transaction has of being a fraud, and the second, additional information about the transaction.

Payment_method_type

Link de Pagamento allows only one type of Boleto per establishment, so the notification does not return if the provider used was Bradesco or Banco do Brasil, as only one of them will be active in the affiliation.

Note: For queries the Type is returned in the Payment.Type field and is filled with the literal value (Description).

Payment_method_brand

It’s the brand of the card.

In queries, the card brand is returned in the Payment.Brand field and is filled with the literal value.

Payment_method_bank

Shipping_type

Status change notification

It is sent to the status change URL and contains the checkout_cielo_order_number, the new status and some transaction data.

To find out more details about the transaction, make a query using checkout_cielo_order_number.

The status change notification format is POST (form data).

checkout_cielo_order_number: "b918afea483d4c6c8615d8a8e19803c1",
amount: "134",
order_number: "024f77ac98cb493b86d8c818eb6e79cd",
payment_status: "3",
test_transaction: "False",
brand: "Visa",
nsu: "000001",
authorization_code: "01234567"

Transaction Query

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

The control of orders originating from a payment link can be done through the Transactional Control API. Querying orders can be done in three different ways:

• By order_number;
• By checkout_cielo_order_number;
• By id of the payment link.

By order_number

Querying transactions by order_number returns a list of transactions with the same number of orders; this occurs because the Link de Pagamento does not prevent the duplication of order_numbers by the store. The response will return the checkout_cielo_order_number, which should be used when querying a specific transaction.

Request

To query a transaction by order_number, do a GET.

Response

[
    {
        "$id": "1",
        "checkoutOrderNumber": "a58995ce24fd4f1cb025701e95a51478",
        "createdDate": "2023-03-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": "2023-03-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 via Checkout Cielo Order_Number, just do a 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": "Alameda Xingu", 
            "number": "512", 
            "complement": "21 andar", 
            "district": "Alphaville", 
            "city": "Barueri", 
            "state": "SP" 
        } 
    }, 
    "payment": { 
        "status": "Paid", 
        "tid": "10127355487AK2C3EOTB",
        "nsu": "149111",
        "authorizationCode": "294551",
        "numberOfPayments": 1,
        "createdDate": "2023-03-02T14:29:43.767",
        "finishedDate": "2023-03-02T14:29:46.117",
        "cardMaskedNumber": "123456******2007",
        "brand": "Visa",
        "type": "creditCard",
        "errorcode": "00",
        "antifraud": { 
            "antifraudeResult": 1,
            "description": "Risco Baixo" 
        } 
    }, 
    "customer": { 
        "identity": "12345678911", 
        "fullName": "Nome do comprador", 
        "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 id of the Link de Pagamento

Request

To query a transaction by id, just do a GET.

Header: Authorization: Bearer {access_token}

Resposta

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

To carry out queries via the Transactional Control API on Link de Pagamento Cielo, it is required that the merchant has configured one of the two notification models:

• Transaction Notification URL via POST or
• Transaction Notification URL via JSON.

It is required to have provided a transaction notification URL as the transaction query data will be sent in the notification content.

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

Status and Codes

Link de Pagamento has its own status, different from the Cielo website or the API Cielo E-commerce. See the full list below.

Card Brands Retry Program

When a shopper tries to make a card purchase on e-commerce, the transaction may be denied due to several reasons. The next attempts to complete the transaction using the same card are called retrying.

How retrying works

The denied transactions were classified as irreversible (never retry) and reversible (retry allowed).

The card brands determine if they will charge a fee for retrying and how many retry attemps are allowed before applying charges. The merchants who do not follow the card brand rules will be penalized by charging fees for exceeded transactions.

Please refer to Card Brands Retry Program manual to see each card brand rules.

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.

Antifraude Status