Ambientes

Requerimentos para acesso

Para a utilização de nossas APIs precisamos receber as seguintes informações, para a criação do cliente id e Authorization.

• Nome
• E-mail
• Função
• Quem será o responsável pela integração (Responsável Técnico) para cadastro no API Suite?

Informações que enviaremos:

Após o envio das informações acima, enviaremos ao responsável o client_id (chave que identifica a APP) e o client_secret.

Qualquer dúvida, abra um ticket via Zendesk

Autenticação

Fluxo de geração do Access Token (via format JSON)

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

Fluxo de geração do Access Token (via format x-www-form-urlencoded)

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

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/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'

Exemplo de Resposta

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

Códigos de retorno da API

SUCESSO

Code	Nome	Descrição
200	Ok	A solicitação foi bem sucedida para uma chamada da API, seja GET OU POST .
201	Created	A solicitação de criação foi bem sucedida para uma chamada da API do tipo POST

EXCEÇÕES

Code	Nome	Descrição
400	Bad Request.	* A requisição não é valida. Uma ou mais condições dos campos do request não foram atendidas Lista das condições não atendidas
401	Unauthorized	Falha na Autenticação do consumidor da API
403	Forbbiden	Consumidor da API não possui acesso a determinados recursos
409	Conflict	Reenvio da solicitação com informações divergentes. (Ex: Solicitação de pagamentos com CPF distintos)
412	Precondition Failed	001: Chave expirada 002: QRCode dinâmico esperado
422	Unprocessable Entity	A requisição é valida, porém não foi possivel realizar o processamento.
500	Internal Server Error	Erro interno da aplicação. Normalmente provinientes de infraestrutura

Geração da chave pública

O parceiro precisa chamar a API/publicKey para obter a chave pública necessária para o envio dos dados do cartão de forma criptografada.

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 do código Java para encriptrar o cartão através da chave pública:

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

Fluxo de pagamento

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

Headers

Key	Value
Authorization	Bearer = access_token (gerado pela API de Access Token)
Content-Type	application/json

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

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

Exemplo de Resposta

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

Observação: Encriptar todas as informações da tag “cardData” inclusive com as aspas “ { } “.

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

Códigos de sucesso Payment

HTTP STATUS CODE	Nome	Descrição
200	Ok	A solicitação foi bem sucedida para uma chamada da API, seja GET OU POST .

Códigos de erro Payment

Ao realizar uma requisição para algum dos recursos da API e os dados não forem satisfatórios para realizar o procedimento, será devolvido uma resposta contendo no corpo as seguintes informações:

{
    "code": "422.007",
    "description": "Generic error (0xd4596b31) "
}

Onde:
• code: Código de resposta interno da aplicação.
• description: Descrição sobre o problema encontrado no processo.

A tabela abaixo apresenta os possíveis cenários de validações realizados pela API durante o fluxo de pagamento.

HTTP STATUS CODE	CODE	DESCRIPTION	CAUSE(S)
400	412.101	O campo ‘key_id’ é obrigatório	O campo key_id enviado no body da requisição está em branco.
400	412.102	O campo ‘card_data’ é obrigatório	O campo card_data enviado no body da requisição está em branco.
400	412.104	O campo ‘qr_code’ é obrigatório	O campo qr_code enviado no body da requisição está em branco.
400	412.156	O CPF enviado não é válido	O campo payee_document enviado no body da requisição não é um CPF válido.
400	412.157	O CNPJ enviado não é válido	O campo payee_document enviado no body da requisição não é um CNPJ válido.
400	422.002	QRCode inválido	O QRCode informado contém campos em que o tamanho da posição está maior que a estabelecida pelo layout.
422	412.155	O documento do cliente não foi reconhecido. Ele dever ser um CPF ou CNPJ válido	O campo payee_document enviado no body da requisição não é um CPF ou CNPJ.
422	422.001	O produto não foi encontrado	A fonte de pagamento informada pela aplicação não foi mapeada.
422	422.002	QRCode inválido	A aplicação não pôde fazer o parse dos dados do QRCode.
			O QRCode informado contém campos em que a posição não existe no layout.
			Não foi encontrado o registro de geração do QRCode informado no banco de dados.
			O valor informado para o “Identificador do Pagamento” (reference label) é divergente do enviado na solicitação do pagamento.
			O valor informado para o “Valor da Transação” (transaction amount) é divergente do enviado na solicitação do pagamento.
			O valor informado para o “Número do Terminal Lógico” (id terminal) é divergente do enviado na solicitação do pagamento.
			O valor informado para a “Data da Transação” (transaction date) é divergente do enviado na solicitação do pagamento.
			O valor informado para o “Número do EC” (id merchant) é divergente do enviado na solicitação do pagamento.
			O valor informado para o “Nome do EC” (merchant name) é divergente do enviado na solicitação do pagamento.
			O valor informado para o “Código da Categoria do EC” (merchant category code) é divergente do enviado na solicitação do pagamento.
			O valor informado para o “Cidade do EC” (merchant city) é divergente do enviado na solicitação do pagamento.
			O valor informado para o NSU é divergente do enviado na solicitação do pagamento.
