Environments

Access requirements

For the use of our APIs we need to receive the following information, for the creation of the client id and Authorization

• Name
• E-mail
• Occupation
• Who will be responsible for the integration (Technical Responsible) to register in API Suite?

Information we will send:

After sending the above information, we will send the client_id (key that identifies the APP) and the client_secret to the person in charge.

Any questions, open a ticket with our Developer Experience team Zendesk

Authentication

Access Token generation flow (via JSON format)

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/access-token (format json)

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
}

Access Token generation flow (via format x-www-form-urlencoded)

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

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/sandbox/v2/oauth/token' \
--header 'Authorization: Basic
dERxQUs0anFoSDg5dFdpUWM1ejY0REJKc2lJTFpLbzh4TG0zV0p3eHkwRkQ0Y2dZVm46
ZVZUVVZJZjFZWDJkOU40M0p4MVZwNGlWVXEzTzluTTR0TGF1UzhZYWo0V1JPcTJFSXU
=' \
--header 'Content-Type: application/json' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'scopes=qrcode_write,qrcode_read'

Response Example

{
"access_token": "8d9529bd-3dcf-3130-82ea-d28712f96de2",
"token_type": "bearer",
"expires_in": 86400
}

API return codes

SUCCESS

Code	Nome	Description
200	Ok	The request was successful for an API call, either GET or POST .
201	Created	The create request was successful for an API call of type POST

EXCEPTIONS

Code	Nome	Description
400	Bad Request.	* The request is not valid. One or more conditions in the request fields were not met List of unmet conditions
401	Unauthorized	API Consumer Authentication Failed
403	Forbbiden	API consumer does not have access to certain features
409	Conflict	Resubmission of the request with divergent information. (Ex: Request for payments with different CPF)
412	Precondition Failed	001: Expired key 002: Expected dynamic QRCode
422	Unprocessable Entity	The request is valid, but it was not possible to process.
500	Internal Server Error	Internal application error. Usually coming from infrastructure

Public key generation

The partner needs to call the API/publicKey to get the public key needed to send the card data in encrypted form.

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);
        }
    }
}

Payment flow

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 /padraoq/v1/payment/card

Headers

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

{
   "key_id":"string",
   "card_data":"string",
   "payee_document":"string",
   "payee_name":"string",
   "authorization_token":"string",
   "qrcode":"string"
}

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": "001",
    "card_data": "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAmeiLngFr9h0npwe6D3ArSi10ZgdOCUCsUYT12KMuYsxImzwe9aGX8XXvzEF60E600ZjdvmYU64UnZKgfbttwNi+Tl7ZcB2cnS/oJMrfA0AbRHukJnL/fFsziHOjv0A1xRcE0ZbJRkob5A5s4GenF+jv/xCTOoIetFimZHZDiPPFux2NyrL3ZqSs7F4XJZvo2zPfCVlAcnEbVf+8vWX3goP2TEuAqZtBT543wIDAQAB+dqSzZSqZolYU1sjV7s8FzsjZYqo+AjM8BMuPlMoPEuBqgRFm4fSRIpeJIr0G9FokSU3X6MAZTC7n3YePHFsFmGxPTrKpEFrp8s28f1qMP5suTsA”,,
    "payee_document": "25617535811",
    "payee_name": ""Alexandre Marcelino",
    "authorization_token": null,
    "qr_code": ""00020101021226580014br.com.padraoq01160010000244470001020862000092030400015204030053039865406123.995802BR5909POSTO_ABC6010Barueri_SP62200516100023071641629281600014br.com.padaoq0112230120171643020400040302020402010502038204010063
041213""
}'

Response Example

{
  "reference_label": "230120171643",
  "merchant_id": "0020060049139200",
  "terminal_id": "62000092",
  "authorization_code": "031581",
  "authentication_code": "null",
  "host_nsu": "730025",
  "terminal_nsu": "730025",
  "timestamp": "160620143832",
  "card_scheme": "Master"
}

Layout - Card Data

Note: Encrypt all “cardData” tag information including the quotes “ { } “.

{
   "card_number":"4984XXXXXX4106",
   "card_cvv":"123",
   "card_holder_name":"Teste",
   "card_expiration_date":"0127"
}

Payment success codes

Code	Name	Description
200	Ok	The request was successful for an API call, either GET or POST .

Payment error codes

