E-Wallets

Redirecionando para https://docs.cielo.com.br/gateway-en/docs/e-wallets ...

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

Pagador currently 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

There are two options for sending an authorization request using the payment method e-wallet:

  1. Authorization using encrypted card: the request contains the node Wallet, the parameter WalletKey (used by Cielo to decrypt e-wallet data) and additional tokens provided by each e-wallet. This type of integration is recommended for merchants who are not PCI DSS compliant;
  2. Authorization using decrypted card: the request contains the node Wallet and the merchant themselves decrypt e-wallet data and send the open data to authorization. This type of integration is recommended for merchants who are PCI DSS compliant.

Encrypted card

Request

{
  "MerchantOrderId": "2014111708",
  "Customer":{
    "Name": "Example Standard Wallet",
    "Identity": "11225468954",
    "IdentityType": "CPF"
  },
  "Payment":{
    "Type":"CreditCard",
    "Amount": 100,
    "Provider": "Cielo",
    "Installments":1,
    "Currency":"BRL",
    "Payment.Capture": "false",
    "Wallet": {
      "Type": "WALLET TYPE",
      "WalletKey": "WALLET STORE ID",
      "AdditionalData": {
        "EphemeralPublicKey": "TOKEN INFORMED BY WALLET"
      }
    }
  }
}
Property Description Type Size Required
MerchantId Store identifier at Braspag. (through header) GUID 36 Yes
MerchantKey Public key for dual authentication at Braspag. (through header) Text 40 Yes
RequestId Request identifier, used when the merchant uses different servers for each GET/POST/PUT. (through header) GUID 36 No
MerchantOrderId Order ID number. Text 50 Yes
Customer.Name Customer’s name. Text 255 Yes
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.Provider Cielo providers only (“Cielo” / “Cielo30”). Text 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”. Text Yes
Wallet.WalletKey Cryptographic key that identifies stores in wallets. Refer to the WalletKey table in the ANNEXES for more information. Text Yes
Wallet.AdditionalData.EphemeralPublicKey Token returned by wallet. Must be submitted in ApplePay integrations. Text Yes
Wallet.AdditionalData.Signature Token returned by wallet. Must be submitted in GooglePay integrations. Text Yes

WalletKey

WalletKey is the identifier used by Braspag to decrypt the payloads returned by an e-wallet.

Here is a list of the WalletKey formats to be passed \to the Pagador API:

Wallet Example  
Apple Pay 9zcCAciwoTS+qBx8jWb++64eHT2QZTWBs6qMVJ0GO+AqpcDVkxGPNpOR/D1bv5AZ62+5lKvucati0+eu7hdilwUYT3n5swkHuIzX2KO80Apx/
SkhoVM5dqgyKrak5VD2/drcGh9xqEanWkyd7wl200sYj4QUMbeLhyaY7bCdnnpKDJgpOY6J883fX3TiHoZorb/QlEEOpvYcbcFYs3ELZ7QVtjxyr
O2LmPsIkz2BgNm5f+JaJUSAOectahgLZnZR+easdhghrsa/E9A6DwjMd0fDYnxjj0bQDfaZpBPeGGPFLu5YYn1IDc
 
Samsung Pay eyJhbGciOiJSU0ExXzUiLCJraWQiOiIvam1iMU9PL2hHdFRVSWxHNFpxY2VYclVEbmFOUFV1ZUR5M2FWeHBzYXVRPS
IsInR5cCI6IkpPU0UiLCJjaGFubmVsU2VjdXJpdHlDb250ZXh0IjoiUlNBX1BLSSIsImVuYyI6IkExMjhHQ00ifQ.cCsGbqgFdzVb1jhXNR
–gApzoXH-fdafddfa-Bo_utsmDN_DuGm69Kk2_nh6txa7ML9PCI59LFfOMniAf7ZwoZUBDCY7Oh8kx3wsZ0kxNBwfy
LBCMEYzET0qcIYxePezQpkNcaZ4oogmdNSpYY-KbZGMcWpo1DKhWphDVp0lZcLxA6Q25K78e5AtarR5whN4HUAkurQ.CFjWpHkAVoLCG8q0.NcsTuauebemJXmos_mLMTyLhEHL-
p5Wv6J88WkgzyjAt_DW7laiPMYw2sqRXkOiMJLwhifRzbSp8ZgJBM25IX05dKKSS4XfFjJQQjOBHw6PYtEF5pUDMLHML3jcddCrX07abfef_DuP41PqOQYsjwesLZ8XsRj-
R0TH4diOZ_GQop8_oawjRIo9eJr9Wbtho0h8kAzHYpfuhamOPT718EaGAY6SSrR7t6nBkzGNkrKAmHkC7aRwe.AbZG53wRqgF0XRG3wUK_UQ
 
