Access requirements

To access the APIs, it’s necessary to open a ticket via Zendesk, informing the name of the responsible technician, e-mail, name, function and which application will perform the integration.

Macro flow integration

Currently within the payments API there’re three resources used for integration, being them:

QR Code Integration Flow

Environments

Environment Address Description
Homologation api2.cielo.com.br/sandbox It should be used as the partner development/testing environment.
Production api2.cielo.com.br It must be used when carrying the production credentials and a good level of maturity with the approval environment.

Access Token

The access_token resource is responsible for authentication using the OAuth 2.0 protocol. With client_id and client_secret in hand the request to POST / access_token must be done by carrying authorization in Header and grant_type in the body of the request, following example below.

Note: The authorization value must be composed of the word Basic with Base64 generated from the client_id concatenation: client_secret

Contract

POST /v2/oauth/token (url encoded format)

POST /v2/oauth/access-token (json format)

Headers

Key Value
Authorization Basic + Base64
Content-Type application-json

Body

{
"grant_type": "client_credentials"
}

Request Example

curl --location --request POST 'https://api2.cielo.com.br/v2/oauth/access-token' \
--header 'Authorization: Basic
dERxQUs000FoSDg5dFdpUWM1ejY0REJKc2lJTFpLbzh4TG0zV0p3eHkwRkQ0Y2dZVm46ZVZUVVZJZjFZWDJkOU40M0p4MVZwNGlWVXEzTzluTTR0TGF1UzhZYWo0V1JPcTJFSXU=' \
--header 'Content-Type: application/json' \
--data-raw '{
 "grant_type": "client_credentials",
"scopes": "qrcode_write,qrcode_read"
}

Response Example

{
  "access_token": "5eb50e6b-2bfc-3a44-b9ba-b9ba75256e7e",
  "token_type": "bearer",
  "expires_in": 86400
}

Public Keys

Public keys is the resource responsible for returning the public encryption key used to encrypt the card number, which will be sent in the body of the resource request payment/card in the future. The encryption algorithm used is RSA 2048 bits and cipher RSA / ECB / PKCS1Padding. To request the GET / publicKeys resource, the access_token that was generated in the previous step is required.

Contract

GET /padraoq/v1/publicKey

Headers

Key Value
Authorization Bearer = access_token (generated by the Access Token API)

Request Example

curl --location --request GET 'https://api2.cielo.com.br/sandbox/padraoq/v1/publicKey' \
--header 'Authorization: Bearer 83247803-585d-379d-8ea4-19dfcf4c3f75'

Response Example

{
    "public_key": "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAmH7eS0n6yQSylMDZnY3c/mbDUUEJfyslrilslJKpDRG3m2YaCZdtwo5LahEUWshhBc8jckRkCyqDVVfBJ7WQN1Z1hN0ifCK8mfnh/2SAYGc4e8qydcWT64AVQo+Kay201cRuHeCt1Iyuhi5tOxTF2satd40+8eMkqiVJdhJ0Sjc1ZRezFSo96XReiT8eYz/4Rhubq1BPISlNXqqls3NuPMCxY6IFOLmjTi3xEIdcYtUT5MCfXBG4Rz6rMNrQ7JRAfEOIdvcAt++ygV9ilUxtETn+OKKNDcEUKzXM3Taop8vFXD8HWKzfmlA/usxeKxiI6eTrcWCmrVMQ2Yvf4RSU4wIDAQAB",
    "key_id": "1b59934a-7eaa-4f90-a391-585de0ffc550",
    "expires_in": 35853
}

Cryptography

Example Java code to encrypt the card number using a public key:

import java.security.PublicKey;
import java.util.Base64;
import javax.crypto.Cipher;
public class EncriptCard {
    public String encript(PublicKey key, String cardNumber) {
        try {
            Cipher cipher = Cipher.getInstance("RSA");
            cipher.init(Cipher.ENCRYPT_MODE, key);
            byte[] encryptedBytes =
                cipher.doFinal(cardNumber.getBytes());
            String encryptedCard =
                Base64.getEncoder().encodeToString(encryptedBytes);
            return encryptedCard;
        } catch (Exception e) {
            throw new RuntimeException(e);
        }
    }
}