422	422.003	QRCode expirado	Ocorre quando a data de pagamento (timestamp) do QR Code excedeu o tempo limite de expiração.
422	422.004	Dados de cartão inválido	O campo card_number do cartão informado não é numérico.
			O campo card_holder_name do cartão informado está em branco.
			O campo card_expiration_date do cartão informado está em branco.
			O campo card_cvv do cartão informado contém mais de 4 caracteres.
			O campo card_expiration_date do cartão informado contém mês/ano menor que o atual.
			Ao realizar uma integração externa para tokenizar o cartão houve um problema.
422	422.006	Erro no autorizador ou emissor (código de retorno)	Ao realizar uma integração externa para efetuar o pagamento, ele não foi efetuado com sucesso. Obs.: A informação entre parênteses é o código retornado pelo sistema externo, identificando o problema.
422	422.007	Erro genérico (0xd4596b31)	O campo wallet enviado no header da requisição não foi encontrado no banco de dados.
		Erro genérico (0x868cb5bb)	As chaves de criptografia não foram encontradas no banco de dados.
		Erro genérico (0x14382170)	Não foi possível decodificar a chave pública.
			Não foi possível decodificar os dados do cartão.
		Erro genérico (0x7f4659a6)	Não foi possível descriptografar os dados do cartão, pois a chave pública ou privada é inválida.
		Erro genérico (0x342b3019)	Não foi possível descriptografar os dados do cartão.
		Erro genérico (0xf1fe2e5a)	A aplicação não pôde converter o JSON informado com os dados do cartão.
		Erro genérico (0x2b31d726)	O número do cartão informado corresponde ao BIN da Caixa, porém a carteira enviada no header da requisição não é Caixa.
		Erro genérico (0xd8dcc723)	A aplicação não pôde mapear o Tipo de Tecnologia informado.
		Erro genérico (0x3a1a3fb7)	A aplicação não pôde converter o JSON com os dados do cartão tokenizado.
		Erro genérico (0x2172d473)	Ao realizar uma integração externa para efetuar o pagamento houve um problema.
		Erro genérico (0x707a0b47)	A aplicação não pôde converter o CAVV (cipheredCryptogram) para o formato solicitado na integração externa.
		Erro genérico (0xddd30422)	A carteira digital da requisição é diferente da que negou o pagamento.
		Erro genérico (0xljg30422)	Já existe um pagamento sendo processado.
		Erro genérico (2eae5a3583)	Ao realizar uma integração externa para efetuar o pagamento foi retornado um erro.
		Erro genérico (0x27d48cd4)	Ao realizar uma integração externa para efetuar o pagamento foi retornado um erro.
		Erro genérico (0x3c10fed2)	Ao realizar uma integração externa para efetuar o pagamento foi retornado um erro.
500	422.007	Erro genérico (0x2429cb80)	O Tipo de Tecnologia informado pela aplicação não foi encontrado no banco de dados.
		Erro genérico (0x69ad89d4)	O Tipo de Transação informado pela aplicação não foi encontrado no banco de dados.
		Erro genérico (0x6f566831)	O status do pagamento informado pela aplicação não foi encontrado no banco de dados.
500	500.050	Erro interno de sistema	Não foi possível descriptografar a chave pública.
			Data/Hora de expiração da chave pública é menor que a atual.
			Não foi possível codificar a chave privada.
			A aplicação não pôde fazer o parse dos dados do QRCode.
			O valor informado no Point of Initiation Method (posição 01 do QRCode) não existe na aplicação.
			O Tipo de Transação informado pela aplicação não foi mapeado.

API para realizar parse do QR Code (uso opcional)

Contrato

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"

body:

<body vazio>

Response

Observação: stringQrCode está depreciado e será descontinuado.

{
   "stringQrCode": null,
   "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 LAYOUT GERADO PELO POS (MODELO NOVO BR CODE +ELO)

Os dados usados para gerar o QRCode para leitura na carteira digital deve seguir como base a especificação “EMVCo-Merchant-Presented-QR-Specification-v1” utilizando os dados abaixo:

Ex.:

DADOS:

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

QRCODE:

QR CODETM LAYOUT GERADO PELO POS (MODELO NOVO BR CODE)

Os dados usados para gerar o QRCode para leitura na carteira digital deve seguir como base aespecificação “EMVCo-Merchant-Presented-QR-Specification-v1” utilizando os dados abaixo:

Ex:

DADOS:

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

QR CODE:

Mapa TAGs geradas em uma transação via QRCode:

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

QR CODETM LAYOUT GERADO PELO POS (MODELO ANTIGO)

Os dados usados para gerar o QRCode para leitura na carteira digital deve seguir como base a especificação “EMVCo-Merchant-Presented-QR-Specification-v1” utilizando os dados abaixo:

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

CALLBACK API PARA DESFAZIMENTO (uso opcional)

Existe uma API de call-back para informar a carteira sobre um defazimento.

O parceiro precisa desenvolver uma API para receber as informações de desfazimento seguindo o format abaixo e fornecendo a url para envio das informações:

Body:

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

API request (exemplo):

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