Requerimentos para acesso

Para acesso a APIs é necessário abrir um ticket via Zendesk, informando o nome do responsável técnico, e-mail, nome, função e qual o aplicativo que realizará a integração.

Macro fluxo de integração

Atualmente dentro da API de pagamentos existem três recursos utilizados para a integração, sendo eles:

Fluxo de Integração QR Code

Ambientes

Ambiente Endereço Descrição
Homologação api2.cielo.com.br/sandbox Deve ser utilizado como o ambiente de desenvolvimento/testes de parceiro.
Produção api2.cielo.com.br Deve-se utilizar quando portar as credenciais de produção e um bom nível de maturidade com o ambiente de homologação.

Access Token

O recurso access_token é responsável pela autenticação utilizando protocolo OAuth 2.0. Com o client_id e client_secret em mãos a requisição ao POST /access_token deve ser feita portando o authorization no Header e o grant_type no corpo da requisição, segue exemplo abaixo.

Nota: O valor do authorization deve ser composto da palavra Basic com o Base64 gerado a partir da concatenação do client_id:client_secret

Contrato

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

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

Headers

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

Body

{
"grant_type": "client_credentials"
}

Exemplo de Requisição


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"
}

Exemplo de Resposta


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

Public Keys

Public keys é o recurso responsável por retornar a chave pública da criptografia utilizada para criptografar o número do cartão, que futuramente será enviado no corpo da requisição do recurso payment/card. O algoritmo de criptografia utilizada é RSA de 2048 bits e cifra RSA/ECB/PKCS1Padding. Para a requisição ao recurso GET /publicKeys é necessário o access_token que foi gerado no passo anterior.

Contrato

GET /padraoq/v1/publicKey

Headers

Key Value
Authorization Bearer = access_token (gerado pela API de Access Token)

Exemplo de Requisição


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

Exemplo de Resposta


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

Criptografia

Exemplo de código Java para criptografar o número do cartão usando uma 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

O recurso POST /payment/card é responsável por efetuar o pagamento com base nos dados contidos no payload da requisição. No header da requisição é necessário informar o Authorization. O corpo da requisição é composto por dados provenientes do aplicativo e do QR Code.

Observação: é possível gerar cartões para teste através da ferramenta (https://namso-gen.com/), para isso é necessário apenas informar os 6 primeiros dígitos de um cartão válido. Através da ferramenta (https://8gwifi.org/RSAFunctionality?keysize=2048), é possível simular a criptografia do "card_data" feita utilizando o retorno obtido do GET /publicKeys.

Contrato

POST /cielo-payment/v1/payments

Headers

Key Value
Authorization Bearer = access_token (gerado pela API de Access Token)
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"
}
Propriedade Descrição Tipo Tamanho Obrigatório
key_id Identificador da chave de criptografia utilizada para criptografar o cartão. Retornado pelo recurso GET /publicKey Texto alfanumérico   Sim
card_data Dados do cartão criptografado pela chave publica, Veja layout Texto alfanumérico   Sim
payee_document CPF ou CNPJ do pagador (usuário logado na wallet) Texto   Sim
payee_name Nome do pagador (usuário logado na wallet) Texto   Sim
authorization_token Token de autorização do usuário gerada pelo emissor (suporte ao pagamento no débito) * para uso futuro Texto alfanumérico   Sim
qrcode String do QR Code capturado pela wallet Texto alfanumérico   Sim

Exemplo de Requisição


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"
}'

Exemplo de Resposta


{
  "reference_label": "30012036995B2230",
  "merchant_id": "0020060049139200",
  "terminal_id": "00090233",
  "authorization_code": "900735",
  "authentication_code": "",
  "host_nsu": "",
  "terminal_nsu": "997482",
  "timestamp": "208720164223",
  "card_scheme": ""
}
Propriedade Descrição Tipo Tamanho Obrigatório
reference_label        
merchant_id Número do estabelecimento      
terminal_id Número lógico do POS      
authorization_code        
authentication_code        
host_nsu Número Sequencial Único      
terminal_nsu Número Sequencial Único      
timestamp        
card_scheme        

Layout - Card Data

Layout Card Data

Parsed - QR Code

Uso opcional

Request

GET /padraoq/v1/parsedQRCode

Headers

