Documentação APIs Promo

Cielo Promo

Cielo Promo is a Cielo service that aids merchants to sell more. Using this promotional platform the client can advertise their business, attract new customers and business opportunities, as well as build customer loyalty or motivate them to come back to their shop.

Promotional mechanics

Main promotional mechanics

API’s terms and definitions:

OAuth2: it’s an authorization protocol for web API’s set to allow client applications access to a protected resource in the name of an authorized partner or user.
client_id: partner identification attributed by Cielo.
client_secret: partner authentication key attributed by Cielo. This information should not be shared and needs to be stored in a safe location.
access_token: token to access the resources of a Cielo provided API using OAuth2 flow.

API Promotions:

API Promotions is a connector that allows integration and information sharing between Cielo and partners.

How to test APIs

1 Access credentials to API Promotion:

Who is it for: All partners

Step by step

1.1 Obtain client_id and client_secret with Cielo.

Example:

client_id: 1H5ffBGkL1sO7mUySNwpTf8YBnd7kjRkw7GUj55rFiJ36h3zlz o
client_secret: 0AqcqzQ54hCSKMs5yJMRNBeYvybetTDQ5GpBteQzd6B0vkHvc7

1.2 With client_id e client_secret in hands, it’s generated a unique key for the partner that’s called at the Authorization request. To obtain this key it’s necessary to convert the credentials (Client ID and Client Secret) into base64.

Example:

1H5ffBGkL1sO7mUySNwpTf8YBnd7kjRkw7GUj55rFiJ36h3zlz o : 0AqcqzQ54hCSKMs5yJMRNBeYvybetTDQ5GpBteQzd6B0vkHvc7

Using a base64 converter we obtain our key as the example below:

MUg1ZmZCR2tMMXNPN21VeVNOd3BUZjhZQm5kN2tqUmt3N0dVajU1ckZpSjM2aDN6bHogbzowQXFjcXpRNTRoQ1NLTXM1eUpNUk5CZVl2eWJldFREUTVHcEJ0ZVF6ZDZCMHZrSHZjNw==

1.3 With our Authorization it’s possible to make our first Cielo access Token generation call, using the URL: https://api.cielo.com.br/v2/oauth/access-token

At the request is necessary to put some parameters at the header and body

At the header it’s necessary to put the Authorization with the value “Basic + generated credential in base64” as well as the Content –Type in Application/json format

t the Body it’s necessary to put the following json structure:

{
“grant_type”: “Client_credentials”
}

After running the request the following response will appear:

{ 
    "access_token": "awQIVTM7A03PMqU1Q9PbgpXmD5ZKIhtIYOnKGuTtr6X1VBmpCv", 
    "token_type": "bearer", 
    "expires_in": 3600 
}

With this generated Access token the partner can access the API Promotion and its resources for an hour. After this time, it will be necessary to create a new Access token, flowing the same process and using the same credentials.

2 Card sending script (TAG):

Who is it for: Partners that will send cardholder lists

Step by step

2.1 Access the “Access Token”

2.2 Access the “Headers” field and inform in the Authorization

Example:

: Basic cExCNXZ2eWdFemN1bEtJVlpwbE5iVUhoTm9BbTBTQlJzWGVTZUZMV0ZZUzNETmkwZFE6ZjI3M FRwQjRjSGhTSUs5d0gyMTRNcEhzbkJXQUt2RkFpVjRRQU1TS0l1d211WENQSzc)

2.3 Click “Send” Token successfully generated. Copy the generated Token at the request response

2.4 Access “Get /public-Keys: https://api.cielo.com.br/sandbox/promotions-api/v1/public-keys”

2.5 Inform the Token generated in step 2.3 at the “Headers” of the Get /public-Keys API.

2.6 Click “Send” and the Public-Key will be generated

