Requerimentos para acesso

Para acesso a APIs é necessário abrir um cDê-para QR Code x Rechamado via Zendesk

Nota: Futuramente a geração de credenciais será feita via portal do desenvolvedor.

Macro fluxo de integração

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

• POST /access_token
• GET /publicKeys
• POST /payments

Ambientes

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 os parâmetros client_id e 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 /cielo-payment/v1/access_token

Headers

Key	Value
client_id
Authorization
Content-Type	application-json

Body

{
"grant_type": "client_credentials"
}

Exemplo de Requisição

curl --request POST \
  --url 'https:///cielo-payment/v1/access_token' \
  --header 'Authorization: ' \
  --header 'Content-Type: application/json' \
  --header 'client_id: ' \
  --data '{
    "grant_type": "client_credentials"
}

Exemplo de Resposta

{
  "access_token": "g7xDuftvHv5y3Dx3gnQvsOeSG0YN99FcS4NVOtihNflWTUUPgf",
  "token_type": "access_token",
  "expires_in": 600
}

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. O algoritmo de criptografia utilizada é RSA de 2048 bits e cifra RSA/ECB/PKCS1Padding. Para a requisição ao recurso GET /publicKeys é necessário client_id e o access_token que foi gerado no passo anterior.

Contrato

GET /cielo-payment/v1/publicKeys

Headers

Key	Value
client_id
access_token	{access_token}

Exemplo de Requisição

curl --request GET \
  --url 'http:///cielo-payment/v1/publicKeys' \
  --header 'access_token: ' \
  --header 'client_id: 

Exemplo de Resposta

MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAmeiLngFr9h0npwe6D3ArSi10ZgdOCUCsUYT12KMuYsxImzwe9aGX8XXvzEF60E600ZjdvmYU64UnZKgfbttwNi+Tl7ZcB2cnS/oJMrfA0AbRHukJnL/fFsziHOjv0A1xRcE70ZbJRkob5A5s4GenF+jv/xCTOoIetFimZHZDiPPFux2NyrL3ZqSs7F4XJZvo2zPfCVlAcnEbVf+8vWX3goP2TEuAqZtBT543wIDAQAB+dqSzZSqZolYU1sjV7s8FzsjZYqo+AjM8BMuPlMoPEuBqgRFm4fSRIpeJIr0G9FokSU3X6MAZTvC7n3YePHFsFmGxPTrKpEFrp8s28f1qMP5suTsA

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 /payments é responsável por efetuar o pagamento com base nos dados contidos no payload da requisição. No header da requisição é necessário os dados de client_id, access_token, Content-type e wallet. Wallet representa a carteira digital da aplicação sendo única por app. O corpo da requisição é composto por dados provenientes do aplicativo e do QR Code. Verificar seção 3 para os campos extraídos do QR Code.

Contrato

POST /cielo-payment/v1/payments

Headers

Key	Value
client_id
access_token
Content-Type	application/json
wallet

Body

{
 "technology":{
    "type":"QRCODE",
    "identifier":"13050329197F190A"
 },
 "operationType":{
    "id":1
 },
 "amount":1,
 "paymentInstallments":01,
 "terminalLogicalNumber":12345,
 "paymentDate":"2018-05-15T11:33:49Z",
 "mainProduct":{
    "id":1000
 },
 "subProduct":{
    "id":1
 },
 "merchantAccountInformation":{
    "id":3456789012,
    "merchantName":"Hotelaria Accor Pdb Ltda"
 },
 "card":{
    "encryptedCardNumber": "KPzccLxuZFavn6FN5XhOsXdF19wrfiOleE0lCMixw+0E79YAVn659vDpKhy/D/EQnRbiKrrfRQYyQeek2cpyd5hiqtwK+4gdfUo8X4NpSYxDdk0n0ru1czg8hWn3Dl6LkQT8K/lOgfTttZQgQsmwPRBzhDImlzIav9E1Uqvzba3WWPrusCgGgE5oEMTGLjcmG1ZZByeXHiDmU5Pd9TomILj4nVFsoOWYtM5PZDn+1FfJ3lDLgND8asUMyLIqyQMZ3iDM6Rrgp/4Yj5082FNO++6ZMW2mPmlr4i2gmFi2sV4QayNuXX34mxrUw1kYpSetNVEL/okGzSaGxbN0O37Fug==",
    "holder":"JOAO DA SILVA",
    "expirationDate":"01/25",
    "brand":"VISA"
 },
 "carrier":{
    "name":"João da Silva",
    "document":"31727721012",
    "deviceId":"3ac43b36-0d92-48a7-901b-d3a527d9c3fe"
 },
 "crc":{
    >"qrCodeText":"00020101021226410005Cielo0116123456789012000102082009130352040000530398654120000000001005802BR5905CIELO6014SANTO ANDRE SP801010033”https://www.cielo.com.br/qrcode”011613050329197F190A0212150518113349030410000404000105020006020163049872"
 }
}