Key Value
Authorization Bearer = access_token (gerado pela API de Access Token)
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"
    }
  }
}
Propriedade Descrição Tipo Tamanho Obrigatório
payload_format_indicator Versão dos dados do QR Code utilizada na geração do código. Fixo “01”. Número 02  
point_of_initiation_method Identificador do método QR Code gerado: Fixo “12” – QR Code Dinâmico. Número 02  
gui Identificador global: usar fixo “br.com.padraoq”. Texto alfanumérico 14  
id_merchant Número do Estabelecimento Comercial. Número 16  
id_terminal Número Lógico do Terminal Número 08  
id_credenciador Identificação do credenciador. Fixo “0001”. Número 04  
merchant_category_code Ramo de atividade do Estabelecimento (MCC). Número 04  
transaction_currency Código de origem da Moeda. Número 03  
transaction_amount Valor da transação. Ex: “123.99” Texto 13  
merchant_name Nome Fantasia do Estabelecimento. Texto 25  
merchant_city Cidade do Estabelecimento. Texto 15  
reference_label Identificação do QR Code. Código único da transação, extraído BIT31. Texto 25  
crc16        
gui Identificador global: usar fixo “br.com.padraoq”. Texto 14  
timestamp Data e hora da transação (DDMMAAHHmmss). Número 12  
modalidade Código do produto Matriz. Número 04 Sim
parcelas Número de parcelas. Número 02  
tipo_de_transacao Tipo da transação: Exemplo - “01” – Venda; “02” – Cancelamento. Número 02  
fonte_de_dados_do_pagamento Fixo: “03” – QR Code Número 02  

Como obter o POS de homologação.

Para a obtenção do POS de homologação deve-se abrir chamado via Zendesk.

API de Callback (desfazimento)

Existe uma API de callback para enviar informações sobre as transações de desfazimento, que pode ocorrer no fluxo de transações entre o POS e a plataforma do sistema de autorização.

Será necessário com que o parceiro desenvolva uma API de retorno de chamada para receber as informações sobre aa transações de desfazimento e encaminhar a URL(endpoint) para nossa equipe através do Zendesk. Lembrando que a API de Callback deve ser gerada no formato restfull.

Requisição

{
   "transactionDate": "2018-10-29T14:35:12.000+0000",
   "terminalLogicalNumber": "78257509",
   "authorizationCode": "019387",
   "nsu": "572061",
   "merchantId": 1000000000,
   "amount": 82.90,
   "originalTransactionType": 1,
   "statusCode": 3
}
Propriedade Descrição Tipo Tamanho Obrigatório
transactionDate Data da transação (extraída do QRCode) Texto 36 Sim
terminalLogicalNumber Número lógico do POS Texto 40 Sim
authorizationCode Código de autorização da transação Texto alfanumérico 6 Sim
nsu Número Sequencial Único Texto 50 Sim
merchantId Identificador da loja na Cielo (extraído do QRCode) String 36 Sim
amount Valor da transação Número 15 Sim
originalTransactionType Transação de origem. Comunica o desfazimento de uma transação do /payments. Número 1 Sim
statusCode 1 - Pagamento / 2 - Cancelamento / 3 - Desfazimento - Quando desfazimento - statusCode = 3 Número 1 Sim

Bandeiras e Formas de Parcelamento

A versão atual da API de QRCode possui suporte às seguintes bandeiras e formas de parcelamento:

Bandeira À vista Parcelado Loja Parcelado Emissor Parcelado Cliente
Visa Sim Sim Sim Sim
Mastercard Sim Sim Sim Sim
Elo Sim Sim Sim Sim
American Express Sim Sim Sim Não
Diners Club Sim Sim Sim Não
JCB Sim Sim Sim Não
Banescard Sim Sim Sim Não
Hipercard Sim Sim Sim Não

Cartões emitidos no exterior não possuem permissão de parcelamento.
A solução de pagamento QR Code Cielo atualmente não aceita pagamentos no débito.

Códigos da API

Erros da API

Código Descrição Modelo
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”}

Erros de Pagamento

Código Mensagem Descrição completa
412.001 O produto não foi encontrado Erro de negócio referente a problemas com o produto informado.
412.002 QR Code Inválido Erro de negocio referente a problemas nos dados do QR Code enviado.
412.003 QR Code Expirado Erro de negócio referente à expiração do tempo de validade do QR Code.
412.004 Dados de cartão invalido Erro de negócio referente a problemas nos dados do cartão informado.
412.005 Não aceitamos pagamento com o cartão cadastrado Erro de negócio referente a aceitação do cartão cadastrado.
412.006 Erro no autorizador/emissor Problemas com a criptografia do cartão. Lembrando que o ambiente sandbox verifica a validade dos cartões, com isso, deve ser informado um cartão valido.
412.007 Erro genérico Problemas com a criptografia do cartão. Lembrando que o ambiente sandbox verifica a validade dos cartões, com isso, deve ser informado um cartão valido.

Canal de Suporte a Dúvidas

Caso ainda tenha dúvidas deve-se abrir um chamado via Zendesk.

Documentações e tutoriais
Contato
GitHub