2.7 If you already have a card skip to 2.8. Or access the link below and create a test card (https://www.4devs.com.br/gerador_de_numero_cartao_credito)

2.8 Open the file below “EncriptarCartão” to create the encrypted card.

2.9 Inform the Public-Key generated on step 2.6 > and then the card number > click “Encrypt-me” to encrypt the card.

2.10 Access “POST /tokens” inform in the “Headers” the Token generated on step 2.3 > “Body” inform the encrypted card > “Send”

2.11 Acesse “POST /tags{tagID}/card” informe no “Headers” o Token gerado no passo 3 > “Body” informa o cartão criptografado > “Send” > Card registered in Tag “conforme tag informado pela Cielo”

Make a transaction with a value multiple of $10,00

3 Card to coupon registering script:

Who is it for: Partners that will send a cardholder list and have campaigns that use coupons

Step by step

3.1 Access the “Access Token”

3.2 Access the bracket “Headers” inform at the Authorization

Example:

: Basic cExCNXZ2eWdFemN1bEtJVlpwbE5iVUhoTm9BbTBTQlJzWGVTZUZMV0ZZUzNETmkwZFE6ZjI3M FRwQjRjSGhTSUs5d0gyMTRNcEhzbkJXQUt2RkFpVjRRQU1TS0l1d211WENQSzc)

3.3 Click “Send” Token successfully generated. Copy the Token generated at the request response

3.4 Access “Get /public-Keys: https://api.cielo.com.br/sandbox/promotions-api/v1/public-keys”

3.5 rm the Token generated on step 3.3 at the “Headers” of the Get /public-Keys API.

3.6 Click “Send” and the Public-Key will be generated