Exemplo de Requisição

curl --request POST \
 --url 'http:///cielo-payment/v1/payments' \
 --header 'Content-Type: application/json' \
 --header 'access_token: ' \
 --header 'client_id: ' \
 --data '{
 "technology":{
    "type":"QRCODE",
    "identifier":"13050329197F190A"
 },
 "operationType":{
    "id":1
 },
 "amount":1,
 "paymentInstallments":01,
 "terminalLogicalNumber":12345,
 "paymentDate":"2018-05-15T11:33:49Z",
 "mainProduct":{
    "id":1000
 },
 "subProduct":{
    "id":1
 },
 "merchantAccountInformation":{
    "id":3456789012,
    "merchantName":"Hotelaria Accor Pdb Ltda"
 },
 "card":{
    "encryptedCardNumber": "KPzccLxuZFavn6FN5XhOsXdF19wrfiOleE0lCMixw+0E79YAVn659vDpKhy/D/EQnRbiKrrfRQYyQeek2cpyd5hiqtwK+4gdfUo8X4NpSYxDdk0n0ru1czg8hWn3Dl6LkQT8K/lOgfTttZQgQsmwPRBzhDImlzIav9E1Uqvzba3WWPrusCgGgE5oEMTGLjcmG1ZZByeXHiDmU5Pd9TomILj4nVFsoOWYtM5PZDn+1FfJ3lDLgND8asUMyLIqyQMZ3iDM6Rrgp/4Yj5082FNO++6ZMW2mPmlr4i2gmFi2sV4QayNuXX34mxrUw1kYpSetNVEL/okGzSaGxbN0O37Fug==",
    "holder":"JOAO DA SILVA",
    "expirationDate":"01/25",
    "brand":"VISA"
 },
 "carrier":{
    "name":"João da Silva",
    "document":"31727721012",
    "deviceId":"3ac43b36-0d92-48a7-901b-d3a527d9c3fe"
 },
 "crc":{
    >"qrCodeText":"00020101021226410005Cielo0116123456789012000102082009130352040000530398654120000000001005802BR5905CIELO6014SANTO ANDRE SP801010033”https://www.cielo.com.br/qrcode”011613050329197F190A0212150518113349030410000404000105020006020163049872"
 }
}

Exemplo de Resposta

{
    "transactionDate": "2018-05-15T11:33:49.000-03:00",
    "terminalLogicalNumber": "12345",
    "authorizationCode": "8888",
    "nsu": "999"
}

Dê-para QR Code x Recurso Payments

Para a composição do payload do /payments deve-se mesclar informações provenientes da leitura do QR Code e informações do cartão/portador via aplicativo. Na tabela abaixo é especificado o dê-para dos dados extraídos do QR Code para o payload da requisição.

Para mais informações dos campos provenientes do QR Code verificar o próximo item.

Nota: O campo MerchantAccountInformation.Id tem o tamanho máximo de 10 posições, ao extrair a informação referente no QR Code descontar os dois primeiros e os quatros últimos dígitos.

Layout do QR Code gerado pelo POS

Atualmente o POS cria o QR Code a partir das informações especificadas abaixo com base na especificação “EMVCo-Merchant-Presented-QR-Specification-v1”.

Os campos destacados e identificamos abaixo são provenientes da análise do QR Code. O ID do campo e seu tamanho são sempre enviados antes do valor correspondente.

Como Testar

Atualmente existem duas possibilidades para testar o fluxo de pagamento no ambiente de homologação.

Via QR Code

Caso não esteja com o POS de homologação em mãos, a maneira mais rápida para teste é utilizando o QR Code abaixo.

Posicional de exemplo:

“00020101021226410005Cielo0116123456789012000102082009130352040000530398654120000000001005802BR5905CIELO6014SANTO ANDRE SP801010033”https://www.cielo.com.br/qrcode”011613050329197F190A0212150518113349030410000404000105020006020163049872”

QR Code gerado a partir do código de exemplo:

Observação: Ao testar com o QR Code especificado um erro do tipo 422 é esperado, pois, não existe dados transacionais referentes no autorizador da Cielo.

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
}

Bandeiras e Formas de Parcelamento

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

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

Erros de Pagamento

Dúvidas Frequentes

• Os testes devem ser feitos direto no ambiente de Homologação? R: Sim, infelizmente hoje não temos ambiente de desenvolvimento.

• Qual o processo para adquirir as credenciais de Produção? R: Vide seção 1.

• Qual criptografia é utilizada para criptografar o cartão? R: Vide seção 2.1.

• A solução de pagamento QR Code Cielo atualmente aceita pagamentos no débito? R: Não.

• O que seria o campo deviceID? R: Identificador único de cada dispositivo. Segue IOS: https://developer.apple.com/documentation/uikit/uidevice/1620059-identifierforvendor, Android: https://developer.android.com/training/articles/user-data-ids.

Canal de Suporte a Dúvidas

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