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:
- POST /v2/oauth/access-token
- GET /padraoq/v1/publicKey
- POST /padraoq/v1/payment/card
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
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).