3.7 If you already have a card skip to step 3.8. Access the link below and generate a test card (https://www.4devs.com.br/gerador_de_numero_cartao_credito)

3.8 Open the file below “EncriptarCartão” to generate an encrypted card.

3.9 Inform the Public-Key generated on step 3.6 > then the card number > click “Encrypt-me” to encrypt the card.

3.10 Acesse “POST /tokens” inform at the “Headers” the Token generated on step 3.3 > “Body” inform the encrypted card > “Send”. The response of the API will generate a field called “id” that is the encrypted card identification.

Access “POST /Coupons/{couponID}/cards” inform at “Headers” the Token generated on step 3.3 > “Body” inform the “id” from step 3.10 at the request body, and at the couponID pathparam it’s necessary to inform the campaign number you wish to attach to the card.
As a response the API will inform and ID of the registration of the card as well as the partner informations.

Make a transaction with a value multiple of $10,00

4 Notification script:

Who is it for: All partners

4.1 Inform to Cielo which URL will receive the notification, along with access validation information for that address.

It is important to highlight that our notification API (Webhook) is limited to a single call, so any security flow that demand a previous call will have to be treated with the Cielo Promo team so that the notification is effectively made.

4.2 Notification structure:

{  
   "eventOwners":[  
      "xxxxxxx" (partner name) - (Tam = 100 )
   ],
   "eventType":"eventtype1",(internal event type) - (Fixo Tam = 10)
   "eventCreateDate":"2019-05-09T10:26:51.150",(event date) - (Tam = 23)
   "eventDetails":{  
      "transactions":[  
         {  
            "status":"undone", (transaction status ex: approved, cancelled, undone) - (Tam Max = atual 8, mas é variável)
            "value":"4000,00", (original value) - (Tam = 18) (15 characters a to the left plus comma and 2 more characters to the right)
            "affiliate":{  
               "terminal_id":"48129900", (terminal number) - (Tam = 8)
               "order_id":768479, (document number) - (Tam = 8)
               "partner_id":"12312222200001" (MERCHANT CPF OR CNPJ) - (Non specified, value filled by external service)


            },
            "customer":{  
               "customer_id":"1903451233" (client unique code, can be a CPF or other identification) - (Tam = 36)
            },
            "payments":{  
               "currency":"BRL", (currency) - (Fixo Tam = 3),
               "value":"3900,00", (discounted value) - (Tam = 18) (15 characters a to the left plus comma and 2 more characters to the right)
               "bin":45567 (bin) - (Tam = 6),
              "card_id":"" (card identification) - (Tam = 36 )
            },
            "transaction_id":376, (transaction identification) - (Tam = 10)
"created_at":"2019-05-24T16:35:56"(date and time of notification) - (Tam = 19)
"promotion_id":"928912" (campaign identification) - (Tam = 10)
“coupon_id” (Non mandatory to partners that don’t use coupons) - (Tam = 10)

         }
      ]
   }
}

5 EC to campaign subscription script:

Who is it for: All partners

5.1 Create a request to POST at the URL “https://api.cielo.com.br/oauth/access-token”

5.2 Add a field at the request’s header called “Authorization” in which the value will be the junction of the word “Basic” plus an empty space and the partners authorization.

Example:

Basic cExCNXZ2eWdFemN1bEtJVlpwbE5iVUhoTm9BbTBTQlJzWGVTZUZMV0ZZUzNETmkwZFE6ZjI3M FRwQjRjSGhTSUs5d0gyMTRNcEhzbkJXQUt2RkFpVjRRQU1TS0l1d211WENQSzc

Run the request and the response will be the token that must be saved to perform the operation.

Example:

{
    "access_token": "BxZ5r8arQudlCruHlN8o0LZE1UIsPbZPJGKMUqLpauQ4lUzaZQ",
    "token_type": "access_token",
    "expires_in": 3600
}

5.4 Create a POST request at the URL “https://atpperioldeuccoam.cielo.com.br/partner-promo/partner-promo/v1/promotions/{promotionID}/merchants” where the promotionID will be the promotion ID.

Example:

https://atpperioldeuccoam.cielo.com.br/partner-promo/partner-promo/v1/promotions/547305/merchants

5.5 Create the following fields in the request’s header:

partnerID: will be the partner’s ID;
Authorization: The value will be the union of the word “Bearer” with a blank space and the token generated on step 5.3.
Example:
“Bearer BxZ5r8arQudlCruHlN8o0LZE1UIsPbZPJGKMUqLpauQ4lUzaZQ”
Content-Type: Inform the value “application/json”

5.6 At the request’s body it should be informed a JSON informing the ECs that will be subcribed to the campaign. Example:

{
		"merchants":["9999999998"]
}

5.7 Run the request and the response will be registration information.

Example:

{
    "merchants": [
        "9999999998"
    ],
    "promotionID": 547305,
    "statusMerchants": "Subscription"
}

6 Unsub script of EC in the campaign:

Who is it for: All partners

Resume: a process to remove merchants from a currently campain.

6.1 Create a requisition POST at URL “https://api.cielo.com.br/oauth/access-token”

6.2 Add a field in the requisition header named “Authorization” where the value has to be the connection of the word “Basic” + a blank character + the partner authorizer.

Example:

Basic cExCNXZ2eWdFemN1bEtJVlpwbE5iVUhoTm9BbTBTQlJzWGVTZUZMV0ZZUzNETmkwZFE6ZjI3M FRwQjRjSGhTSUs5d0gyMTRNcEhzbkJXQUt2RkFpVjRRQU1TS0l1d211WENQSzc

6.3 Run the request and the return will be the token which must be saved to perform the operation.

Example:

{
    "access_token": "BxZ5r8arQudlCruHlN8o0LZE1UIsPbZPJGKMUqLpauQ4lUzaZQ",
    "token_type": "access_token",
    "expires_in": 3600
}

6.4 Create a DELETE request in the URL “https://atpperioldeuccoam.cielo.com.br/partner-promo/partner-promo/v1/promotions/{promotionID}/merchants” where the promotionID will be the ID of the promotion.

Example:

https://atpperioldeuccoam.cielo.com.br/partner-promo/partner-promo/v1/promotions/547305/merchants

6.5 Create the following fields in the request header:

partnerID: The ID used by the partner;
Authorization: Will be the union of the word “Bearer” + a blank character + the token generated at step 3.
Example:
“Bearer BxZ5r8arQudlCruHlN8o0LZE1UIsPbZPJGKMUqLpauQ4lUzaZQ”
Content-Type: inform the value “application/json”

6.6 At the request, a JSON must be informed informing the ECs that they will be unlinked from the campaign.

Example:

{
		"merchants":["9999999998"]
}

6.7 Run the requisition and the return will be the status 204.

7 Cashback integration script:

7.1 The Merchant contracts a campaign with the Promotions partner. The partner offer the promotions on their channels (such as app and website). The partner must contact Cielo to request the promotion tag. The promotion tag is a unique code generated only once and that information will be used in the API call using it as the path in the call.

7.2 The user access the partner channels, chose the promotion and register the card to enjoy the promotion. The partner must perform the request below:

Ask for an access token at Cielo Oauth API by POST operation: https://api.cielo.com.br/sandbox/v2/oauth/access-token (*)

Use the token to call the operation POST https://api.cielo.com.br/sandbox/promotions-api/v1/public-keys da promotions-api para obter a chave pública de encriptação que será utilizada para criptografar o cartão do usuário.

Use the token to call the operation POST https://api.cielo.com.br/sandbox/promotions-api/v1/tokens da promotions-api para adicionar um cartão criptografado pela chave pública na plataforma de promoções. Como confirmação de sucesso vai receber o ID de token deste cartão.

Use the token to call the operation POST https://api.cielo.com.br/sandbox/promotion-apis/v1/tags/{tagDePromocaoInformadaPeloBackoffice}/cards da promotions-api para a associar o ID de token de cartão a tag de promoção que o Parceiro combinou com o time da Cielo no Passo 1.

7.3 User goes to the Commercial Establishment participating in the promotion and makes a purchase on the Cielo machine. The purchase must be made with the card previously added to make the payment at the Cielo machine.

7.4 The receipt is printed with a message informing that the user has received the points / cashback. Parallel to confirmation, Cielo’s plataforma sends to the partner service http POST (URL defined on item 4 – notification) a message containing the data of the rewarded transaction. Through this confirmation, the partner is able to credit and deliver the benefit (points / cashback) to the cardholder.

8 Geolocation API – Integration script

Who is it for: Partners using only the geolocation API

Resume: The Geolocation API shows latitude and longitude coordinates that inform which campaigns are registered in a geographic region.

The API Swagger has the complete package, with all services. Below is a print of how the file appears when opened in Swagger's editor:

Fill the bracket "partnerID" with the API by the client_id.

8.1 Swagger – test enviroment: http://10.82.251.112:9137/partner-promo/api-promo-parceiro-merchant/swagger-ui.html#/Merchant/promotionsMerchantsGeolocationsGet

8.2 Copy the Hyaku Token: Authorization: xxxxxxxxx

8.3 Access the Postman and choose the Environment PRD_Acess-Token:

8.4 Access “POST Acess Token”:

8.5 Paste the Token (Authorization) copied on step 1:

8.6 Click on Send and copy the access_token:

8.7 Change the Environment to PRD_API:

8.8 Open the Geolocation (Geolocalização) service:

8.9 Paste the access_token (Bearer) copied on step 5 on “Authorization:

8.10 Click on Send and wait for the process:

FAQ

Any questions about the integration process? Check our pages below:

https://desenvolvedores.cielo.com.br/api-portal/

https://www.cielo.com.br/venda-mais/cielopromo/

or send us a message:

cielopromo@cielo.com.br

Language

English

Português
English

Documentação APIs Promo

Search form

Cielo Promo

Promotional mechanics

Main promotional mechanics

API’s terms and definitions:

API Promotions:

How to test APIs

1 Access credentials to API Promotion:

2 Card sending script (TAG):

3 Card to coupon registering script:

4 Notification script:

5 EC to campaign subscription script:

6 Unsub script of EC in the campaign:

7 Cashback integration script:

8 Geolocation API – Integration script

FAQ

About Sensedia

Main menu

Like Us On Facebook

Nossas soluções

Desenvolvedores

Suporte

Documentação APIs Promo

Search form

You are here

Cielo Promo

Promotional mechanics

Main promotional mechanics

API’s terms and definitions:

API Promotions:

How to test APIs

1 Access credentials to API Promotion:

2 Card sending script (TAG):

3 Card to coupon registering script:

4 Notification script:

5 EC to campaign subscription script:

6 Unsub script of EC in the campaign:

7 Cashback integration script:

8 Geolocation API – Integration script

FAQ

About Sensedia

Main menu

Like Us On Facebook

Nossas soluções

Desenvolvedores

Suporte