E-wallet (digital wallet)
E-wallets are electronic safes (repositories) of cards and payment data for the physical and e-commerce customers. Digital wallets allow a customer to register their payment details, making the purchase process more convenient and secure.
Contact the provider of your choice for further information on how to contract the service.
Available E-wallets
API E-commerce Cielo supports the following digital wallets:
Card brands supported by the wallets
Vist the wallet website to know more about supported card brands:
GooglePay
ApplePay
SamsungPay
E-wallet Integration
See below the representation of a standard transactional flow in the integration of an e-wallet:
Request
{
"MerchantOrderId": "2014111708",
"Customer": {
"Name": "Exemplo Wallet Padrão",
"Identity": "11225468954",
"IdentityType": "CPF"
},
"Payment": {
"Type": "CreditCard",
"Amount": 100,
"Installments": 1,
"Currency": "BRL",
"Payment.Capture": "false",
"Wallet": {
"Type": "TIPO DE WALLET",
"WalletKey": "IDENTIFICADOR DA LOJA NA WALLET",
"AdditionalData": {
"EphemeralPublicKey": "TOKEN INFORMADO PELA WALLET"
}
}
}
}
--request POST "https://apisandbox.cieloecommerce.cielo.com.br/1/sales/"
--header "Content-Type: application/json"
--header "MerchantId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--header "MerchantKey: 0123456789012345678901234567890123456789"
--header "RequestId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--data-binary
{
"MerchantOrderId": "2014111708",
"Customer": {
"Name": "Exemplo Wallet Padrão",
"Identity": "11225468954",
"IdentityType": "CPF"
},
"Payment": {
"Type": "CreditCard",
"Amount": 100,
"Installments": 1,
"Currency": "BRL",
"Payment.Capture": "false",
"Wallet": {
"Type": "TIPO DE WALLET",
"WalletKey": "IDENTIFICADOR DA LOJA NA WALLET",
"AdditionalData": {
"EphemeralPublicKey": "TOKEN INFORMADO PELA WALLET"
}
}
}
}
Property | Description | Type | Size | Required |
---|---|---|---|---|
MerchantId |
Merchant identifier at Cielo | GUID | 36 | Yes (sent in header) |
MerchantKey |
Public key for dual authentication at Cielo. | Text | 40 | Yes (sent in header) |
RequestId |
Request identifier, used when the merchant uses different servers for each GET/POST/PUT. | GUID | 36 | No (send in header) |
MerchantOrderId |
Order ID number. | Text | 50 | Yes |
Customer.Name |
Customer’s name. | Text | 255 | No |
Customer.Status |
Customer’s registration status (“NEW” / “EXISTING”). | Text | 255 | No |
Payment.Type |
Payment method type. | Text | 100 | Yes |
Payment.Amount |
Order amount in cents. | Number | 15 | Yes |
Payment.Installments |
Number of installments. | Number | 2 | Yes |
Payment.Capture |
Indicates whether the authorization will use automatic capture (“true”) or not (“false”). If “false”, a capture request must be sent - please, check with the acquirer if pre-authorization is available. | Boolean | - | No (default “false”) |
Wallet.Type |
Wallet type: “ApplePay” / “SamsungPay” / “GooglePay” / “Masterpass”. | Text | – | Yes |
Wallet.WalletKey |
Cryptographic key that identifies stores in wallets. Consult the table WalletKey for more information. | Text | – | Yes |
Wallet.AdditionalData.EphemeralPublicKey |
Token returned by wallet. Must be submitted in ApplePay integrations. | Text | – | Yes |
Wallet.AdditionalData.CaptureCode |
Code informed by Masterpass to the merchant. | Text | – | Yes |
Wallet.AdditionalData.Signature |
Token returned by wallet. Must be submitted in GooglePay integrations. | Text | – | Yes |
WalletKey
WalletKey is the identifier used by Cielo to decrypt the payloads returned by an e-wallet.
The WalletKey
formats that must be sent to the API E-commerce Cielo are:
Wallet | Example | |
---|---|---|
Apple Pay | 9zcCAciwoTS+qBx8jWb++64eHT2QZTWBs6qMVJ0GO+AqpcDVkxGPNpOR/D1bv5AZ62+5lKvucati0+eu7hdilwUYT3n5swkHuIzX2KO80Apx/SkhoVM5dqgyKrak5VD2/drcGh9xqEanWkyd7wl200sYj4QUMbeLhyaY7bCdnnpKDJgpOY6J883fX3TiHoZorb/QlEEOpvYcbcFYs3ELZ7QVtjxyrO2LmPsIkz2BgNm5f+JaJUSAOectahgLZnZR+easdhghrsa/E9A6DwjMd0fDYnxjj0bQDfaZpBPeGGPFLu5YYn1IDc | . |
Samsung Pay | eyJhbGciOiJSU0ExXzUiLCJraWQiOiIvam1iMU9PL2hHdFRVSWxHNFpxY2VYclVEbmFOUFV1ZUR5M2FWeHBzYXVRPSIsInR5cCI6IkpPU0UiLCJjaGFubmVsU2VjdXJpdHlDb250ZXh0IjoiUlNBX1BLSSIsImVuYyI6IkExMjhHQ00ifQ.cCsGbqgFdzVb1jhXNR–gApzoXH-fdafddfa-Bo_utsmDN_DuGm69Kk2_nh6txa7ML9PCI59LFfOMniAf7ZwoZUBDCY7Oh8kx3wsZ0kxNBwfyLBCMEYzET0qcIYxePezQpkNcaZ4oogmdNSpYY-KbZGMcWpo1DKhWphDVp0lZcLxA6Q25K78e5AtarR5whN4HUAkurQ.CFjWpHkAVoLCG8q0.NcsTuauebemJXmos_mLMTyLhEHL-p5Wv6J88WkgzyjAt_DW7laiPMYw2sqRXkOiMJLwhifRzbSp8ZgJBM25IX05dKKSS4XfFjJQQjOBHw6PYtEF5pUDMLHML3jcddCrX07abfef_DuP41PqOQYsjwesLZ8XsRj-R0TH4diOZ_GQop8_oawjRIo9eJr9Wbtho0h8kAzHYpfuhamOPT718EaGAY6SSrR7t6nBkzGNkrKAmHkC7aRwe.AbZG53wRqgF0XRG3wUK_UQ | . |
Google Pay | {"encryptedMessage":"0mXBb94Cy9JZhMuwtrBhMjXb8pDslrNsN5KhcEqnowOINqJgjXHD36KcCuzpQQ4cDAe64ZLmk2N3UBGXsN9hMMyeMakXlidVmteE+QMaNZIor048oJqlUIFPD54B/ic8zCdqq3xnefUmyKQe0I03x57TcEA9xAT/E4x3rYfyqLFUAEtu2lT0GwTdwgrsT8pKoTldHIgP+wVNTjrKvJrB4xM/Bhn6JfcSmOzFyI6w37mBU71/TK761nYOSxt7z1bNWSLZ4b8xBu1dlRgen2BSlqdafuQjV3UZjr6ubSvaJ8NiCh5FD/X013kAwLuLALMS2uAFS9j8cZ6R6zNIi13fK6Fe4ACbFTHwLzSNZjQiaRDb6MlMnY8/amncPIOXzpirb5ScIz8EZUL05xd+3YWVTVfpqgFo1eaaS+wZdUyRG0QEgOsr6eLBoH8d5lfV9Rx6XdioorUuT7s1Yqc0OJZO+fhBt6X0izE9hBGTexdZyg\u003d\u003d","ephemeralPublicKey":"BMdwrkJeEgCOtLevYsN3MbdP8xbOItXiTejoB6vXy0Kn0ZM10jy4Aasd6jTSxtoxoTpFydLhj5kzoOhbw2OzZu0\u003d","tag":"yAQIjWZ0VuCC7SWyYwc4eXOzpSUKhZduF9ip0Ji+Gj8\u003d"} | . |
Masterpass | a561da1c18a89cfdafas875f9d43fc46cd9bf3e1 | . |
EphemeralPublicKey
This is the EphemeralPublicKey
format to be sent to API E-commerce Cielo:
Wallet | Example |
---|---|
Apple Pay | MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEoedz1NqI6hs9hEO6dBsnn0X0xp5/DKj3gXirjEqxNIJ8JyhGxVB3ITd0E+6uG4W6Evt+kugG8gOhCBrdUU6JwQ== |
Signature
Signature
format that must be sent to the API E-commerce Cielo:
Wallet | Example |
---|---|
Google Pay | MEUCIQCGQLOmwxe5eFMSuTcr4EcwSZu35fB0KlCWcVop6ZxxhgIgbdtNHThSlynOopfxMIxkDs0cLh2NFh5es+J5uDmaViA= |
Responses
{
"MerchantOrderId": "2014111703",
"Customer": {
"Name": "[Guest]"
},
"Payment": {
"ServiceTaxAmount": 0,
"Installments": 1,
"Interest": 0,
"Capture": false,
"Authenticate": false,
"Recurrent": false,
"CreditCard": {
"CardNumber": "453211******1521",
"Holder": "BJORN IRONSIDE",
"ExpirationDate": "08/2020",
"SaveCard": false,
"Brand": "Visa"
},
"Tid": "0319040817883",
"ProofOfSale": "817883",
"AuthorizationCode": "027795",
"Wallet": {
"Type": "TIPO DE WALLET",
"WalletKey": "IDENTIFICADOR DA LOJA NA WALLET",
"Eci": 0,
"AdditionalData": {
"EphemeralPublicKey": "TOKEN INFORMADO PELA WALLET"
}
},
"SoftDescriptor": "123456789ABCD",
"Amount": 100,
"ReceivedDate": "2018-03-19 16:08:16",
"Status": 1,
"IsSplitted": false,
"ReturnMessage": "Operation Successful",
"ReturnCode": "4",
"PaymentId": "e57b09eb-475b-44b6-ac71-01b9b82f2491",
"Type": "CreditCard",
"Currency": "BRL",
"Country": "BRA",
"Links": [
{
"Method": "GET",
"Rel": "self",
"Href": "https://apiquerysandbox.cieloecommerce.cielo.com.br/1/sales/{PaymentId}"
},
{
"Method": "PUT",
"Rel": "capture",
"Href": "https://apisandbox.cieloecommerce.cielo.com.br/1/sales/{paymentId}/capture"
},
{
"Method": "PUT",
"Rel": "void",
"Href": "https://apisandbox.cieloecommerce.cielo.com.br/1/sales/{PaymentId}/void"
}
]
}
}
--header "Content-Type: application/json"
--header "RequestId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--data-binary
{
"MerchantOrderId": "2014111703",
"Customer": {
"Name": "[Guest]"
},
"Payment": {
"ServiceTaxAmount": 0,
"Installments": 1,
"Interest": 0,
"Capture": false,
"Authenticate": false,
"Recurrent": false,
"CreditCard": {
"CardNumber": "453211******1521",
"Holder": "BJORN IRONSIDE",
"ExpirationDate": "08/2020",
"SaveCard": false,
"Brand": "Visa"
},
"Tid": "0319040817883",
"ProofOfSale": "817883",
"AuthorizationCode": "027795",
"Wallet": {
"Type": "TIPO DE WALLET",
"WalletKey": "IDENTIFICADOR DA LOJA NA WALLET",
"Eci": 0,
"AdditionalData": {
"EphemeralPublicKey": "TOKEN INFORMADO PELA WALLET"
},
},
"SoftDescriptor": "123456789ABCD",
"Amount": 100,
"ReceivedDate": "2018-03-19 16:08:16",
"Status": 1,
"IsSplitted": false,
"ReturnMessage": "Operation Successful",
"ReturnCode": "4",
"PaymentId": "e57b09eb-475b-44b6-ac71-01b9b82f2491",
"Type": "CreditCard",
"Currency": "BRL",
"Country": "BRA",
"Links": [
{
"Method": "GET",
"Rel": "self",
"Href": "https://apiquerysandbox.cieloecommerce.cielo.com.br/1/sales/{PaymentId}"
},
{
"Method": "PUT",
"Rel": "capture",
"Href": "https://apisandbox.cieloecommerce.cielo.com.br/1/sales/{paymentId}/capture"
},
{
"Method": "PUT",
"Rel": "void",
"Href": "https://apisandbox.cieloecommerce.cielo.com.br/1/sales/{PaymentId}/void"
}
]
}
}
Property | Description | Type | Size | Format |
---|---|---|---|---|
ProofOfSale |
Authorization number, identical to NSU. | Text | 6 | Alphanumeric text |
Tid |
Transaction ID in the acquirer. | Text | 20 | Alphanumeric text |
AuthorizationCode |
Authorization code. | Text | 6 | Alphanumeric text |
SoftDescriptor |
Text to be printed on the bearer bank statement. Available for VISA/MASTER only - no special characters allowed. | Text | 13 | Alphanumeric text |
PaymentId |
Order identifier field. | GUID | 36 | xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx |
ECI |
Electronic Commerce Indicator. Represents how secure a transaction is. | Text | 2 | E.g.: 7 |
Status |
Transaction status. | Byte | 2 | E.g.: 1 |
ReturnCode |
Return code from the acquirer. | Text | 32 | Alphanmeric text. |
ReturnMessage |
Return message from the acquirer. | Text | – | Alphanumeric text. |
Type |
Wallet type: “ApplePay” / “SamsungPay” / “GooglePay” / “Masterpass”. | Text | – | Alphanumeric text |
WalletKey |
Cryptographic key that identifies stores in wallets. Consult the table WalletKey for more information | Text | – | See table WalletKey |
AdditionalData.EphemeralPublicKey |
Token returned by the wallet. Must be submitted in ApplePay integrations. | Text | – | See table EphemeralPublicKey |
AdditionalData.CaptureCode |
Code informed by Masterpass to the merchant. | Text | – | 3 |
AdditionalData.Signature |
Token returned by wallet. Must be submitted in GooglePay integrations. | Text | – | See table Signature |
Integration examples
Here are some examples of integration with the main e-wallets available on the market.
Apple Pay ™
Apple Pay is a virtual wallet. It allows the shopper to make payments in e-commerce stores and apps using, in a practical and safe way, their credit and debit cards stored in their Apple accounts and devices.
Prerequisites
In order to use Apple Pay, your store must be previously registered in the AppleID program. In addition to that, you must also:
- Enroll your store through this URL, following all steps required by Apple.
- Follow the procedure set out in this document, in order to complete your integration with Apple.
- Hire API E-commerce Cielo;
- Hire Cielo 3.0 as the acquirer;
- Integrate with API E-commerce Cielo.
PART 1: Configuring the Merchant Identifier
In this initial step, you will need to create a merchant identifier for your store. Once created, the merchant identifier must be sent to Cielo in a request for a “.CSR” certificate. The “.CSR” certificate created by Cielo must be used to create a new certificate with Apple, the “.CER” certificate, which will serve as a follow-up to the second stage of the process.
Step 1 - Create a Merchant Identifier
The merchant identifier must be created through the Apple Developer website as follows:
- In the “Certificates, Identifiers & Profiles” section, select “Identifiers” in the side menu, and then click the
(+)
button next to the title: - Select the “Merchant IDs” option and then click
Continue
: - Enter a value in the “Description” and “Identifier” fields, following your specifications, and click
Continue
: - To finish, click on
Register
:
Step 2 - Request the “.CSR” Certificate
To request Cielo to generate the certificate in “.CSR” format, contact our Support Team and enter:
- The Merchant Identifier created in “Step 1”;
- The Merchant ID of your Cielo store in production.
Our team will return with the “.CSR” file within 48 business hours.
Step 3 - Create a “.CER” Certificate
- In the “Certificates, Identifier & Profiles” section, select “Identifiers” on the side menu.
- Use the filter on the top right corner (“App IDs”), to locate the “Merchant IDs” item:
- Select the recently created identifier:
- In the “Apple Pay Payment Processing Certificate” block, click the
Create Certificate
button right after the short description: - Choose “No” in “Edit or Configure Merchant ID”:
- In the dialog box, click
Choose File
and choose the “.CSR” certificate sent by Cielo: - Click
Continue
: - Click
Download
and save the “.CER” file:
For more details on the process, access Apple’s Developer Account Help.
PART 2: Integrating with Apple Pay
Most of the process of enabling the “Pay with Apple Pay” button in your app or site is performed during your wallet integration. For that reason, we recommend you to follow the instructions available in the Apple Developer Documentation website for Apple’s self-service implementation.
At the end of the process performed in the Apple API, you will receive a JSON containing two important fields that will be used in “PART 3”: the paymentData.data
and the ephemeralPublicKey.header.EphemeralPublicKey
fields.
{
"applePayData": {
"paymentData": {
"version": "EC_v1",
"data": "as01vRj+n9crY2vome7zc+u7Tz0+qg2La/8IUHpJIjFN6ThhUqLnSrskQHTrEbcYPiMksFK0+ddo9sZu70uJQJH1I+44N6PrVhilNDem97vOXq2VYDXiVJ27F/Q9wGQDgZBeGcZ6Pml9SIelHqUauBcQoOatrlnWPUL8kbdpT8WqgzXyaCh7oeTz=z6++rp/ofjvSjnGtOqAUsnrzvw4uzkcyKUSsfROdJ6B/Xzgu/T9fMIr5UxXD2DPF1SNh3ydEJABKz4HFjDW7ObvbQeua4GYxJdpQLpI3NgUbJy91E/LOyb/+PcCtO+0=a41tBrfnTTF9qsPuCIw8HWIEEKSRofn27NTofxev/i+nHEfqEtqNrN/epIvhzceD/gDiGetfiLKMzf94ARmpWUAMC==",
"signature": "(…)",
"header": {
"ephemeralPublicKey": "MFkwEwZJKoZIzj0CAQYIKo12zj0DAQcDQgAEo+ReGClSmQ4hDJD1yh9nci3V4l7kPm2AQtKZMMvuNS0iK5sn/1A9l3kw1B1xCqOycZmnPSng7p5hpTvrei1BCA==",
"publicKeyHash": "KXN06+BtJu6yEfF9zDhr7f4M/2HwVybnx0FGfC520gB=",
"transactionId": "71c5b61c3791546e94d2b4893a6c69aaac2ab86b5c113c83a7d89057906a9b5f"
}
},
"paymentMethod": {
"displayName": "MasterCard 1212",
"network": "MasterCard",
"type": "credit"
},
"transactionIdentifier": "81C5B61C3791646E94D2B4893A6C69BBBC2AB86B5C363C83A7D89057906A9BAC"
},
"x_document": "24562608994",
"x_name": "João da Silva"
}
Important Note
PART 3: Integration with API E-commerce Cielo (decryption and authorization)
Authorization with the Apple Pay token happens in the same way as standard credit card authorization. However, instead of providing card details openly, the token received by Apple Pay must be provided, as in the example below:
Request
{
"MerchantOrderId": "2017051002",
"Customer": {
(…)
},
"Payment": {
"Type": "CreditCard",
"Amount": 1000,
"Installments": 1,
"Currency": "BRL",
"Wallet": {
"Type": "ApplePay",
"WalletKey":"['paymentData.data']",
"AdditionalData": {
"EphemeralPublicKey": "['ephemeralPublicKey.header.EphemeralPublicKey']"
}
}
}
}
Header Parameters | Description | Type and Size |
---|---|---|
MerchantId |
Store ID in API E-commerce Cielo. | GUID (36) |
MerchantKey |
API key in API E-commerce Cielo. | String (24) |
Parameter | Description | Type and Size |
---|---|---|
MerchantOrderId |
Order ID number. | String (50) |
Customer |
Node with customer’s data. | Refer to API E-commerce Cielo. |
Payment.Type |
Payment method type. Possibilities: “CreditCard” / “DebitCard”. | String (100) |
Payment.Amount |
Order amount in cents. | Number (15) |
Payment.Installments |
Number of installments. | Number (2) |
Payment.Wallet.Type |
Name of payment method provider. For Apple Pay transactions, use “ApplePay”. | String (15) |
Payment.Wallet.WalletKey |
Fill with the paymentData.data parameter value returned by Apple Pay. |
String |
Payment.Wallet.AdditionalData.EphemeralPublicKey |
Fill with the ephemeralPublicKey.header.EphemeralPublicKey parameter value returned by Apple Pay. |
String |
Response
{
"MerchantOrderId": "2017051002",
"Customer": {(…)
},
"Payment": {
(…)
"CreditCard": {
(…)
},
(…)
"Wallet": {
"Type": "ApplePay",
"WalletKey": "as01vRj+n9crY2vome7zc+u7Tz0+qg2La/8IUHpJIjFN6ThhUqLnSrskQHTrEbcYPiMksFK0+ddo9sZu70uJQJH1I+44N6PrVhilNDem97vOXq2VYDXiVJ27F/Q9wGQDgZBeGcZ6Pml9SIelHqUauBcQoOatrlnWPUL8kbdpT8WqgzXyaCh7oeTz=z6++rp/ofjvSjnGtOqAUsnrzvw4uzkcyKUSsfROdJ6B/Xzgu/T9fMIr5UxXD2DPF1SNh3ydEJABKz4HFjDW7ObvbQeua4GYxJdpQLpI3NgUbJy91E/LOyb/+PcCtO+0=a41tBrfnTTF9qsPuCIw8HWIEEKSRofn27NTofxev/i+nHEfqEtqNrN/epIvhzceD/gDiGetfiLKMzf94ARmpWUAMC==",
"AdditionalData": {
"EphemeralPublicKey": "MFkwEwZJKoZIzj0CAQYIKo12zj0DAQcDQgAEo+ReGClSmQ4hDJD1yh9nci3V4l7kPm2AQtKZMMvuNS0iK5sn/1A9l3kw1B1xCqOycZmnPSng7p5hpTvrei1BCA=="
}
},
(…)
"Links": [
(…)
]
}
}
The wallet authorization response will have the same fields presented in the documentation of API E-commerce Cielo, however with the addition of the Payment.Wallet
node repeating the same fields used in the authorization, as described above.
Google Pay ™
Google Pay is an e-wallet that allows shoppers to make payments in e-commerce stores and apps using their credit and debit cards stored in their Google Accounts and Android devices in a safe and easy way.
Prerequisites
In order to use Google Pay, your store must be previously registered and integrated with Google Pay. In addition to that, you must also:
- Agree to Google’s terms of service;
- Follow the steps in this documentation to thoroughly integrate Google Pay into your app;
- Hire API E-commerce Cielo;
- Hire Cielo 3.0 as the acquirer;
- Integrate with API E-commerce Cielo.
PART 1: Integrating Google Pay
In this initial step, must set up your project and implement Google Pay in your Android application.
Step 1 - Configure your Project
To set up your project, follow the instructions described in the Google Pay Setup Guide.
In this step, you must add dependencies either by importing the library from Google Play Services or choosing the APIs you want to compile. And then, to enable Google Pay in your Android application, you will have to modify the “AndroidManifest.xml” file of your project according to the instructions given on the page.
Step 2 - Implement Google Pay
To integrate Google Play into your app, follow all the steps described in the Google Pay Tutorial Guide.
For the correct integration of Google Pay via Cielo, it is necessary to pay attention to the points below:
Gateway Definition
In step “Step 2: Request a payment token for your payment provider”, follow the model indicated as “GATEWAY” and assign the value “PAYMENT_GATEWAY” to the type
parameter and the value “cielo” to the gateway
parameter, according to the given example:
private static JSONObject getTokenizationSpecification() {
JSONObject tokenizationSpecification = new JSONObject();
tokenizationSpecification.put("type", "PAYMENT_GATEWAY");
tokenizationSpecification.put(
"parameters",
new JSONObject()
.put("gateway", "cielo")
.put("gatewayMerchantId", "exampleMerchantId"));
return tokenizationSpecification;
}
Fill in the gatewayMerchantId
parameter with your store’s identifier, generated by the gateway. The store identifier follows the format “XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX” (type GUID / size 36).
Card brands definition
In “Step 3: Define supported payment card networks”, configure according to the flags accepted by the wallet.
Environment definition
In “Step 5: Create a PaymentsClient instance”, use the value “WalletConstants.ENVIRONMENT_TEST” for the test environment.
Shopping Data definition
In “Step 7: Create a PaymentDataRequest object”, use the “BRL” value for the currencyCode
parameter. The merchantName
field is the name that the shopper will see throughout the Google Pay payment process. Thus, the use of a recognizable friendly name is recommended.
Payment data recovery
In “Step 9: Handle the response object”, the Activity.RESULT_OK
event is described, in which an object is returned with all the payment data, including payment tokens.
From the PaymentData
, the PaymentMethodToken
object is obtained, by calling the getPaymentMethodToken()
method. Click here for more information.
Next, you must get the string that contains payment tokens from the GetToken()
method of the PaymentMethodToken
object. Click here for more information.
The string obtained in the previous step has a structure like the one shown below. Click here for more information.
{
"protocolVersion": "ECv1",
"signature": "TJVA95OrM7E2cBab30RMHrHDcEfxjoYZgeFONFh7HgQ",
"signedMessage": "{\"encryptedMessage\":
\"ZW5jcnlwdGVkTWVzc2FnZQ==\",\"ephemeralPublicKey\":
\"ZXBoZW1lcmFsUHVibGljS2V5\",\"tag\": \"c2lnbmF0dXJl\"}"
}
Parameter | Type | Description |
---|---|---|
signedMessage |
string | Signed message. |
signature |
string | Message signature. |
Save the signedMessage
and signature
data, which will be required for authorization via the API E-commerce Cielo in STEP 2, described below.
PART 2: Authorization with Token
Authorization with the Google Pay token happens in the same way as standard credit card authorization. However, instead of providing card details openly, the token received by Google Pay must be provided, as shown in the example:
Request
{
"MerchantOrderId": "2014111708",
"Customer": {
(…)
},
"Payment": {
"Type": "CreditCard",
"Amount": 100,
"Installments": 1,
"Wallet": {
"Type": "AndroidPay",
"WalletKey": "{\"encryptedMessage\": \"ZW5jcnlwdGVkTWVzc2FnZQ==\",\"ephemeralPublicKey\": \"ZXBoZW1lcmFsUHVibGljS2V5\",\"tag\": \"c2lnbmF0dXJl\"}",
"AdditionalData": {
"Signature": "ZXBoZW1lcmFsUHVibGljS2V5"
}
}
}
}
Header Parameters | Description | Type and Size |
---|---|---|
MerchantId |
Store identifier at Cielo 3.0. For the Sandbox environment, use 63D6ACCB-2734-4236-AB5D-843A9DAC44C7. | GUID (36) |
MerchantKey |
API key for Cielo 3.0. For the Sandbox environment, use ZCVHDJWKTGOZXADDYJFURIDIKHEMRYQAQDYEJMQK. | String (24) |
Parameters | Description | Type and size |
---|---|---|
MerchantOrderId |
Order identification number. | String (50) |
Customer |
Node with the shopper’s data. | Refer to API E-commerce Cielo. |
Payment.Type |
Payment method type. Possible values: “CreditCard” / “DebitCard”. | String (100) |
Payment.Amount |
Transaction amount in cents. | Number (15) |
Payment.Installments |
Number of installments. | Number (2) |
Payment.Wallet.Type |
allet provider name. For Google Pay, use “AndroidPay”. | String (15) |
Payment.Wallet.WalletKey |
Provide the signedMessage received from Google Pay. |
String |
Payment.Wallet.AdditionalData.Signature |
Provide the signature received from Google Pay. |
String |
For further information, refer to API E-commerce Cielo.
The wallet authorization response will have the same fields presented in our API E-commerce Cielo documentation, however with the addition of the Payment.Wallet
node repeating the same fields used in the authorization, as described above.
PART 3: Production Data Request
In order to complete the process, first validate the steps performed in PARTS 1 and 2. Then, request your access credentials for deployment.
Step 1 - Branding Guideline
Verify whether the branding guidelines have been thoroughly followed.
Step 2 - Checklist and Credentials Request
Check that all items in the integration checklist have been attended. After everything is validated, request your access credentials for the production environment.
Samsung Pay™
Below is the prerequisite for using Samsung Pay and also an example of a request to make it available in your store.
Request
Example of a standard Samsung Pay request:
{
"MerchantOrderId": "6242-642-723",
"Customer": {
"Name": "Exemplo Wallet Padrão",
"Identity": "11225468954",
"IdentityType": "CPF"
},
"Payment": {
"Type": "CreditCard",
"Amount": 1,
"Installments": 1,
"Currency": "BRL",
"Wallet": {
"Type": "SamsungPay",
"WalletKey": "IDENTIFICADOR DA LOJA NA WALLET"
}
}
}
curl
--request POST "https://apisandbox.cieloecommerce.cielo.com.br/1/sales/"
--header "Content-Type: application/json"
--header "MerchantId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--header "MerchantKey: 0123456789012345678901234567890123456789"
--header "RequestId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--data-binary
{
"MerchantOrderId":"6242-642-723",
"Customer":{
"Name":"Exemplo Wallet Padrão",
"Identity":"11225468954",
"IdentityType":"CPF"
},
"Payment":{
"Type":"CreditCard",
"Amount":1,
"Installments":1,
"Currency":"BRL",
"Wallet":{
"Type":"SamsungPay",
"WalletKey":"IDENTIFICADOR DA LOJA NA WALLET"
}
}
}
Property | Description | Type | Size | Required |
---|---|---|---|---|
MerchantId |
Store identifier at Cielo. | GUID | 36 | Yes (sent in header) |
MerchantKey |
Public key for dual authentication at Cielo. | Text | 40 | Yes (sent in header) |
RequestId |
Request identifier, used when the merchant uses different servers for each GET/POST/PUT. | GUID | 36 | No (sent in header) |
MerchantOrderId |
Order ID number. | Text | 50 | Yes |
Customer.Name |
Customer’s name. | Text | 255 | No |
Customer.Status |
Customer’s registration status (“NEW” / “EXISTING”). | Text | 255 | No |
Payment.Type |
Payment method type. | Text | 100 | Yes |
Payment.Amount |
Order amount in cents. | Number | 15 | Yes |
Payment.Installments |
Number of installments. | Number | 2 | Yes |
Wallet.Type |
Wallet type: “SamsungPay”. | Text | 255 | Yes |
Wallet.WalletKey |
Cryptographic key representing card data. Consult the table WalletKey for more information. | Text | 255 | Yes |
Response
{
"MerchantOrderId": "2014111703",
"Customer": {
"Name": "[Guest]"
},
"Payment": {
"ServiceTaxAmount": 0,
"Installments": 1,
"Interest": 0,
"Capture": false,
"Authenticate": false,
"Recurrent": false,
"CreditCard": {
"CardNumber": "453211******1521",
"Holder": "BJORN IRONSIDE",
"ExpirationDate": "08/2020",
"SaveCard": false,
"Brand": "Visa"
},
"Tid": "0319040817883",
"ProofOfSale": "817883",
"AuthorizationCode": "027795",
"Wallet": {
"Type": "SamsungPay",
"WalletKey": "IDENTIFICADOR DA LOJA NA WALLET",
"Eci": 0
},
"SoftDescriptor": "123456789ABCD",
"Amount": 100,
"ReceivedDate": "2018-03-19 16:08:16",
"Status": 1,
"IsSplitted": false,
"ReturnMessage": "Operation Successful",
"ReturnCode": "4",
"PaymentId": "e57b09eb-475b-44b6-ac71-01b9b82f2491",
"Type": "CreditCard",
"Currency": "BRL",
"Country": "BRA",
"Links": [
{
"Method": "GET",
"Rel": "self",
"Href": "https://apiquerysandbox.cieloecommerce.cielo.com.br/1/sales/{PaymentId}"
},
{
"Method": "PUT",
"Rel": "capture",
"Href": "https://apisandbox.cieloecommerce.cielo.com.br/1/sales/{paymentId}/capture"
},
{
"Method": "PUT",
"Rel": "void",
"Href": "https://apisandbox.cieloecommerce.cielo.com.br/1/sales/{PaymentId}/void"
}
]
}
}
--header "Content-Type: application/json"
--header "RequestId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--data-binary
{
"MerchantOrderId": "2014111703",
"Customer": {
"Name": "[Guest]"
},
"Payment": {
"ServiceTaxAmount": 0,
"Installments": 1,
"Interest": 0,
"Capture": false,
"Authenticate": false,
"Recurrent": false,
"CreditCard": {
"CardNumber": "453211******1521",
"Holder": "BJORN IRONSIDE",
"ExpirationDate": "08/2020",
"SaveCard": false,
"Brand": "Visa"
},
"Tid": "0319040817883",
"ProofOfSale": "817883",
"AuthorizationCode": "027795",
"Wallet": {
"Type": "SamsungPay",
"WalletKey": "IDENTIFICADOR DA LOJA NA WALLET",
"Eci": 0
},
"SoftDescriptor": "123456789ABCD",
"Amount": 100,
"ReceivedDate": "2018-03-19 16:08:16",
"Status": 1,
"IsSplitted": false,
"ReturnMessage": "Operation Successful",
"ReturnCode": "4",
"PaymentId": "e57b09eb-475b-44b6-ac71-01b9b82f2491",
"Type": "CreditCard",
"Currency": "BRL",
"Country": "BRA",
"Links": [
{
"Method": "GET",
"Rel": "self",
"Href": "https://apiquerysandbox.cieloecommerce.cielo.com.br/1/sales/{PaymentId}"
},
{
"Method": "PUT",
"Rel": "capture",
"Href": "https://apisandbox.cieloecommerce.cielo.com.br/1/sales/{paymentId}/capture"
},
{
"Method": "PUT",
"Rel": "void",
"Href": "https://apisandbox.cieloecommerce.cielo.com.br/1/sales/{PaymentId}/void"
}
]
}
}
Property | Description | Type | Size | Format |
---|---|---|---|---|
ProofOfSale |
Authorization number, identical to the NSU. | Text | 6 | Alphanumeric |
Tid |
Transaction ID on the acquirer. | Text | 20 | Alphanumeric |
AuthorizationCode |
Authorization code. | Text | 6 | Alphanumeric |
SoftDescriptor |
Text to be printed on the bearer’s bank statement. Note: Does not allow special characters. Available for VISA/MASTER only. | Text | 13 | Alphanumeric |
PaymentId |
Order identifier field. | GUID | 36 | xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx |
ECI |
Electronic Commerce Indicator. Represents how secure a transaction is. | Text | 2 | E.g.: 7 |
Status |
Transaction status. | Byte | 2 | E.g.: 1 |
ReturnCode |
Return code from the acquirer. | Text | 32 | Alphanumeric |
ReturnMessage |
Return message from acquirer. | Text | 512 | Alphanumeric |
Type |
Wallet type: “SamsungPay” | Text | 255 | Alphanumeric |
WalletKey |
Cryptographic key representing card data. Consult the table WalletKey for more information. | Text | 255 | Refer to WalletKey. |
Authorization with decrypted card
If the merchant decrypts the payload received from the wallet and sends it to the API E-commerce Cielo for processing and authorization, they must use the following request model:
Request
-- Envio de cartão
{
"MerchantOrderId": "6242-642-723",
"Customer": {
"Name": "Guilherme Gama",
"Identity": "11225468954",
"IdentityType": "CPF"
},
"Payment": {
"Type": "CreditCard",
"Amount": 1100,
"Provider": "Cielo",
"Installments": 1,
"CreditCard": {
"CardNumber":"4532********6521",
"Holder":"Guilherme Gama",
"ExpirationDate":"12/2021",
"SecurityCode":"123",
"Brand":"Master"
},
"Wallet": {
"Type": "Tipo de wallet",
"Eci":"7",
"Cavv":"AM1mbqehL24XAAa0J04CAoABFA=="
}
}
}
Property | Type | Size | Required | Description |
---|---|---|---|---|
MerchantId |
Guid | 36 | Yes | Store identifier atCielo. |
MerchantKey |
Text | 40 | Yes | Public key for dual authentication at Cielo. |
RequestId |
Guid | 36 | No | Request identifier, used when the merchant uses different servers for each GET/POST/PUT. |
MerchantOrderId |
Text | 50 | Yes | Order ID number. |
Customer.Name |
Text | 255 | No | Customer’s name. |
Customer.Status |
Text | 255 | No | Customer’s registration status (“NEW” / “EXISTING”). |
Payment.Type |
Text | 100 | Yes | Payment method type. |
Payment.Amount |
Number | 15 | Yes | Order amount in cents. |
Payment.Installments |
Number | 2 | Yes | Number of installments. |
CreditCard.CardNumber. |
Text | 19 | Yes | Customer’s card number |
CreditCard.SecurityCode |
Texto | 4 | Não | Security code printed on the back of the card. |
CreditCard.Brand |
Text | 10 | Yes | Card brand (Visa / Master / Amex / Elo / Aura / JCB / Diners / Discover / Hipercard / Hiper). |
Wallet.Type |
Text | 255 | Yes | Wallet type: AndroidPay / ApplePay / SamsungPay |
Wallet.Walletkey |
Text | 255 | Yes | Cryptographic key representing card data. Consult the table WalletKey for more information. |
Wallet.Eci |
Text | 3 | Yes | The ECI (Electronic Commerce Indicator) represents how safe a transaction is. This value must be taken into account by the merchant when deciding on capturing the transaction. |
Wallet.Cavv |
Text | 255 | Yes | Validation field returned by Wallet and used as authorization basis. |
Response
{
"MerchantOrderId": "2014111703",
"Customer": {
"Name": "[Guest]"
},
"Payment": {
"ServiceTaxAmount": 0,
"Installments": 1,
"Interest": 0,
"Capture": false,
"Authenticate": false,
"Recurrent": false,
"CreditCard": {
"CardNumber": "453211******1521",
"Holder": "Gama Gama",
"ExpirationDate": "08/2020",
"SaveCard": false,
"Brand": "Visa"
},
"Tid": "0319040817883",
"ProofOfSale": "817883",
"AuthorizationCode": "027795",
"Wallet": {
"Type": "TIPO DE WALLET",
"Eci": 0
},
"SoftDescriptor": "123456789ABCD",
"Amount": 100,
"ReceivedDate": "2018-03-19 16:08:16",
"Status": 1,
"IsSplitted": false,
"ReturnMessage": "Operation Successful",
"ReturnCode": "4",
"PaymentId": "e57b09eb-475b-44b6-ac71-01b9b82f2491",
"Type": "CreditCard",
"Currency": "BRL",
"Country": "BRA",
"Links": [
{
"Method": "GET",
"Rel": "self",
"Href": "https://apiquerysandbox.cieloecommerce.cielo.com.br/1/sales/e57b09eb-475b-44b6-ac71-01b9b82f2491"
},
{
"Method": "PUT",
"Rel": "capture",
"Href": "https://apisandbox.cieloecommerce.cielo.com.br/1/sales/e57b09eb-475b-44b6-ac71-01b9b82f2491/capture"
},
{
"Method": "PUT",
"Rel": "void",
"Href": "https://apisandbox.cieloecommerce.cielo.com.br/1/sales/e57b09eb-475b-44b6-ac71-01b9b82f2491/void"
}
]
}
}
Property | Description | Type | Size | Format |
---|---|---|---|---|
ProofOfSale |
Authorization number, identical to NSU. | Text | 6 | Alphanumeric |
Tid |
Transaction ID in the acquirer. | Text | 20 | Alphanumeric |
AuthorizationCode |
Authorization code. | Text | 6 | Alphanumeric |
SoftDescriptor |
Text to be printed on customer’s invoice. Note: Does not allow special characters. Available for VISA/MASTER only. | Text | 13 | Alphanumeric |
PaymentId |
Order identifier field. | Guid | 36 | xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx |
ECI |
Eletronic Commerce Indicator. Represents how secure a transaction is. | Text | 2 | E.g.: 7 |
Status |
Transaction status. | Byte | — | 2 |
ReturnCode |
Return code from acquirer. | Text | 32 | Alphanumeric |
ReturnMessage |
Return message from acquirer. | Text | 512 | Alphanumeric |
Type |
Wallet type: Masterpass / ApplePay / SamsungPay |
Text | 255 | Alphanumeric |
Walletkey |
Cryptographic key representing card data. Consult the table WalletKey for more information. | Text | 255 | Check the WalletKey table |
AdditionalData.capturecode |
Code passed to merchant by Masterpass. | Text | 255 | 3 |
Annexes
Transaction Status List
List of statuses returned by the API:
Code | Payment status | Payment method | Description |
---|---|---|---|
0 | NotFinished | All | Failed to process the payment. Possible causes: incorrect data, error in the request, acquirer timeout, some processing instability. In case of debit transaction, the buyer may have abandoned the purchase. |
1 | Authorized | All | Payment methods able to be captured or paid (boleto). For a boleto transaction, it means that the boleto was successfully generated. For a card transaction, it means that there was approval by the issuing bank. However, this does not mean that the transaction has been completed - for this, a second step is required, capturing the transaction or making the payment. |
2 | PaymentConfirmed | All | Payment confirmed and completed. |
3 | Denied | Credit and debit cards (electronic transfer) and e-wallets. | Payment denied by authorizer. Possible causes: insufficient limit, lack of payment on the card, unavailable brand, blocking due to fraud, among others. To find out the real reason for the denial, it is necessary to look at the return code generated during the transaction. |
10 | Voided | All, except boleto | Payment canceled. It is the suspension of the transaction, exempting from fees or amounts charged. Pre-authorized transactions can be canceled even after 23:59 on the authorization date. Captured transactions can be canceled up to 11:59 pm on the same day of authorization, after which time the amount will be reversed. |
11 | Refunded | Credit and debit cards and e-wallets. | Payment cancelled/reversed. Means that the cancellation of the transaction was requested, which may occur from 0:00 am on the day after the creation of the transaction. Regardless of the amount, it is only possible to make one reversal request per transaction. This can happen due to incorrect data or at the request of the shopper. |
12 | Pending | Credit and debit cards (electronic transfer), e-wallets and pix. | Awaiting return from financial institution. Means that the transaction was sent to Cielo in the pre-authorization process, awaiting a response from the issuing bank to validate it. |
13 | Aborted | All | Payment canceled due to processing failure. Means that the transaction was canceled due to processing failure. It can also be aborted if Anti-Fraud denies the transaction before authorization. |
20 | Scheduled | Credit card and e-wallets. | Scheduled recurrence. Means that the transaction will have a scheduled recurrence, that is, the purchase amount will be collected on the day it was scheduled by the store. |