Google Pay {“encryptedMessage”:”0mXBb94Cy9JZhMuwtrBhMjXb8pDslrNsN5KhcEqnowOINqJgjXHD36KcCuzpQQ4cDAe64ZLmk2N3UBGXsN9hMMyeMakXlidVmteE
+QMaNZIor048oJqlUIFPD54B/ic8zCdqq3xnefUmyKQe0I03x57TcEA9xAT/E4x3rYfyqLFUAEtu2lT0GwTdwgrsT8pKoTldHIgP+wVNTjrKvJrB4xM/Bhn6JfcSmOzFyI6w37
mBU71/TK761nYOSxt7z1bNWSLZ4b8xBu1dlRgen2BSlqdafuQjV3UZjr6ubSvaJ8NiCh5FD/X013kAwLuLALMS2uAFS9j8cZ6R6zNIi13fK6Fe4ACbFTHw
LzSNZjQiaRDb6MlMnY8/amncPIOXzpirb5ScIz8EZUL05xd+3YWVTVfpqgFo1eaaS+wZdUyRG0QEgOsr6eLBoH8d5lfV9Rx6XdioorUuT7s1Yqc0OJZO
+fhBt6X0izE9hBGTexdZyg\u003d\u003d”,”ephemeralPublicKey”:”BMdwrkJeEgCOtLevYsN3MbdP8xbOItXiTejoB6vXy0Kn0ZM10jy4Aasd6jTSxtoxo
TpFydLhj5kzoOhbw2OzZu0\u003d”,”tag”:”yAQIjWZ0VuCC7SWyYwc4eXOzpSUKhZduF9ip0Ji+Gj8\u003d”}
 

EphemeralPublicKey

This is the EphemeralPublicKey format to be passed to the Pagador API:

Wallet Example
Apple Pay MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEoedz1NqI6hs9hEO6dBsnn0X0xp5/DKj3gXirjEqxNIJ8JyhGxVB3ITd0E+6uG4W6Evt+kugG8gOhCBrdUU6JwQ==

Signature

This is the Signature format to be passed to the Pagador API:

Wallet Example
Google Pay MEUCIQCGQLOmwxe5eFMSuTcr4EcwSZu35fB0KlCWcVop6ZxxhgIgbdtNHThSlynOopfxMIxkDs0cLh2NFh5es+J5uDmaViA=

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": "WALLET TYPE",
            "WalletKey": "WALLET STORE ID",
            "Eci": 0,
            "AdditionalData": {
                "EphemeralPublicKey": "TOKEN INFORMED BY 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.braspag.com.br/v2/sales/e57b09eb-475b-44b6-ac71-01b9b82f2491"
            },
            {
                "Method": "PUT",
                "Rel": "capture",
                "Href": "https://apisandbox.braspag.com.br/v2/sales/e57b09eb-475b-44b6-ac71-01b9b82f2491/capture"
            },
            {
                "Method": "PUT",
                "Rel": "void",
                "Href": "https://apisandbox.braspag.com.br/v2/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 the bearer bank statement. Available for VISA/MASTER only - no special characters allowed. 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 the acquirer. Text Alphanumeric
Type Wallet type: “ApplePay” / “SamsungPay” / “GooglePay”. Text Alphanumeric
WalletKey Cryptographic key that identifies stores in wallets. Check the WalletKey table in the ANNEXES for more information. Text See “WalletKey” table annexed
AdditionalData.EphemeralPublicKey Token returned by wallet. Must be submitted in ApplePay integrations. Text See “EphemeralPublicKey” table annexed
AdditionalData.Signature Token returned by wallet. Must be submitted in GooglePay integrations. Text See “Signature” table annexed

Decrypted card

If the merchant decrypts the payload received from the wallet and sends it to the the Gateway API for processing and authorization, they must use the following request model:

Request

{
  "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=="
    }
  }
}
--request POST "https://apisandbox.braspag.com.br/v2/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
-- 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.braspag.com.br/v2/sales/e57b09eb-475b-44b6-ac71-01b9b82f2491"
        },
        {
            "Method": "PUT",
            "Rel": "capture",
            "Href": "https://apisandbox.braspag.com.br/v2/sales/e57b09eb-475b-44b6-ac71-01b9b82f2491/capture"
        },
        {
            "Method": "PUT",
            "Rel": "void",
            "Href": "https://apisandbox.braspag.com.br/v2/sales/e57b09eb-475b-44b6-ac71-01b9b82f2491/void"
        }
    ]
  }
}

Integration examples

In this topic, we present integration examples with the main e-wallets available on the market. The examples comprehend the scenario for encrypted cards, in which WalletKey and other token identifiers are required in the authorization.

If the merchant will send the authorization request with decrypted card data, please refer to Decrypted card.

Apple Pay ™

Apple Pay is a digital wallet. It allows shoppers to make payments in e-commerce stores and apps in a safe and easy way, using credit and debit cards stored in their Apple account 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:

  1. Enroll your store through this URL, following all steps required by Apple.
  2. Follow the procedure set out in this document, in order to complete your integration with Apple.
  3. Hire Pagador API REST as the payment gateway.
  4. Hire Cielo 3.0 as the acquirer.
  5. Integrate with Pagador API REST.

PART 1 - Configuring the Merchant Identifier

To begin with, you must create a merchant identifier for your store. After that, the merchant identifier must be sent to Braspag in request for a “.CSR” certificate. The “.CSR” certificate created by Braspag must be used to create the new “.CER” certificate, in Apple. This “.CER” certificate will be used to proceed to the second part of the process.

Step 1 - Create a Merchant Identifier

The merchant identifier must be created through the Apple Developer website as follows:

  1. In the “Certificates, Identifiers & Profiles” section, select “Identifiers” on the side menu, and click the (+) button by the title: Step1.1
  2. Select the “Merchant IDs” option, then click Continue: Step1.2
  3. Insert values in the “Description” and “Identifier” fields, in accordance with each specification, and click Continue: Step1.3
  4. Finally click Register: Step1.4

Step 2 - Apply for a “.CSR” Certificate

To send Braspag a request for a certificate in the “.CSR” format, contact our Support Team informing the following:

  1. The Merchant Identifier created in “Step 1”;
  2. Your store “in production” Merchant ID at Braspag.

Our team will get back to you with the “.CSR” file in up to 48 working hours.

Step 3 - Create a “.CER” Certificate

To create a payment processing certificate (“.CER”) to be used in your virtual store or app, you must enter the Apple Developer website and follow the procedure below:

  1. In the “Certificates, Identifier & Profiles” section, select “Identifiers” on the side menu.
  2. Use the filter on the top right corner (“App IDs”), to locate the “Merchant IDs” item: Step2.1
  3. Select the recently created identifier: Step2.2
  4. In the “Apple Pay Payment Processing Certificate” block, click the Create Certificate button right after the short description: Step2.3
  5. Choose “No” in “Edit or Configure Merchant ID”: Step2.4
  6. In the dialog box, click Choose File and choose the “.CSR” certificate sent by Braspag: Step2.5
  7. Click Continue: Step2.6
  8. Click Download and save the “.CER” file: Step2.7

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.