Payments

The POST /payment/card resource is responsible for making the payment based on the data contained in the requisition payload. In the request header it’s required to inform Authorization.

The request body consists of data from the application and the QR Code.

Note: it’s possible to generate test cards using the tool (https://namso-gen.com/), for this it’s only required to inform the first 6 digits of a valid card. Through the tool (https://8gwifi.org/RSAFunctionality?keysize=2048), it’s possible to simulate the encryption of the "card_data" made using the return obtained from GET / publicKeys.

Contract

POST /cielo-payment/v1/payments

Headers

Key Value
Authorization Bearer = access_token (generated by the Access Token API)
Content-Type application/json
{
    "key_id": "1b59934a-7eaa-4f90-a391-585de0ffc550",
    "card_data": "liRNW6uKAbB95ht2gmLg+LdYRZuAzredVeJkKpJsVSUABak2828xennWNjySFJlvNL9LXBv7adGddr7oM6rqoTGo+NLt/rpyosT9Gl4mvPmSFyNe+bMd7bPht2PKfnyWH4skP6lSuxqusq5bcPbapO8i9Fe8rSY+msNBTTywu02hYym6FD6MVgZe2dewpH39DfjTTtF9ck5rJlCYje3Jqfh3gUnLU6+6s7kliuKrbb5Z66y5BwQ9HFyF92mJYWilCYSEc5aqB9zcs7ij+B4yo8uMo8uBscJ+e15M2ESURdn/HMkehNggvqQBydtF+IJZqGo5jT/DI8LbhAG9WuyeAA==",
    "payee_document": "10771410093",
    "payee_name": "Maria Aparecida",
    "authorization_token": null,
    "qr_code": "00020101021226580014br.com.padraoq0116002006784913920002080004351503040001520400005303986540518.005802BR5918MASSA DADOS AFIL. 6012SAO PAULO SP6220051638021736126C351181600014br.com.padraoq01121702201614140204100003020104020105020382006304C7FE"
}
Property Description Type Required
key_id Identifier of the encryption key used to encrypt the card. Returned by the GET /publicKey resource Alphanumeric text Yes
card_data Card data encrypted by the public key, See layout Alphanumeric text Yes
payee_document CPF or CNPJ of the payer (user logged in the wallet) Text Yes
payee_name Payer name (user logged into the wallet) Text Yes
authorization_token User authorization token generated by the issuer (support debit payment) * for future use Alphanumeric text Yes
qrcode QR Code string captured by the wallet Alphanumeric text Yes

Request Example

curl --location --request POST 'https://api2.cielo.com.br/sandbox/padraoq/v1/payment/card' \
--header 'Authorization: Bearer 83247803-585d-379d-8ea4-19dfcf4c3f75' \
--header 'Content-Type: application/json' \
--header 'Content-Type: application/json' \
--data-raw '{
    "key_id": "1b59934a-7eaa-4f90-a391-585de0ffc550",
    "card_data": "liRNW6uKAbB95ht2gmLg+LdYRZuAzredVeJkKpJsVSUABak2828xennWNjySFJlvNL9LXBv7adGddr7oM6rqoTGo+NLt/rpyosT9Gl4mvPmSFyNe+bMd7bPht2PKfnyWH4skP6lSuxqusq5bcPbapO8i9Fe8rSY+msNBTTywu02hYym6FD6MVgZe2dewpH39DfjTTtF9ck5rJlCYje3Jqfh3gUnLU6+6s7kliuKrbb5Z66y5BwQ9HFyF92mJYWilCYSEc5aqB9zcs7ij+B4yo8uMo8uBscJ+e15M2ESURdn/HMkehNggvqQBydtF+IJZqGo5jT/DI8LbhAG9WuyeAA==",
    "payee_document": "10771410093",
    "payee_name": "Maria Aparecida",
    "authorization_token": null,
    "qr_code": "00020101021226580014br.com.padraoq0116002006784913920002080004351503040001520400005303986540518.005802BR5918MASSA DADOS AFIL. 6012SAO PAULO SP6220051638021736126C351181600014br.com.padraoq01121702201614140204100003020104020105020382006304C7FE"
}'