Error	Code	Error	Description
422	001	The product was not found	Business error regarding problems with the reported product
422	002	Invalid QRCode	Business error regarding problems in QRCode data sent
422	003	QRCode expired	Business error regarding QRCode expiration time
422	004	Invalid Card Data	Business error referring to problems with the card data entered
422	005	We do not accept payments with the registered card	Business error regarding the acceptance of the registered card
422	006	Error in authorizer	Business error returned from issuer authorizer
422	007	Generic Error	Other Business Mistakes

API to parse the QR Code (optional use))

Contract

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"

body:

<body empty>

Response

{
   "qrcode_data":{
      "payload_format_indicator":"01",
      "point_of_initiation_method":"12",
      "merchant_account_information":{
         "gui":"br.com.padraoq",
         "id_merchant":"1234567890123456",
         "id_terminal":"12345678",
         "id_credenciador":"1234",
         "instituicao":"12345678",
         "tipo_de_conta":"1234",
         "agencia":"12345678",
         "conta":"12345678901234567890"
      },
      "merchant_category_code":"0000",
      "transaction_currency":"986",
      "transaction_amount":"01.00",
      "country_code":"BR",
      "merchant_name":"Q Café",
      "merchant_city":"Brasilia",
      "additional_data_field":{
         "reference_label":"reference label"
      },
      "crc16":"AC05",
      "unreserved_templates":{
         "gui":"br.gov.bcb.spi",
         "url_uri":"https://br.gov.bcb.spi/"
      },
      "payment_information":{
         "gui":"br.com.padraoq",
         "timestamp":"010220120001",
         "modalidade":"0400",
         "parcelas":"01",
         "tipo_de_transacao":"01",
         "fonte_de_dados_do_pagamento":"03",
         "campo_livre":"1234567890"
      }
   }
}

QR CODETM POS GENERATED LAYOUT (NEW BR CODE +ELO MODEL)

The data used to generate the QRCode for reading in the digital wallet must follow as a basis the specification “EMVCo-Merchant-Presented-QR-Specification-v1” using the data below:

Ex.:

Data:

00020101021226760014br.com.padraoq0116123456789012000102082009130003040001041 40306501400093927580010BR.COM.ELO010483840215234567890120001030820091300040 1P520400005303986540525.005802BR5905CIELO6014SANTOANDRE SP61080600000062200516040310245460330981740014br.com.padraoq01120203211002180 20400020302010402010502030606069646500082560010BR.COM.ELO011003021002180203 C0003020104060696460801363044847

QRCODE:

QR CODETM POS GENERATED LAYOUT (NEW BR CODE MODEL)

The data used to generate the QRCode for reading in the digital wallet must follow the specification “EMVCo-Merchant-Presented-QR-Specification-v1” using the data below:

Ex:

DATA:

00020101021226760014br.com.padraoq0116001000024447000102086200009203040001041 4010270580001915204030053039865406123.995802BR5909POSTO_ABC6010Barueri_SP6220 0516100023071641629281720014br.com.padraoq011223012017164302040004030202040201 05020306020050020063040CE6

QR CODE:

Map TAGs generated in a transaction via QRCode:

00020101021226760014br.com.padraoq0116001000024447000102086200009203040001041 4010270580001915204030053039865406123.995802BR5909POSTO_ABC6010Barueri_SP6220 0516100023071641629281720014br.com.padraoq011223012017164302040004030202040201 05020306020050020063040CE6

QR CODETM POS GENERATED LAYOUT (OLD MODEL)

The data used to generate the QRCode for reading in the digital wallet must follow as a basis the specification “EMVCo-Merchant-Presented-QR-Specification-v1” using the data below:

00020101021226410005Cielo011600100002444720100208201000015204591 2530398654120000000010005802765923CIA BRAS MEIO PAGAMENTO6009SAO PAULO801010033”https://www.cielo.com.br/qrcode”01161209676128919 232021210041809451203041000040400010502010602016304**A177**

CALLBACK API FOR UNDO (optional use)

There is a call-back API to inform the wallet of a defect

The partner needs to develop an API to receive the undo information following the format below and providing the url to send the information:

Body:

{
"transactionDate": "string",
"terminalLogicalNumber": "string",
"authorizationCode": “string",
"nsu": "string",
“merchantId“: 0,
“amount“: 0,
“originalTransactionType”: 0,
“statusCode“: 0
}

API request (example):

{
"transactionDate": "2018-10-29T14:35:12.000+0000",
"terminalLogicalNumber": "78257509",
"authorizationCode": "019387",
"nsu": "572061",
“merchantId“: 1000000000,
“amount“: 82.90,
“originalTransactionType”: 1,
“statusCode“: 3
}