Check below an example of how Apple API may send the JSON:

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

The parameter Payment.Wallet.WalletKey sent in Gateway authorization request should be filled with the value received from Apple in paymentData.data.

Important Note

PART 3. Integrating with Pagador

Authorization with the Apple Pay token happens in the same way as standard credit card authorization. However, instead of transmitting the card data openly, you must provide the token received from Apple Pay, as shown in the example below:

Request

{
   "MerchantOrderId": "2017051002",
   "Customer": {
     (…)
   },
   "Payment": {
      "Type": "CreditCard",
      "Amount": 1000,
      "Provider": "Cielo30",
      "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 Pagador. GUID (36)
MerchantKey API key in Pagador. String (24)
Parameter Description Type and Size
MerchantOrderId Order ID number. String (50)
Customer Node with customer’s data. Refer to the Pagador Guide.
Payment.Type Payment method type. Possibilities: “CreditCard” / “DebitCard”. String (100)
Payment.Amount Order amount in cents. Number (15)
Payment.Provider Name of payment method provider. For Apple Pay transactions, use “Cielo30”. String (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 authorization response returned by the wallet will have the same fields shown in our Pagador documentation, but 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. It allows shoppers to make payments in e-commerce stores and apps using their credit and debit cards stored in their Google Account 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:

  1. Agree to Google’s terms of service.
  2. Follow the steps in this documentation to thoroughly integrate Google Pay into your app.
  3. Hire Pagador API REST as the payment gateway.
  4. Hire Cielo 3.0 as the acquirer.
  5. Integrate with Pagador API REST.

PART 1: Integrating Google Pay

Initially, you must configure your project and implement Google Pay in your Android app.

Step 1 - Configure your Project

Follow the instructions described in the Google Pay Setup Guide.
In this step, you must add dependencies either by importing the Google Pay Services library or choosing the APIs you wish to compile. Then, you must follow the instructions and modify your project’s “AndroidManifest.xml” file accordingly.

Step 2 - Implement Google Pay

To integrate Google Play into your app, follow all the steps described in the Google Pay Tutorial Guide.

For an accurate integration of Google Pay using Braspag’s payment gateway, the following points must be carefully considered:

Gateway Definition

In “Step 2: Choose a payment tokenization method”, follow the “GATEWAY” integration model and assign the “PAYMENT_GATEWAY” value to the type parameter and the “cielo” value to the gateway parameter, according to the 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 the gatewayMerchantId with the identifier generated for your store by the gateway. The merchant identifier has the “XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX” format (type GUID / size 36).

Card Networks Definition

In “Step 3: Define supported payment card networks”, proceed with the supported brands: “VISA”, “MASTERCARD”, “AMEX”, “DISCOVER” and “JCB”.

Environment Definition

In “Step 5: Create a PaymentsClient instance”, use the “WalletConstants.ENVIRONMENT_TEST” value for test purposes.

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 buyer will see throughout the Google Pay payment process. Thus, the use of a 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.

Use the getPaymentMethodToken() method to get the PaymentMethodToken object from PaymentData. Click here for details.

After obtaining the PaymentMethodToken, use the GetToken() method, from the PaymentMethodToken object in order to obtain the string that contains the payment tokens. Click here for details.

The string obtained has a similar structure to the one in the following example. Click here for further information.

{
  "protocolVersion": "ECv1",
  "signature": "TJVA95OrM7E2cBab30RMHrHDcEfxjoYZgeFONFh7HgQ",
  "signedMessage": "{\"encryptedMessage\":
  \"ZW5jcnlwdGVkTWVzc2FnZQ==\",\"ephemeralPublicKey\":
  \"ZXBoZW1lcmFsUHVibGljS2V5\",\"tag\": \"c2lnbmF0dXJl\"}"
}
Parâmetro Type Descrição
signedMessage string Base64-encoded encrypted message containing payment information and some additional security fields.
signature string Base64-encoded ephemeral public key associated with the private key to encrypt the message in uncompressed point format.

(to see more details: https://developers.google.com/pay/api/android/guides/resources/payment-data-cryptography)

Hold the signedMessage and signature values. They will be requested in Braspag’s authorization process in PART 2, described ahead.

PART 2: Authorization with Token

The authorization with the Google Pay token must be performed in the same way as a standard authorization for a credit card. Although, instead of openly providing the card data, the token received through Google Pay must be provided, as in the example.

Request

{
  "MerchantOrderId": "2014111708",
  "Customer": {
    (…)
  },
  "Payment": {
    "Type": "CreditCard",
    "Amount": 100,
    "Provider": "Cielo30",
    "Installments": 1,
    "Wallet": {
      "Type": "AndroidPay",
      "WalletKey": "ZW5jcnlwdGVkTWVzc2FnZQ==",
      "AdditionalData": {
        "EphemeralPublicKey": "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 buyer’s data. Refer to the Pagador Guide.
Payment.Type Payment method type. Possible values: “CreditCard” / “DebitCard”. String (100)
Payment.Amount Transaction amount in cents. Number (15)
Payment.Provider Payment method provider name. For Google Pay, use “Cielo30”. String (15)
Payment.Installments Number of installments. Number (2)
Payment.Wallet.Type Wallet provider name. For Google Pay, use “AndroidPay”. String (15)
Payment.Wallet.WalletKey Provide the signedMessage received from Google Pay. String
Payment.Wallet.AdditionalData. EphemeralPublicKey Provide the signature received from Google Pay. String

For further information, refer to the Pagador Guide.

Response

The wallet authorization response will have the same fields as the ones presented in our Pagador documentation. The response will be added of the Payment.Wallet node, which will repeat the same fields used in the request and 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

Verify whether all items in the integration checklist have been completed.

After the validation in steps 1 and 2 is done, request your access credentials for the production environment.

Samsung Pay ™

Below is a prerequisite for using Samsung Pay, followed by an example of a request to make it available in your store.

The store must already have Samsung registration and integration before integrating with the Pagador API. For more information, refer to Samsung Pay documentation.

Request

Example of a standard Samsung Pay request:

{
  "MerchantOrderId":"6242-642-723",
  "Customer":{
     "Name": "Example Standard Wallet",
     "Identity": "11225468954",
      "IdentityType": "CPF"
  },
  "Payment":{
     "Type":"CreditCard",
     "Amount": 1,
     "Provider": "Cielo",
     "Installments":1,
     "Currency":"BRL",
     "Wallet":{
       "Type":"SamsungPay",
       "WalletKey":"eyJhbGciOiJSU0ExXzUiLCJraWQiOiIvam1iMU9PL2hHdFRVSWxHNFpxY2VYclVEbmFOUFV1ZUR5M2FWeHBzYXVRPSIsInR5cCI6IkpPU0UiLCJjaGFubmVsU2VjdXJpdHlDb250ZXh0IjoiUlNBX1BLSSIsImVuYyI6IkExMjhHQ00ifQ.cCsGbqgFdzVb1jhXNR--gApzoXH-LldMArSoG59x6i0BbI7jttqxyAdcriSy8q_77VAp3854P9kekjj54RKLrP6APDIr46DI97kjG9E99ONXImnEyamHj95ZH_AW8lvkfa09KAr4537RM8GEXyZoys2vfIW8zqjjicZ8EKIpAixNlmrFJu6-Bo_utsmDN_DuGm69Kk2_nh6txa7ML9PCI59LFfOMniAf7ZwoZUBDCY7Oh8kx3wsZ0kxNBwfyLBCMEYzET0qcIYxePezQpkNcaZ4oogmdNSpYY-KbZGMcWpo1DKhWphDVp0lZcLxA6Q25K78e5AtarR5whN4HUAkurQ.CFjWpHkAVoLCG8q0.NcsTuauebemJXmos_mLMTyLhEHL-p5Wv6J88WkgzyjAt_DW7laiPMYw2sqRXkOiMJLwhifRzbSp8ZgJBM25IX05dKKSS4XfFjJQQjOBHw6PYtEF5pUDMLHML3jcddCrX07abfef_DuP41PqOQYsjwesLZ8XsRj-R0TH4diOZ_GQop8_oawjRIo9eJr9Wbtho0h8kAzHYpfuhamOPT718EaGAY6SSrR7t6nBkzGNkrKAmHkC7aRwe.AbZG53wRqgF0XRG3wUK_UQ"
    }
  }
}

Property Description Type Size Required
MerchantId Store identifier at Braspag. GUID 36 Yes (through header)
MerchantKey Public key for dual authentication at Braspag. Text 40 Yes (through header)
RequestId Request identifier, used when the merchant uses different servers for each GET/POST/PUT. GUID 36 No (through header)
MerchantOrderId Order ID number. Text 50 Yes
Customer.Name Customer’s name. Text 255 Yes
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.Provider Cielo providers only (“Cielo” / “Cielo30”). Text 15 Yes
Payment.Installments Number of installments. Number 2 Yes
Wallet.Type Wallet type: “ApplePay” / “SamsungPay” / “GooglePay”. Text 255 Yes
Wallet.WalletKey Cryptographic key that identifies stores in wallets. Check the WalletKey table in the ANNEXES 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": "eyJhbGciOiJSU0ExXzUiLCJraWQiOiIvam1iMU9PL2hHdFRVSWxHNFpxY2VYclVEbmFOUFV1ZUR5M2FWeHBzYXVRPSIsInR5cCI6IkpPU0UiLCJjaGFubmVsU2VjdXJpdHlDb250ZXh0IjoiUlNBX1BLSSIsImVuYyI6IkExMjhHQ00ifQ.cCsGbqgFdzVb1jhXNR--gApzoXH-LldMArSoG59x6i0BbI7jttqxyAdcriSy8q_77VAp3854P9kekjj54RKLrP6APDIr46DI97kjG9E99ONXImnEyamHj95ZH_AW8lvkfa09KAr4537RM8GEXyZoys2vfIW8zqjjicZ8EKIpAixNlmrFJu6-Bo_utsmDN_DuGm69Kk2_nh6txa7ML9PCI59LFfOMniAf7ZwoZUBDCY7Oh8kx3wsZ0kxNBwfyLBCMEYzET0qcIYxePezQpkNcaZ4oogmdNSpYY-KbZGMcWpo1DKhWphDVp0lZcLxA6Q25K78e5AtarR5whN4HUAkurQ.CFjWpHkAVoLCG8q0.NcsTuauebemJXmos_mLMTyLhEHL-p5Wv6J88WkgzyjAt_DW7laiPMYw2sqRXkOiMJLwhifRzbSp8ZgJBM25IX05dKKSS4XfFjJQQjOBHw6PYtEF5pUDMLHML3jcddCrX07abfef_DuP41PqOQYsjwesLZ8XsRj-R0TH4diOZ_GQop8_oawjRIo9eJr9Wbtho0h8kAzHYpfuhamOPT718EaGAY6SSrR7t6nBkzGNkrKAmHkC7aRwe.AbZG53wRqgF0XRG3wUK_UQ",
            "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.braspag.com.br/v2/sales/e57b09eb-475b-44b6-ac71-01b9b82f2491"
            },
            {
                "Method": "PUT",
                "Rel": "capture",
                "Href": "https://apisandbox.braspag.com.br/v2/sales/e57b09eb-475b-44b6-ac71-01b9b82f2491/capture"
            },
            {
                "Method": "PUT",
                "Rel": "void",
                "Href": "https://apisandbox.braspag.com.br/v2/sales/e57b09eb-475b-44b6-ac71-01b9b82f2491/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 Examples: 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: “ApplePay” / “SamsungPay” / “GooglePay”. Text 255 Alphanumeric
WalletKey Cryptographic key that identifies stores in wallets. Check the WalletKey table in the ANNEXES for more information. Text 255 See “WalletKey” table

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.