Response Example

{
  "reference_label": "30012036995B2230",
  "merchant_id": "0020060049139200",
  "terminal_id": "00090233",
  "authorization_code": "900735",
  "authentication_code": "",
  "host_nsu": "",
  "terminal_nsu": "997482",
  "timestamp": "208720164223",
  "card_scheme": ""
}
Property Description Type Size Required
reference_label        
merchant_id Establishment number      
terminal_id POS logical number      
authorization_code        
authentication_code        
host_nsu Unique Sequential Number      
terminal_nsu Unique Sequential Number      
timestamp        
card_scheme        

Layout - Card Data

Layout Card Data

Parsed - QR Code

Optional use

Request

GET /padraoq/v1/parsedQRCode

Headers

Key Value
Authorization Bearer = access_token (generated by the Access Token API)
Content-Type application/json

Parameter: 

qrcode:"00020101021226580014br.com.padraoq011600100002444700010208620000920304000152040
30053039865406123.995802BR5909POSTO_ABC6010Barueri_SP622005161000230716416292816000
14br.com.padraoq0112230120171643020400040302020402010502038204010063041213"

Response


{
  "qrcode_data": {
    "payload_format_indicator": "01",
    "point_of_initiation_method": "12",
    "merchant_account_information": {
      "gui": "br.com.padraoq",
      "id_merchant": "0020128328439200",
      "id_terminal": "21832843",
      "id_credenciador": "0001"
    },
    "merchant_category_code": "0000",
    "transaction_currency": "986",
    "transaction_amount": "6.00",
    "country_code": "BR",
    "merchant_name": "MASSA DADOS AFIL. ",
    "merchant_city": "SAO PAULO SP",
    "additional_data_field": {
      "reference_label": "12050C0415690978"
    },
    "crc16": "B8B0",
    "payment_information": {
      "gui": "br.com.padraoq",
      "timestamp": "120520162558",
      "modalidade": "1000",
      "parcelas": "01",
      "tipo_de_transacao": "01",
      "fonte_de_dados_do_pagamento": "03"
    }
  }
}

Property Description Type Size Required
payload_format_indicator Version of the QR Code data used to generate the code. Fixed “01”. Number 02  
point_of_initiation_method Identifier of the generated QR Code method: Fixed “12” - Dynamic QR Code. Number 02  
gui Global identifier: use a fixed “br.com.padraoq”. Alphanumeric text 14  
id_merchant Commercial Establishment Number. Number 16  
id_terminal Logical Terminal Number Number 08  
id_credenciador Identification of the creditor. Fixed “0001”. Number 04  
merchant_category_code Branch of activity of the Establishment (MCC). Number 04  
transaction_currency Currency source code. Number 03  
transaction_amount Transaction amount. Ex: “123.99” Text 13  
merchant_name Established Trade Name. Text 25  
merchant_city Establishment City. Text 15  
reference_label QR Code identification. Unique transaction code, extracted from BIT31. Text 25  
crc16        
gui Global identifier: use a fixed “br.com.padraoq”. Text 14  
timestamp Transaction date and time (DDMMAAHHmmss). Number 12  
modalidade Matrix product code. Number 04 Sim
parcelas Number of parcels. Number 02  
tipo_de_transacao Transaction type: Example - “01” - Sale; “02” - Cancellation. Number 02  
fonte_de_dados_do_pagamento Fixed: “03” - QR Code Number 02  

How to obtain the homologation POS.

To obtain the homologation POS, it is necessary to open a new request on [Zendesk] (https://devcielo.zendesk.com/hc/pt-br/requests/new?ticket_form_id=360000324432).

Callback API

There is a callback API to send information about undo transactions, which can occur in the transaction flow between the POS and the authorization system platform.

It will be necessary for the partner to develop a callback API to receive information about the undo transactions and forward the URL (endpoint) to our team through Zendesk. Remembering that the Callback API must be generated in the restfull format.

Request

{  
   "transactionDate": "2018-10-29T14:35:12.000+0000",
   "terminalLogicalNumber": "78257509",
   "authorizationCode": "019387",
   "nsu": "572061",
   "merchantId": 1000000000,
   "amount": 82.90,
   "originalTransactionType": 1,
   "statusCode": 3
}
Property Description Type Size Required
transactionDate Transaction date (extracted from QRCode) Text 36 Yes
terminalLogicalNumber POS logical number Text 40 Yes
authorizationCode Transaction authorization code Alphanumeric 6 Yes
nsu Unique Sequential Number Text 50 Yes
merchantId Cielo store identifier (extracted from QRCode) String 36 Yes
amount Transaction Amount Number 15 Yes
originalTransactionType Originating transaction. Reports the undo of an /payments transaction. Number 1 Yes
statusCode 1 - Payment / 2 - Cancellation / 3 - Undo - When Undo - statusCode = 3 Número 1 Yes

Brands and Payment Type

The current version of the QRCode API supports the following flags and installment forms:

Bandeira À vista Parcelado Loja Parcelado Emissor Parcelado Cliente
Visa Yes Yes Yes Yes
Mastercard Yes Yes Yes Yes
Elo Yes Yes Yes Yes
American Express Yes Yes Yes No
Diners Club Yes Yes Yes No
JCB Yes Yes Yes No
Banescard Yes Yes Yes No
Hipercard Yes Yes Yes No

Cards issued abroad are not allowed in installments. The QR Code Cielo payment solution does not currently accept debit payments.

API codes

API errors

Code Description Model
201 Created  
400 Bad Request. {“description”:”Error full description.”,”type”:”string”}
401 Unauthorized. {“description”:”Error full description.”,”type”:”string”}
403 Forbidden. {“description”:”Error full description.”,”type”:”string”}
404 Not Found. {“description”:”Error full description.”,”type”:”string”}
412 Precondition Failed. {“properties”:{“code”:{“type”:”string”,”description”:”Error code.”},”description”:{“type”:”string”,”description”:”Error full description.”}}}
413 Request Entity Too Large. {“description”:”Error full description.”,”type”:”string”}
415 Unsupported Media Type. {“description”:”Error full description.”,”type”:”string”}
422 Unprocessable Entity. {“properties”:{“code”:{“type”:”string”,”description”:”Error code.”},”description”:{“type”:”string”,”description”:”Error full description.”}}}
429 Too Many Requests. {“description”:”Error full description.”,”type”:”string”}
500 Internal Server Error. {“properties”:{“code”:{“type”:”string”,”description”:”Error code.”},”description”:{“type”:”string”,”description”:”Error full description.”}}}
502 Bad Gateway. {“description”:”Error full description.”,”type”:”string”}
504 Gateway Timeout. {“description”:”Error full description.”,”type”:”string”}

Payment Errors

Code Message Full description
412.001 The product was not found Business error regarding problems with the reported product.
412.002 Invalid QR Code Business error regarding problems in the sent QR Code data.
412.003 Expired QR Code Business error regarding the expiration of the QR Code validity time.
412.004 Invalid card data Business error referring to problems with the informed card data.
412.005 We do not accept payment with the registered card Business error regarding acceptance of the registered card.
412.006 Authorizer/issuing error Problems with card encryption. Remember that the sandbox environment verifies the validity of the cards, then, a valid card must be informed.
412.007 Generic error Problems with card encryption. Remember that the sandbox environment verifies the validity of the cards, then, a valid card must be informed.

Questions and Support Channel

If you still have any questions, you can open a request on [Zendesk] (https://devcielo.zendesk.com/hc/pt-br/requests/new?ticket_form_id=360000316152).