PIX - Boletos

Citibank

Carat allows payment of boletos through Citibank.

In this page, the nomenclature "Citibank" will be used to reference the acquirer on Carat Portal.

Carat Portal Interfaces Supported for Integration

The following interfaces for integration with Boleto Citibank are available:

• REST payment
• HTML Payment
• Reprint of boletos

Required credentials

The merchant must obtain with Citibank the credentials listed below, and pass them to Software Express.

The store may also request the configuration of some parameters of default values ​​with Software Express.

Citibank payemnt flow

1. Successfully generated the boleto.
2. The Payment Transaction will remain in 'Processed' status.
3. The merchant will receive from Citibank a file with the data of the slips and situation, informing if they were paid.

Payment REST

Boleto payment follows the normal payment flow

Transaction creation

More details in topic Transaction creation

Ex:

{
    "merchant_usn": "7112400307",
    "order_id": "07112400307",
    "amount": "2400",
    "installments": "1",
    "installment_type": "4",
    "authorizer_id": "2601",
    "additional_data": {
        "payer": {
            "name": "Steve",
            "surname": "Harris",
            "address": {
                "zip_code": "01307001",
                "street_number": "35",
                "street_name": "Avenida Paulista",
                "complement": "Ap 10",
                "district": "bela vista",
                "city": "São Paulo",
                "state": "SP",
                "country": "BR"
            },
            "documents": [
                {
                    "type": "CPF",
                    "number": "60861648005"
                }
            ]
        },
        "boleto": {
            "assignor_code": "99999999999999999999",
            "your_number": "1646940087",
            "expiration_date": "20/03/2022",
            "issue_date": "10/03/2022",
            "specie_type": "01",
            "company_identification": "identificacao_empresa",
            "assignor": "XPTO COMPUTADORES DO BRASIL LTDA",
            "assignor_document": {
                "type": "CNPJ",
                "number": "72381189000110"
            },
            "assignor_address": {
                "zip_code": "01307001",
                "street_number": "999",
                "street_name": "Avenida YYZ",
                "complement": "Ap 3000",
                "district": "bela vista",
                "city": "São Paulo",
                "state": "SP",
                "country": "BR"
            },
            "instructions": [
                {
                    "message": "ficha_compensacao msg1"
                },
                {
                    "message": "ficha_compensacao msg2"
                }
            ],
            "receipt_messages": [
                {
                    "message": "recibo msg1"
                },
                {
                    "message": "recibo msg2"
                }
            ]
        }
    }
}

Payment Effectuation

More details in topic Payment effectuation

The effectuation payment response delivers some unique data from the boleto payment

Ex request:

{
    "authorizer_id": "2601"
}

Ex response:

{
    "code": "0",
    "message": "OK. Transaction successful.",
    "payment": {
        "authorizer_message": "OK",
        "status": "PRO",
        "nit": "9901701cc1631cf6fc71a38b0a6e8dba8b8130f2ad1c3109643753223dba312b",
        "order_id": "07112400307",
        "authorizer_id": "2601",
        "acquirer_id": "2601",
        "acquirer_name": "Boleto Citibank",
        "merchant_usn": "7112400307",
        "esitef_usn": "220310093364750",
        "amount": "2400",
        "payment_type": "B",
        "payment_date": "10/03/2022T16:29",
        "boleto": {
            "digitable_line": "47720953885052730207262219741330432820197130661",
            "url": "https://esitef-homologacao.softwareexpress.com.br/e-sitef/reissue.se?nit=9901701cc1631cf6fc71a38b0a6e8dba8b8130f2ad1c3109643753223dba312b"
        }
    }
}

Web Checkout

Transaction creation

More details in topic Transaction creation

Ex:

{
    "merchant_id": "BOLETOCITI",
    "merchant_usn": "7112400307",
    "order_id": "07112400307",
    "amount": "2400",
    "installments": "1",
    "installment_type": "4",
    "authorizer_id": "2601",
    "additional_data": {
        "payer": {
            "name": "Steve",
            "surname": "Harris",
            "address": {
                "zip_code": "01307001",
                "street_number": "35",
                "street_name": "Avenida Paulista",
                "complement": "Ap 10",
                "district": "bela vista",
                "city": "São Paulo",
                "state": "SP",
                "country": "BR"
            },
            "documents": [
                {
                    "type": "CPF",
                    "number": "60861648005"
                }
            ]
        },
        "boleto": {
            "assignor_code": "99999999999999999999",
            "your_number": "1646940087",
            "expiration_date": "17/08/2022",
            "issue_date": "10/03/2022",
            "specie_type": "01",
            "company_identification": "identificacao_empresa",
            "assignor": "XPTO COMPUTADORES DO BRASIL LTDA",
            "assignor_document": {
                "type": "CNPJ",
                "number": "72381189000110"
            },
            "assignor_address": {
                "zip_code": "01307001",
                "street_number": "999",
                "street_name": "Avenida YYZ",
                "complement": "Ap 3000",
                "district": "bela vista",
                "city": "São Paulo",
                "state": "SP",
                "country": "BR"
            },
            "instructions": [
                {
                    "message": "ficha_compensacao msg1"
                },
                {
                    "message": "ficha_compensacao msg2"
                }
            ],
            "receipt_messages": [
                {
                    "message": "recibo msg1"
                },
                {
                    "message": "recibo msg2"
                }
            ]
        }
    }
}

Optional data in Web Checkout

If the buyer's Name, Document and Address data are not sent, a form will be displayed for the buyer to fill out.

Mandatory fields

So that the customer can make a boleto bancário payment, it's necessary that the store submits to Carat Portal the following information:

Reprint of boletos

It is possible to make available to customers the reprint of Citibank boletos.

That functionality is available through the URL:

The nit used in the original payment transaction, made via Citibank Boleto, must be informed as a GET parameter. Accessing this URL allows viewing the boleto.

If the payment transaction is not in the expected state, it is present an error message.

Attention

The IP address must never be used instead of the domain (or for Certification and Test environment). The IP address can change at any moment without notice, so it is important to always use the domain to access Carat Portal.

PIX - Digital Wallets

A Digital Wallet is an application that securely stores credit/debit/voucher cards in order to facilitate the buyer when performing a payment.

Digital Wallets alone provide only cardholder/card information, and a payment method is required to use this data to actually perform the payment.

The Carat Portal fits into this flow as the Payment Gateway.

This page aims to clarify how a Digital Wallet integrates with Carat Portal services.

Supported Digital Wallets

The Carat Portal supports the following Digital Wallets:

• Google Pay
• Masterpass
• Visa Chechout

Routing/Acquirers with 3DS authentication support

When adding a card within a Digital Wallet it is possible (when supported) to perform authentication (3DS) during the registration process. When a card is registered in this way, the Digital Wallet will pass on this authentication data to Carat Portal, which in turn will pass on this data to the acquirers.

The routing/acquirers that support 3DS authentication are:

• SiTef [*]
• Cielo e-Commerce
• e.Rede REST
• Getnet WS
• GlobalPayments WS
• SafraPay

[*] Contact our Carat Portal support team for more information on 3DS authentication support on SiTef.

Integration flow via REST Payment

For further information about REST Payment, access the REST Payment - Overview page.

Below will be presented the basic flow of Digital Wallets integration with Carat Portal using the REST Payment interface.

In this scenario, the integration with the Digital Wallet is splitted between Virtual Store and Carat Portal:

1. The Costumer initiates the checkout process inside the Virtual Store and chooses a Digital Wallet as the payment method.
2. The Virtual Store, which integrated with the first stage of the Digital Wallet integration (opening the wallet) will show the Digital Wallet interface to the Costumer.
3. The Costumer will choose, within the Digital Wallet, the card that will be used to make the payment for the purchase.
4. After the Costumer chooses the card, the Digital Wallet will return the encrypted card and purchase data to the Virtual Store application.
5. With the encrypted data in hand, the Virtual Store will transfer it to our REST Payment interface through the card.wallet_transaction_id field.
6. The Carat Portal will receive the encrypted data and decrypt it, that is, Carat Portal will have access to the card data to send it to the acquirers to effectively perform the payment.
7. The Carat Portal returns to the Virtual Store the transaction result.
8. The Virtual Store in turn passes the response from Carat Portal to the Cosutmer.

Integration flow via HTML Payment

For further information about REST Payment, access the HTML Payment - Overview page.

Below will be presented the basic flow of Digital Wallets integration with Carat Portal using the HTML Payment interface.

In this scenario, the integration with the Digital Wallet is carried out entirely by Carat Portal:

1. The Costumer initiates the checkout process inside the Virtual Store
2. The Virtual Store initiates a transaction and redirects the Costumer to the Carat Portal checkout page.
3. The Costumer, already redirected to the Carat Portal checkout page, verifies the payment options.
4. The Costumer chooses a Digital Wallet as payment method.
5. The Digital Wallet interface will be displayed for the Costumer who then chooses the card.
6. Digital Wallet will return encrypted card/purchase data to Carat Portal.
7. The Carat Portal will receive the encrypted card/purchase data and will decrypt it, that is, it will have access to the card data to send it to the acquirers to effectively perform the payment.
8. The Carat Portal returns the result of the transaction to the Customer.

Contents of the card.wallet_transaction_id field

The content to be sent in the card.wallet_transaction_id field via the REST Payment interface varies according to the Digital Wallet to be integrated. Consult the specific documentation for more details.

Samsung Pay

How it works

When the payer clicks on the Samsung Pay payment button, the payment methods saved in the Samsung Pay account are displayed. The buyer can quickly select the desired payment method and optionally fill in additional purchase information. After this interaction with Samsung Pay, this same data will be sent / processed by Carat Portal to make the payment flow.

For more information on the payment flow with wallets, see the Overview page.

Required registration data

In cases of integration via the REST API, it will be necessary for the merchant to use the Software Express Service ID with Samsung. To obtain the Service ID of the homologation / production environment contact our support team.

Supported flags

The following card networks available at Samsung Pay (Brazil) are supported by Carat Portal:

REST Payment / Pre-Authorization

In the REST Payment or REST Pre-Authorization, the merchant must perform the first part of the integration with Samsung Pay (all steps of integration until obtaining the Reference ID). please contact Samsung support for more details.

The Reference ID must then be passed on to our REST interfaces.

Send the data to Carat Portal

When the merchant completes the first part of the integration with Samsung Pay, the Reference ID will be obtained.

This data must be passed through the card.wallet_transaction_id field of the interface.

curl -X POST \
  https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/payments/<NIT> \
  --header "Content-Type: application/json" \
  --header "merchant_id: <MERCHANT_ID>" \
  --header "merchant_key: <MERCHANT_KEY>" \
  --data-binary '{
    "authorizer_id": "410",
    "card": {
        "wallet_transaction_id": "ReferenceIdExample"
    }
}'

In the example above, it was defined in the authorizer_id field with the value'410', which corresponds to selecting Samsung Pay as the payment method; and was defined in the wallet_transaction_id field with the value of Samsung Pay's Reference ID. A successful execution of the above command will return a JSON similar to the one below.

{
  "code": "0",
  "message": "OK. Transaction successful.",
  "payment": {
    "authorizer_code": "000",
    "authorizer_message": "Transacao OK",
    "status": "CON",
    "nit": "<NIT>",
    "order_id": "13034649671",
    "customer_receipt": "====PAYER RECEIPT====",
    "merchant_receipt": "====MERCHANT RECEIPT====",
    "authorizer_id": "410",
    "acquirer_id": "1005",
    "acquirer_name": "Redecard",
    "authorizer_date": "28/02/2020T08:57",
    "authorization_number": "132030",
    "merchant_usn": "13034649671",
    "esitef_usn": "170713097340300",
    "sitef_usn": "132030",
    "host_usn": "999132030",
    "payment_date": "13/07/2017T15:52",
    "amount": "1000",
    "payment_type": "C",
    "issuer": "2",
    "authorizer_merchant_id": "<MERCHANT_ID>"
  }
}

HTML Payment/Pre-Authorization

To use Samsung Pay with HTML payment/pre-authorization, contact a member of our support team to perform the necessary configuration. It is possible to determine which flags will be accepted in Samsung Pay for HTML integration.

Important:
Unlike other digital wallets, payment with Samsung Pay will not require CVV on confirmation. It is the responsibility of the merchant to negotiate with the acquirers to perform payments without the requirement of the security code. Otherwise, this parameter will be requested during the transaction flow.

However, even if the acquirers allow transactions without the security code (CVV2), there is no guarantee that the issuer (Financial Institution) accepts a transaction with this condition (no security code).

REST Capture of Pre-Authorization and REST Cancellation/via Portal

Samsung Pay does not allow the same Reference ID to be used more than once. Because of this, two-step operations such as Payment/Cancellation, Pre-Authorization/Capture require that the card be stored in Carat Portal. The storage via the HTML interface can be done together with the payment/pre-authorization following the documentation of Payment with card storage or through the REST interface, as described in the chapter below.

REST Card Storage

Card storage is possible using Samsung Pay's Reference ID. Please contact our support team to make the necessary settings to enable this storage.

REST card storage works as if you were to store any card, but with the following precautions:

• Instead of sending the card number, send the wallet_transaction_id field with the content of the Reference ID.
• The authorizer_id field must be '410' (Samsung Pay).

For more details, see here.

Apple Pay

Apple Pay is now available!

Benefits

• Increase Conversion Rates with Apple Pay.
• Grow your business by making checkout easy with Apple Pay and [PSP].
• Boost sales by offering a fast, simple, and secure checkout experience with Apple Pay.
• Improve Privacy and Security: Every transaction requires authentication with Face ID, Touch ID, or passcode.

Apple Pay boosts conversion rates and user adoption by making buying easier than ever. It’s a simple and secure way for online
shoppers to speed through checkout and for online businesses to increase sales. It's a win for shoppers and a win for businesses.

Introduction

Apple Pay is a wallet available only for iOS devices with a Secure Element - a chip that securely stores payment information. The list of compatible devices can be found here.

Apple Pay offers 2 JavaScript APIs for web integration - the Apple Pay JS API and the Payment Request API. For integration with Carat Portal, was chosen the Apple Pay JS API. Both APIs are natively available in the Safari browser.

How it works

As mentioned in the previous section, due to its availability on compatible devices, the payment button via Apple Pay will only be displayed on compatible devices. Once the buyer is on the payment screen with the available Apple Pay payment method, simply click on the payment button to select the desired card for payment. When the buyer clicks on the Apple Pay button, selects the card and confirms the transaction, interactions must occur between Carat Portal and Apple Pay, to create the payment transaction and confirm the payment. After the last interaction with Apple Pay, the transaction is processed on Carat Portal for payment confirmation.

For more information on the payment flow with wallets, see the Overview page.

Required registration data

The merchant must register their Merchant ID on the Apple system. This registration acts as the store identification at Apple for Carat Portal. It is also necessary to associate this record with the Carat Portal certificate and with a domain, which would be the address of the payment page (where the Apple Pay payment button is made available). For this 2nd step, contact our support team.

Supported payment networks

The following payment networks are available at Apple Pay (Brazil) and supported by Carat Portal: Visa and MasterCard.

Integrate with Apple Pay

To start processing payments with Apple Pay, you need to integrate Apple via the Web. During the integration, you will see that some parameters are required to process Apple Pay via Carat Portal:

• The merchantIdentifier parameter must be filled in with the Merchant ID of the store in Carat Portal. It is enough to have registered the same in the Apple Pay portal and in the store configuration in Carat Portal that it will be automatically filled out and sent in the requisition to Apple Pay;
• The domainName parameter must be filled in with the domain of the store's website. Just have the same registered on the Apple Pay portal, associated with the Merchant ID, and it will be validated correctly with Apple Pay.

These parameters are used in the first request for Apple Pay (when the Apple Pay button is clicked), called "startSession", which has the function of creating the payment session, identifying which store the request comes from. The data entered is validated on the Apple server and returns an error when the data entered in the request does not correspond to the data registered with Apple.

Here is an example of a request for startSession:

 curl --location --request POST 'https://apple-pay-gateway-cert.apple.com/paymentservices/startSession' \
--header 'Content-Type: application/json' \
--data-raw '{
    "merchantIdentifier": "merchant.br.com.softwareexpress.teste.e-SiTef",
    "domainName": "esitef-homologacao.softwareexpress.com.br",
    "displayName": "Teste Apple Pay para eSiTef"
}'

The Apple Pay JS API coordinates all calls required for Apple Pay to complete the transaction. After startSession, the latter's response is passed on to completeMerchantValidation. At this time, the Apple Pay payment window has successfully validated the store's credentials and is awaiting confirmation of payment by the user. When the user confirms the payment, using a password or fingerprint, the onpaymentauthorized function is activated, with the payment information encrypted within the event object.

// function that integrates Apple Pay operations with back-end calls
var _handleApplePayEvents = function (appleSession) {
  // store identification validation
  // first function called when Apple Pay button is clicked
  appleSession.onvalidatemerchant = function (event) {
    // call to startSession and then the response is sent to completeMerchantValidation
    _validateApplePaySession(event.validationURL, function (merchantSession) {
      appleSession.completeMerchantValidation(merchantSession);
    });
  };
  };

REST Payment / Pre-Authorization

In the form of Payment or Pre-Authorization, the retailer must perform the first part of the integration with Apple Pay (all the steps described in the previous section to obtain the token). For more details regarding this process of obtaining the token, it is recommended to contact Apple Pay support.

The obtained token must then be passed on to our REST interfaces.

Send the data to Carat Portal

When you complete the first part of the integration with Apple Pay, you will have the token at hand.

This data must be passed through the card.wallet_transaction_id field of the interface.

curl -X POST \
  https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/payments/<NIT> \
  --header "Content-Type: application/json" \
  --header "merchant_id: <MERCHANT_ID>" \
  --header "merchant_key: <MERCHANT_KEY>" \
  --data-binary '{
    "authorizer_id": "421",
    "card": {
        "wallet_transaction_id": "some token from Apple Pay"
    }
}'

In the example above, it was defined in the authorizer_id field with the value 421, which corresponds to selecting Apple Pay as a form of payment and was defined in the wallet_transaction_id field with the value of the Apple Pay token. A successful execution of the above command will return a JSON similar to the one below.

{
  "code": "0",
  "message": "OK. Transaction successful.",
  "payment": {
    "authorizer_code": "000",
    "authorizer_message": "Transacao OK",
    "status": "CON",
    "nit": "<NIT>",
    "order_id": "13034649899",
    "customer_receipt": "====CUPOM COMPRADOR====",
    "merchant_receipt": "====CUPOM ESTABELECIMENTO====",
    "authorizer_id": "421",
    "acquirer_id": "1005",
    "acquirer_name": "Redecard",
    "authorizer_date": "12/03/2021T14:33",
    "authorization_number": "132030",
    "merchant_usn": "13034649671",
    "esitef_usn": "170713097340300",
    "sitef_usn": "132030",
    "host_usn": "999132030",
    "payment_date": "12/03/2021T15:52",
    "amount": "1000",
    "payment_type": "C",
    "issuer": "2",
    "authorizer_merchant_id": "<MERCHANT_ID>"
  }
}

HTML Payment/Pre-Authorization

To use Apple Pay with your HTML payment / pre-authorization, contact a member of our support team to perform the necessary setup. It is possible to determine which flags will be accepted in Apple Pay for HTML integration.

REST Capture of Pre-Authorization and REST Cancellation/via Portal

Apple Pay does not allow the same token to be used more than once. Because of this, two-step operations such as Payment / Cancellation, Pre-Authorization / Capture requires that the payer's card be stored in Carat Portal. The storage through the HTML interface can be carried out together with the payment / pre-authorization, following the Payment documentation with card storage or through the REST interface, as described in the following section.

REST Card Storage

Card storage is possible using Apple Pay's token. Please contact our support team to make the necessary configurations to enable this storage.

The REST card storage works as if you were going to store any card, but with the following precautions:

• Instead of sending the card number, send the wallet_transaction_id field with the content of the token.
• The authorizer_id field must be '421' (Apple Pay).

For more details, see here.

Merchant Key Management

For the correct processing of a transaction by ApplePay, it is necessary to have a public key register on the Apple Server. The public and private keys provided by the Apple Server will serve as the basis for the decript of the payload sent by the Apple JS library. This is the first step in setting up a Merchant to receive ApplePay payments.

In this guide you can see more details of the registration of keys on the Apple Server.

After registering the keys, it is necessary to contact our support and inform them, so that they can be configured in the store register. Apple requires that it is possible to register two key pairs. Each key has a validity period and the merchant will be in charge of managing the validity and informing the new keys to Software Express support.

Important: Note that there are 2 key pairs - one pair is responsible for decryption and the other pair is responsible for creating a server connection session with Apple.

Mercado Pago

This documentation describes the integration with Mercado Pago payment platform and also explains about the settings that must be made at the Carat Portal environment.

Carat Portal supported Interfaces for integration

It is possible to use the following interfaces for integration with Mercado Pago routing:

• HTML Payment

Required credentials

The merchant must get at the Carat Portal-Portal the credentials listed below, and pass them on to Software Express or register on the Carat Portal-Portal.

Authorizer codes

Below are the codes to be used in this integration:

• 440: PIX
• 402: other forms of payment with Mercado Pago

Attention: In Mercado Pago's approval environment, it is not possible to simulate an approved PIX transaction. The transaction will be pending.

Mercado Pago specific parameters

HTML payment creation service

Below are the Mercado Pago-specific requisition parameters for the HTML payment creation service:

JSON example:

{
  "merchant_id": "LOJAMERCADOPAGO",
  "merchant_usn": "123456",
  "amount": "100",
  "soft_descriptor": "softDescriptor",
  "additional_data": {
    "extra_info": "extraInfo",
    "items": [
      {
        "title": "Camiseta",
        "quantity": "1",
        "unit_price": "100",
        "picture_url": "https://abc.def/item/552292339/zoom/10.jpg",
        "category_id": "fashion",
        "description": "Camiseta Preta",
        "id": "id"
      }
    ],
    "payer": {
      "name": "Jonas",
      "surname": "Melo",
      "email": "[email protected]",
      "date_created": "11/02/2015",
      "address": {
        "zip_code": "12345678",
        "street_number": "751",
        "street_name": "Rua Major Vitor"
      },
      "phones": [
        {
          "number": "912341234",
          "ddd": "11"
        }
      ],
      "identification_type": "CPF",
      "identification_number": "86670573049"
    },
    "payment_method": {
      "excluded_payment_methods": [
        {
          "id": "debelo"
        }
      ],
      "excluded_payment_types": [
        {
          "id": "debit_card"
        }
      ]
    },
    "shipment": {
      "mode": "not_specified",
      "local_pickup": "true",
      "dimensions": "23x23x23, 23g",
      "default_shipping_method": "45",
      "cost": "2",
      "free_shipment": "true",
      "address": {
        "zip_code": "87654321",
        "street_number": "920",
        "street_name": "Rua General Henrique",
        "floor": "1",
        "apartment": "23",
        "city": "São Mateus",
        "state": "AM"
      },
      "free_methods": [
        {
          "id": "621"
        }
      ]
    },
    "max_installments": "12",
    "application_fee": "1",
    "acquirer_expiry_date": "2021-06-02T11:05:27",
    "acquirer_expiry_date_from": "2021-06-01T11:05:27",
    "acquirer_expiry_date_to": "2021-06-03T11:05:27",
    "acquirer_expires": "false",
    "ad_tracks": [
      {
        "conversion_id": "conversionId",
        "type": "google_ad",
        "conversion_label": "conversionLabel"
      }
    ]
  }
}

Masterpass

Carat Portal allows the integration of the merchant's e-commerce with payments that authenticate through Masterpass digital wallet. The customer makes their payment online without entering data from their card, using only user data (e-mail or phone number) and password. For this, the customer needs only to open an account with Masterpass first and register their credit and / or debit card information.

It is important to remember that Masterpass is not a payment method, so it does not process transactions. This is an digital wallet that perform customer authentication and provides the payment data to the merchant or for processing partners such as Carat Portal.

Supported Carat Portal interfaces

The following interfaces for integration with Masterpass are available:

• HTML Payment Interface 2.0 Learn more
• Cancel Web Service Interface Learn more
• Refund on the Merchant’s Portal on Carat Portal Learn more

Masterpass authorizer id

The Masterpass digital wallet is identified in Carat Portal by the folowing authorizer id:

"authorizer_id": "407"

Required Configurations

Before making Masterpass transactions with Carat Portal, the configuration steps presented below must be followed.

Merchant’s account data on Masterpass Portal

The merchant must contact Software Express to request a Masterpass account creation to Carat Portal Support or Production teams that will process the request.

Required configurations on Carat Portal

After the Masterpass account creation, the following authorizer parameters must be registered on Carat Portal:

These parameters should be reported to the Carat Portal registration team.

Allowed Authorizers / Cards

According to the documentation (version 1 - last update on: February 1, 2017), the authorizers / cards currently allowed by Masterpass are:

• Mastercard
• Visa
• American Express
• Discover
• Maestro
• Diners

However, changes may occur, and therefore, for a more up-to-date information we strongly suggest the merchant to contact Masterpass and confirm this information.

Masterpass Payment Flow

The basic payment flow using the Masterpass digital wallet starts as presented in the HTML payment integration.

The image below presents a Masterpass payment flow:

Status Notification

For each transaction status change on Carat Portal, resulting from the communication between Carat Portal and Masterpass, a status notification is sent to the merchant’s server. Learn more

Parameters for a payment transaction with the Masterpass digital wallet

The parameters used to create a payment transaction with the Masterpass digital wallet are the same as the ones presented in the HTML Payment, HTML Pre-Authorization e HTML Recharge.

Refunding Masterpass payments

The payments made on Carat Portal with the Masterpass digital wallet can be reversed using the Rest Cancel or the Merchant’s Portal.

Note that it’s required to have a card number to allow a refund. For this, it’s necessary to store the card on Carat Portal and call the cancellation service using the token / card Hash (Learn more) OR contact directly the card holder to obtain the number.

Visa Checkout

Carat Portal has Visa Checkout digital wallet as a functionality for integration with the merchant’s application.

It allows the merchant to not have any direct contact with customer card and personal data collection, using the interface and the communication structure developed by VISA for payments using this technology.

Supported routings

Currently, the Visa Checkout integration via Web Services is supported for payments routed via SiTef, Cielo e-Commerce and Stone WS.

Supported Carat Portal interfaces

The supported interfaces on Carat Portal for using Visa Checkout are:

• REST Payment
• REST Cancel
• REST Pre-Authorization

For further details about these interfaces, the merchant must have their respective integration manuals. If necessary, they must be requested to our support team.

Required configurations on Carat Portal

For a merchant to use the Visa Checkout digital wallet on Carat Portal, simply ask the Carat Portal support team to set up.

REST integration requirements

The merchant’s application must be integrated with Visa Checkout on its graphical interface and on its JavaScript callback communications to obtain the callid parameter. This field is necessary to integrate with Carat Portal’s REST payment interface.
For further details about this integration, the merchant must request the integration guide to VISA and develop the integration with the Visa Checkout Button and the LightBox.

Flows

The payment flows for using Carat Portal with Visa Checkout via Web Services assume that the merchant’s application fulfills the requirements presented in the previous item, which means that application is already capable of using Carat Portal’s Web Services with the callid.

REST payment flow

The payment flow for using Carat Portal with Visa Checkout assumes that the merchant's application is already following the requirements present in the previous item, which means that the application is capable of using Carat Portal's REST interfaces after getting the callid.

The figure below presents the sequence diagram for the integration with Carat Portal and Visa Checkout:

To pay Visa Checkout transactions via REST, the merchant's application must send the wallet_transaction_id instead of the card number in the card object. Optionally, it's also possible to send initial_wallet_transaction_id, which informs whether this is the first time that this wallet_transaction_id is being used. If it isn't defined, its default value is true. Below is an example with the cUrl application where the acquirer requests sending the security code on the payment:

To use this example, don't forget to define the variable {{url}} with the value

curl 
--request POST "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/payments/xxxxxxxxxxxx...xxxxxxxxxxxxx"
--header "Content-Type: application/json"
--header "merchant_id:wwwwwww"
--header "merchant_key:yyyyyyyyyyyyyyyyyyyyyy"
--data-binary
{
   "card":{
      "wallet_transaction_id":"callid_de_teste",
      "initial_wallet_transaction_id":"false",
      "security_code":"123"
   }
}
--verbose

Learn more.

REST pre-authorization flow

As in the REST payment, the pre-authorization interface can also receive the wallet_transaction_id and initial_wallet_transaction_id fields.

In case of payments with promotional amounts for using Visa Checkout, VISA suggests that the subtotal, discount and promo_code fields are sent additionally on the pre-authorization effectuation service and the pre-authorization capture service. Learn more.

Sending these fields isn't mandatory. However, it's extremely recommended by VISA for enriching statistical data of Visa Checkout usage and improving related services.
These fields are sent to the Visa Checkout systems along with information regarding total amount, currency and order id.
To clarify the usage of these fields, here is an example: supposing a transaction of a product which has an amount of $ 80,00, with a discount of 10% ($ 8,00) and resulting in a liquid amount of $ 72,00, the fields must be filled as follows:

amount: R$ 72,00
subtotal: R$ 80,00
discount: R$ 8,00
amount = subtotal - discount = R$ 80,00 - R$ 8,00 = R$ 72,00

REST cancel

For cancelling or reversing Visa Checkout transactions, the merchant's application must send the wallet_transaction_id instead of the card number in the card object. Below is an example with the cUrl application where the acquirer requests sending the security code:

To use this example, don't forget to define the variable {{url}} with the value

curl 
--request PUT "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/cancellations/xxxxxxxxxxxx...xxxxxxxxxxxxx"
--header "Content-Type:application/json"
--header "merchant_id:wwwwwww"
--header "merchant_key:yyyyyyyyyyyyyyyyyyyyyy"
--data-binary
{
   "card":{
      "security_code":"zzz",
      "wallet_transaction_id":"callid_de_teste",
   },
   "amount":"1000"
}
--verbose

Learn more.

AME

This documentation describes the integration with AME through Carat Portal, using the CardSE via SiTef routing.

Registration information

The Carat must be configured to accept payments for the AME authorizer thru CardSE.

REST Payment

Flow

sequenceDiagram
    participant C as Customer
    participant L as Merchant
    participant E as Online Payment
    participant A as Authorizer
    C->>+L: Checkout
    L->>+E: 1. Creates Transaction
    E-->>-L: nit
    L->>+E: 2. Performs payment(nit)
    E-->>-L: PEN status, QR code
    L-->>-C: 3. Displays QR code
    C->>+A: 4. Scans QR code
    A-->>-C: Payment Confirmation
    E->>+A: 5. Query payment
    A-->>-E: Payment confirmed
    L->>+E: 6. Query transaction
    E-->>-L: CON status

1. The merchant creates the transaction on Carat Portal passing some additional AME information and receives a NIT as a response.
2. The merchant calls the payment effectuation service and receives a QR code and a transaction with PEN (pending) status.
3. The merchant displays the QR code to the customer.
4. The customer scans the QR code with the AME app and goes through the payment confirmation procedures requested by the authorizer.
5. While the customer finishes the payment, Carat Portal will query the sale situation on the authorizer until the transaction ends.
6. The merchant, in turn, must query the transaction status on Carat Portal until it doesn't have the PEN status anymore.

Attention:

If the status remains pending (PEN) after 3 (three) minutes, Carat Portal will undo the transaction alongside AME.

Additional information when creating the transaction

For AME transactions, the authorizer_id = 446 must be used.

Below are the additional parameters that can be sent on AME transactions:

Example:

Starting transaction

--request POST "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/transactions"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-raw '
{
   "merchant_usn":"12042142155",
   "order_id":"1651001767957",
   "installments":"1",
   "installment_type":"4",
   "authorizer_id":"446",
   "amount":"1000",
	"additional_data": {
		"items": [
			{
				"quantity": "1",
				"quantity_type": "u",
				"unit_price": "50000",
                "ean": "9283746529385",
				"description": "bola para jogar 1"
			},
			{
				"quantity": "2",
				"quantity_type": "u",
				"unit_price": "25000",
                "ean": "9283746529384",
				"description": "bola para jogar 2"
			}
		]
	}
}'

Payment effectuation request

When using AME, it won't be necessary to send any card data.

Example:

--request POST "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/payments/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-raw '
{
}

Payment effectuation response with non-standard size

Attention:

In case of a communication failure in this operation, it will be necessary to create another transaction.

Example:

    "code": "0",
    "message": "OK. Transaction successful.",
    "payment": {
        "authorizer_code": "000",
        "status": "PEN",
        "nit": "a479f7d0fc3e3bdfe22f489298b9ca56fa98c4c7c56e2529eb4fddb44c7a392c",
        "order_id": "1651003189064",
        "authorizer_id": "446",
        "acquirer_id": "271",
        "acquirer_name": "CardSE",
        "authorizer_date": "26/04/2022T16:59",
        "authorization_number": "111111111122222222223333333333444444444455555555556666666666                                        ",
        "merchant_usn": "12042142155",
        "esitef_usn": "220426096883310",
        "sitef_usn": "265428",
        "host_usn": "000000000   ",
        "amount": "1000",
        "payment_type": "O",
        "authorizer_merchant_id": "084675745000140",
        "terminal_id": "ES000041",
        "payment_date": "26/04/2022T16:59",
        "qr_code": "The quick brown fox jumps over the lazy dog"
    }
}

HTML Payment

There are no flow differences to the merchant.

As in the REST Payment, additional parameters on the transaction creation can be sent, using the same format.

REST Cancel

Cancel request

When using AME, it won't be necessary to send any card data.

Example:

--request PUT "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/cancellations/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-raw '{
}'

Cancel response parameters

{
    "code": "0",
    "message": "OK. Transaction successful.",
    "cancellation": {
        "authorizer_code": "000",
        "authorizer_message": "Lojista OK",
        "status": "CON",
        "nit": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
        "order_id": "1651003189064",
        "customer_receipt": "=== COMPROVANTE ===",
        "merchant_receipt": "=== COMPROVANTE ===",
        "authorizer_id": "446",
        "acquirer_id": "1271",
        "acquirer_name": "CardSE",
        "authorizer_date": "26/04/2022T17:12",
        "authorization_number": "265429",
        "merchant_usn": "12042142155",
        "esitef_usn": "220426096883331",
        "sitef_usn": "265429",
        "host_usn": "00000000000004265429          ",
        "amount": "1000",
        "payment_type": "O",
        "authorizer_merchant_id": "084675745000140",
        "esitef_date": "26/04/2022T17:12",
        "is_host_cancel": "false"
    }
}

Generate payment link on the Merchant's Portal

It's also possible to make AME payments using the payment link functionality of the Merchant's Portal. However, additional AME information cannot yet be sent.

VEE Via CardSE

This documentation describes the integration with the VEE digital wallet through Carat Portal, using the CardSE via SiTef routing.

Flow

1. The merchant effectuates the payment in Carat Portal, informing the transaction token generated by the customer's VEE app. This token must be sent to Carat Portal's card.wallet_transaction_id field. Learn more about REST Payment request parameters.
2. Carat Portal initiates the payment with the VEE authorizer, informing the transaction token.
3. VEE opens the digital wallet in the customer's app.
4. The customer chooses the payment method and confirms the purchase through the VEE app.
5. The authorizer sends the response to Carat Portal, approving or denying the transaction.
6. Carat Portal forwards the authorizer's response to the merchant.

Flow without customer's delay

Attention:

If the customer takes too long to choose the payment method, the transaction will be set to pending (PEN) and Carat Portal will start a loop with an approximately 30 seconds interval to query the transaction status until it is resolved.

During the loop, the merchant must query the status of the transaction on Carat Portal by doing a transaction status query.

If the transaction status is still pending after approximately 3 (three) minutes, Carat Portal will undo the transaction along with the VEE authorizer.

Flow with customer's delay and status resolved before time limit

Flow with customer's delay and time limit reached

PayPal

This document goal is show the required configurations and guidelines to make possible merchant integration with PayPal by Carat Portal HTML Interface, and Carat Portal Merchant's Portal and Web Services for Refunding.

Carat Portal supported interfaces for integration

The following interfaces are available for Integrations using PayPal:

• HTML Payment Interface 2.0
• Refund Web Service
• Refunding by Carat Portal Merchant's Portal

PayPal authorizer id code in Carat Portal

The authorization code for using PayPal is 400. For more authorizer codes, visit the Authorizers page.

Required Configurations

Before start making transactions using PayPal in Carat Portal, merchants must follow the steps below.

Merchant's account data at PayPal

The store must create a PayPal account if you no longer have it. More information at www.paypal.com.br. Follow the instructions at Create PayPal Account. Within your account, create the required credentials.

PayPal allows from the registered Business account to create virtual accounts for the sandbox - PayPal's testing environment. For the Carat Portal homologation process, it is suggested that an account be created in the sandbox. Look for the option on the website within your PayPal account.

The Table below show then required PayPal credentials:

Note: Sandbox account data can be used in Carat Portal test and Certification environment, but in Carat Portal Production environment, merchant must use real PayPal account data.

Register PayPal account data in Carat Portal

Merchant must contact Carat Portal Support Team to register PayPal account data at Carat Portal, and the additional
steps below is required:

• PayPal authorizer activation in merchant account in Carat Portal;
• Username and password to access Carat Portal Merchant's Portal.

For more information, go to the Authorizer Configuration in the Merchant's Portal page.

Header Image and customized logo in PayPal page

Merchants can choose on using customized logo and/or header image in PayPal payment page. Logo size must be 190 pixels x 60 pixels and header image size must be 915 pixel x 85 pixels.

Merchant logo and header image must be submitted to PayPal support team to validation and combination with Carat Portal logo.

Payment Flow with PayPal

Carat Portal uses PayPal's Express Checkout API to payment integration.

The common payment flow using Carat Portal to integrate with PayPal API is described in steps below:

1. The user starts payment in Carat Portal;
2. Configured authorizers for mechant are presented to the user;
3. The user choose PayPal;
4. At this moment a new window opens, redirecting the user to PayPal page;
5. The user starts payment process in PayPal page, where authentication and authorization occours;
6. The user ends payment in PayPal environment;
7. PayPal redirects user back to Carat Portal;
8. After receiving redirected user, Carat Portal makes a query on PayPal and updates the transaction status on Carat Portal;
9. If the merchant configured automatic redirecting in Carat Portal, the user is automatic redirected to registered Success URL or Failure URL.

The input/output diagram below shows a PayPal payment flow via Carat Portal:

sequenceDiagram

There is only one case where this flow is different, when transaction begin is made with pre-fixed PayPal authorizer. In this case, steps 2 and 3 is not necessary.

Status Notification

For each transaction status change in Carat Portal resulting from communication between Carat Portal and PayPal, a Status Notification is sent to the merchant's server. For more details, see the Status Notification page.

Transaction required parameters for PayPal payments in Carat Portal

The parameters used to create a payment transaction with PayPal are the same as those presented in the HTML Payment Transaction Creation document.

In addition to the common parameters, it is possible to send in the request the specific fields for Paypal described below:

ADDITIONALDATA (additional_data)

ITEMS (items)

PAYER (payer)

SHIPMENT (shipment)

RECEIVERADDRESS (receiver_address)

EXTRAPARAM (extra_param)

ACQUIRERPARAMS (acquirer_params) (**)

(*) This field is not required if the product item is a digital product (see item object, type field), so there is no product delivery. Ex: e-books, digital songs, etc.

NOTE: The field that defines whether the item is digital or not is the type field of the item object.

(**) acquirer_params: This field groups key + value format parameters, to specific acquirer parameters. In PayPal case, the following parameters can be sent here:

Important: Despite of PayPal support for multiple item groups, Carat Portal supports only one item group in a single payment.

JSON request examples to begin PayPal transaction in Carat Portal

Below are shown request examples to begin a PayPal transaction in Carat Portal.

Minimum request example:

Minimum request JSON object:

{
  "merchant_id": "CODIGOLOJA",
  "amount": "1000",
  "authorizer_id": "400",
  "additional_data": {
    "currency": "BRL",
    "payer": {
      "identification_type": "BR_CPF",
      "identification_number": "12345678901"
    }
  }
}

Complete request example:

{
  "merchant_id": "CODIGOLOJA",
  "merchant_usn": "1234567890",
  "order_id": "pedido45687",
  "authorizer_id": "400",
  "amount": "1000",
  "redirect": "M",
  "style": "P",
  "soft_descriptor": "MINHALOJA",
  "additional_data": {
    "item_amount": "1000",
    "tax_amount": "0",
    "insurance_amount": "0",
    "handling_amount": "0",
    "extra_info": "descricao",
    "currency": "BRL",
    "items": [
      {
        "id": "1",
        "title": "bola 1",
        "quantity": "1",
        "unit_price": "500",
        "currency": "BRL",
        "url": "http://sportv.globo.com/platb/files/1103/2011/08/bola_futebol.gif",
        "type": "Physical",
        "description": "bola para jogar 1",
        "weight": "100",
        "length": "20",
        "width": "20",
        "height": "20",
        "tax_amount": "0"
      },
      {
        "id": "2",
        "title": "bola 2",
        "quantity": "2",
        "unit_price": "250",
        "currency": "BRL",
        "url": "http://sportv.globo.com/platb/files/1103/2011/08/bola_futebol.gif",
        "type": "Physical",
        "description": "bola para jogar 2",
        "weight": "200",
        "length": "20",
        "width": "20",
        "height": "20",
        "tax_amount": "0"
      }
    ],
    "payer": {
      "email": "[email protected]",
      "identification_type": "CPF",
      "identification_number": "09719224703"
    },
    "shipment": {
      "cost": "0",
      "discount_amount": "0",
      "receiver_address": {
        "zip_code": "12345678",
        "street_number": "Rua do Exemplo",
        "street_name": "123",
        "name": "Rafael do Mel",
        "phone_area_code": "11",
        "phone_number": "912341234",
        "city": "São Paulo",
        "complement": "Sobreloja 3",
        "country": "BRA",
        "state": "SP"
      }
    },
    "extra_param": {
      "acquirer_params": [
        {
          "key": "reqConfirmShipping",
          "value": "0"
        },
        {
          "key": "noShipping",
          "value": "1"
        },
        {
          "key": "allowNote",
          "value": "1"
        },
        {
          "key": "addrOverride",
          "value": "1"
        },
        {
          "key": "localeCode",
          "value": "pt_BR"
        },
        {
          "key": "pageStyle",
          "value": ""
        },
        {
          "key": "hdrBorderColor",
          "value": ""
        },
        {
          "key": "hdrBackColor",
          "value": ""
        },
        {
          "key": "payFlowColor",
          "value": ""
        },
        {
          "key": "cartBorderColor",
          "value": ""
        },
        {
          "key": "landingPage",
          "value": ""
        },
        {
          "key": "buyerEmailOptinenable",
          "value": "0"
        },
        {
          "key": "paymentRequest_0_paymentReason",
          "value": "none"
        },
        {
          "key": "paymentRequest_0_insuranceOptionOffered",
          "value": "false"
        },
        {
          "key": "paymentRequest_0_custom",
          "value": ""
        },
        {
          "key": "paymentRequest_0_noteText",
          "value": "Obrigado por comprar na Loja Teste!"
        }
      ]
    }
  }
}

PayPal transactions cancelling

The PayPal transaction cancelling or refunding are available in Carat Portal at two interfaces:

• REST Cancel WebService and;
• Merchant's Portal.

Refund using Merchant's Portal

When cancelling a PayPal transaction via Merchant's Portal the following screen will be displayed during the process:

The following table shows the description of the form fields:

Google Pay

Google Pay allows your customers to store payment methods in their own Google account for faster and more secure payments.

How it works

When the customer clicks the Google Pay payment button, the payment methods saved to their Google account are displayed. The customer can quickly select the desired payment method and optionally fill in additional purchase information. After this interaction with Google Pay, these same data will be sent / processed by the Carat Portal for payment flow.

Google Pay is supported by Carat Portal, however it is not supported by all acquirers and is not enabled by default in your account. Contact a member of our support team for more information.

Attention: By using Google Pay through Carat Portal, the merchant must be aware of and adhere to the Acceptable Use Policy and accept the Google Pay API Terms of Service.

REST Payment

Integrate with Google Pay

To start processing payments with Google Pay, you need to integrate with Google via Web or Android. During the integration you will see that some parameters are required to process Google Pay through Carat Portal:

• The gatewayMerchantId parameter must be populated with the merchant's merchant_id in Carat Portal;
• The gateway parameter must be filled with softwareexpress;

Below is an excerpt of integration via web that needs to be configured with Carat Portal data:

const tokenizationSpecification = {
  type: 'PAYMENT_GATEWAY',
  parameters: {
    gateway: 'softwareexpress',
    gatewayMerchantId: '<ESITEF_MERCHANT_ID>',
  },
};

Below is an excerpt of integration via Android that needs to be configured with Carat Portal data:

.setPaymentMethodTokenizationType(WalletConstants.PAYMENT_METHOD_TOKENIZATION_TYPE_PAYMENT_GATEWAY)
.addParameter("gateway", "softwareexpress")
.addParameter("gatewayMerchantId", "<ESITEF_MERCHANT_ID>")

The following card networks available on Google Pay are supported by Carat Portal: VISA, ELECTRON, MASTERCARD, MAESTRO, ELO, ELO_DEBIT, AMEX, DISCOVER and JCB. The following authorization methods available on Google Pay are supported by Carat Portal: PAN_ONLY and 3DS_CRYPTOGRAM. Contact our support team to activate the proper settings for your merchant.

In addition, the store must follow Google Pay layout guidelines. See the Google Pay documentation for brand guidelines.

The screens below shows a Web buy flow recommended by Google Pay.

The screens below shows an Android buy flow recommended by Google Pay.

Send data to Carat Portal

When you complete your integration with Google, you will have all the information you need to make a payment with Carat Portal.

Google will respond with the PaymentData response, which includes the encrypted load (token).
From the Google response containing the customer information, extract the token, following the API reference to properly extract the token from the response. Currently, the token can be extracted from paymentData.paymentMethodData.tokenizationData.token. Use this token on payment effectuation request in the card.wallet_transaction_id field. Additionally this, will be necessary to send the field paymentData.paymentMethodData.info.cardNetwork to the field wallet_returned_card_brand. Below is an example of this request:

The content of paymentData.paymentMethodData.tokenizationData.token is equivalent to a JSON, but there is no need to handle this content. Pass the value obtained without performing any treatment to the card.wallet_transaction_id field.

To use this example, don't forget to define the variable {{url}} with the value

curl  -X POST \
  https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/payments/<NIT> \
  --header "Content-Type: application/json" \
  --header "merchant_id: <MERCHANT_ID>" \
  --header "merchant_key: <MERCHANT_KEY>" \
  --data-binary '{
    "authorizer_id": "405",
    "card": {
        "wallet_transaction_id": "{\"signatures\":\"MEUCIH1PBdMmbWMvaR/ArH08R/OT41Or2yfLqbzj2JG9VGfJAiEA+6NPKT6sAKZeaLacm29wIS8v2tUwPE281JuRBf81imo\\u003d\",\"intermediateSigningKey\":{\"signedKey\":\"{\\\"keyValue\\\":\\\"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEm1j1auejJXFzexs/H3TasImWFERsifrx93W7wxZb0dpLxk/FaK8hQN6Ypwep8DaYrEKSp6zvxeE4ezDrssf/Bg\\\\u003d\\\\u003d\\\",\\\"keyExpiration\\\":\\\"1576347458323\\\"}\",\"signatures\":[\"MEYCIQCbAolg3/K2yD0/p3K7gRFhXva79STrj+rZcYp/3vi6ogIhANGT/9GkO9S1lJtnu3C6QQ/kFSR2wxtPJRGfuqSKs9FE\"]},\"protocolVersion\":\"ECv2\",\"signedMessage\":\"{\\\"encryptedMessage\\\":\\\"Dcm8wxtB6Bp7CyHV1OBqTskStqX3K5x7I0fV/2V0KsMLkZHP5nn+IXC+HBLkZtPF0Ov6uBD1eLbOB2KQd1cVmBPm7f4xSsB4DaYTktfk2AaLpR0BZlb9errv4jl4QAxSLdxw8Hk3EKicSmvsUNE2SzFBOONPrvv1qe03ZnzB3Q0ID1ocsBJ09PQ/2jft0WY/Py6iAA4sccZKmxLdo83NJJc1VrfcGLcqwy5InUV4nSxmXrnr/eNQDIx9p4Yf3RSVlS6/t+bEpUjpUSwSNoHwzhlWOve3/Gm+yt+OKheXOWSsXiHJL1rV1ENgDroR2uMUb85OZCF1ulStb6U8xocRVKSKkhAxFVUehz568huQdlEjns+5MMWdZkNgH3cXMgTQxZ6DiUYxMthUhdT8HINXCUYxaT/od/Njh2JZHJb2R4u4HsfViUoIVRHojSaepXP3KI2z4G9hPwKX/MWeEMyiZRUiCHHe0VJoU/8xxg\\\\u003d\\\\u003d\\\",\\\"ephemeralPublicKey\\\":\\\"BG0eCJ8xbPN55ht7b3oDZgFgwG4rZxkRWrOFnmW9wwxUrZS0A6oeMAySLKThMydaGuoTbbiAwK38zx8pnNKgirA\\\\u003d\\\",\\\"tag\\\":\\\"uPvitOn+aGk48RlrwzYSKgDicO5oYtmMEWXzj5rUewo\\\\u003d\\\"}\"}"
    },
    "wallet_returned_card_brand" : "MASTER"
}'

In the example above, it was set authorizer_id field with the value 405, which corresponds to select Google Pay as payment method; and was set wallet_transaction_id field with the value of the Google Pay token. Successful execution of the above command will return a JSON similar to the one below.

{
  "code": "0",
  "message": "OK. Transaction successful.",
  "payment": {
    "authorizer_code": "000",
    "authorizer_message": "Transacao OK",
    "status": "CON",
    "nit": "<NIT>",
    "order_id": "13034649671",
    "customer_receipt": "====RECEIPT BUYER====",
    "merchant_receipt": "====RECEIPT MERCHANT====",
    "authorizer_id": "405",
    "acquirer_id": "1005",
    "acquirer_name": "Redecard",
    "authorizer_date": "28/02/2020T08:57",
    "authorization_number": "132030",
    "merchant_usn": "13034649671",
    "esitef_usn": "170713097340300",
    "sitef_usn": "132030",
    "host_usn": "999132030",
    "payment_date": "13/07/2017T15:52",
    "amount": "1000",
    "payment_type": "C",
    "issuer": "2",
    "authorizer_merchant_id": "<MERCHANT_ID>"
  }
}

For more details, see Carat Portal REST payment.

REST Card Storage (Vault)

Card storage is possible, with some exceptions depending on how the Google Pay token was generated. Contact our support team to make the necessary configurations to enable this storage.

REST card storage works just like storing any other card, but with the following precautions:

• Instead of sending card numbers, send the wallet_transaction_id field.
• The authorizer_id field must be sent according to the card network. See the table below to submit the correct value:

For more details, see Carat Portal REST store.

HTML Payment

To use Google Pay with HTML payment, please contact a member of our support team to perform the necessary setup. You can determine which card networks will be accepted on Google Pay in HTML integration.

Vouchers

Carat Portal Vouchers List

Emergency Assistance

The Carat Portal allows the use of Emergency Assistance.

For this, the conditions below must be met.

Carat Portal Interfaces Supported for Integration

You can use the following interfaces to use Emergency Assistance:

• Pagamento REST
• Pagamento HTML (including Payment Link)

Allowed Credit Card Companies

The following Credit Card Companies support the use of Emergency Assistance:

• ELO DÉBITO
• VISA ELECTRON

Allowed Routings

The following routing/Credit Card Companies supports the use of Emergency Assistance:

• Cielo e-Commerce
• eRede REST
• SafraPay
• Getnet WS

Anti-Fraud Analysis

The following anti-fraud analysis entities support Emergency Assistance:

• Cybersource

Attention:

It is possible to send an analysis to the anti-fraud analysis entity Konduto, but the debit mode is not supported and
the call is just logged without an analysis being performed.

Details for the Anti-Fraud Analysis

The notes below are valid for the [HTML Payment] interface(pagamento-html-begin.md).

To use anti-fraud with Emergency Assistance, it is mandatory that the following parameter has the value:

The values ​​in the fields below will be ignored:

Authorizers

Carat Portal has the concept of Authorizer, that can represent a card issuer, an online bank payment service or some other Carat Portal method. Examples: Visa, Mastercard, American Express, Itaú Shopline, PayPal, PagSeguro, etc.

Authorizer Exchange

Carat Portal allows the merchant to set up the payment method responsible for authorizing transactions for a particular card brand. For example, a merchant may prefer that Visa card transactions be routed by Cielo while Mastercard cards are routed through Cielo.

This flexibility for routing configuration gives the merchant the ability to handle promotions according to the card brand.

Thinking about how to prevent a customer from selecting the Visa card brand, but end up entering the number of a Mastercard card, Carat Portal provides a verification and exchange mechanism of the Authorizer who will process the authorization of the transaction.

When it is detected that the customer has selected one card brand but has informed one card of another, the merchant may choose three actions to be taken by Carat Portal:

• Do not change the authorizer

Carat Portal takes no action, usually following the payment process. This is the default option adopted by Carat Portal for merchants that do not require anything about changing Authorizers during payment.

• Change the authorizer

Carat Portal goes through the payment process, but exchanges (for information purposes) the Authorizer responsible for the card used.

• Block transactions with authorizer exchange

Carat Portal denies the payment transaction when the card entered by the customer does not match the chosen Authorizer. For example, a Visa card payment is chosen but a Mastercard card is entered.

All of these settings are made in the Carat Portal backoffice administration system.

The merchant can inform upon registration which action option would prefer to be configured, as well as may contact in the future asking to change the setting.

Authorizer codes on Carat Portal

These codes can be altered in the future, and more authorizer codes can be added without previous warning.

IMPORTANT: The authorizers that can be used on Carat Portal depend on the possibilities provided by the acquirer selected by the Merchant.

Example: if the merchant has an agreement with the Cielo acquirer and it assured payments via Visa credit card, the option Visa routed by Cielo will be possible on Carat Portal.

The "Code" column corresponds to the authorizer_id parameter.

Code	Authorizer	HTML	REST
1	VISA
2	MASTERCARD
3	AMERICAN EXPRESS
5	HIPERCARD
12	CABAL
29	SOROCRED
41	ELO

Code	Authorizer	HTML	REST
1	VISA
2	MASTERCARD
3	AMERICAN EXPRESS
4	MULTICHECK
5	HIPER
6	AURA
7	ITAÚ SHOPLINE
8	BRADESCO TRANSFERÊNCIA
9	BANCO IBI
12	CABAL
13	POLICARD
15	BIGCARD
16	SUPERCARD
17	EXCARD
18	EDMCARD
19	COOPER CARD
20	CREDMAIS
21	DACASA
22	CREDISHOP
23	OBOÉ
24	SMARTSHOP
25	ACCREDITO
26	COOPLIFE
27	PAGGO
28	VALECARD
29	SOROCRED
30	MAXICRED
31	CREDSYSTEM
32	TREDENEXX
33	DINERS
34	BANESE
35	SICREDI
36	MULTIALIMENTAÇÃO
37	MULTICASH
40	FORTBRASIL
41	ELO
42	GOODCARD
43	JCB
44	DISCOVER
45	CHINA UNION PAY
46	CREDZ
47	AGIPLAN
48	VEROCHEQUE
49	SAVEGNAGO
50	MASTERCARD ALIMENTAÇÃO
51	MASTERCARD REFEIÇÃO
52	TRICARD
53	ABASTECE AÍ
59	PERSONAL CARD
60	MUFFATO
61	BRASILCARD
70	TICKET REFEIÇÃO
71	TICKET ALIMENTAÇÃO
72	TICKET CAR
73	TICKET CULTURA
74	TICKET FLEX
75	TICKET SUPERFLEX
81	BRADESCO BOLETO
82	BRADESCO CARTÃO
83	BRADESCO FINANCIAMENTO
86	MARISA PRIVATE LABEL
100	WAPPA REFEIÇÃO
101	WAPPA ALIMENTAÇÃO
115	BRADESCARD PRIVATE LABEL
116	COMPCARD
122	PAN
127	CARTÃO PRESENTE MARISA
160	ORBITALL
161	E-COMMERCE PERNAMBUCANAS
162	CLUB+
163	CARTÃO VUON PRIVATE LABEL
192	AVISTA CREDITO
193	CAMPEÃO PRIVATE LABEL
201	VISA PRIVATE LABEL
202	MASTERCARD PRIVATE LABEL
203	PEELA (GIFT)
206	RENNER REALIZE
207	VR ALIMENTAÇÃO
209	VR REFEIÇÃO
210	VR AUTO
211	VR CULTURA
218	HUG (GIFT)
221	VISA ELECTRON (DÉBITO)
222	VISA PRÉ-PAGO
223	ALELO CULTURA
224	ALELO REFEIÇÃO
225	ALELO ALIMENTAÇÃO
245	COOPERCARD CULTURA
246	COOPERCARD ALIMENTAÇÃO
250	COOP FACIL PRIVATE LABEL
266	CASSOL PRIVATE LABEL
267	EXTRABOM
271	VERDECARD PRIVATE LABEL
279	SODEXO VALE CULTURA
280	SODEXO VALE ALIMENTAÇÃO
281	SODEXO VALE REFEIÇÃO
282	SODEXO GIFT
283	SODEXO PREMIUM
284	SODEXO COMBUSTÍVEL
285	BANESCARD
286	MASTERCARD DÉBITO
287	KOERICH
288	ELO DÉBITO
289	VALECARD VOUCHER
300	SAFETYPAY
400	PAYPAL
401	BCASH
402	MERCADO PAGO
403	PAGSEGURO
404	BANCO DO BRASIL BOLETO
405	GOOGLE PAY
406	VISA CHECKOUT
407	MASTER PASS
408	BANCO DO BRASIL TRANSFERÊNCIA
409	ALELO AUTO
411	BANRI COMPRAS À VISTA
412	BANRI COMPRAS PARCELADO
413	BANRI COMPRAS PRÉ-DATADO
414	CASA SHOW
415	BANCO DO BRASIL DÉBITO PF
416	BANCO DO BRASIL DÉBITO PF E PJ
417	BANCO DO BRASIL CREDIÁRIO
430	SENFF
431	VEE
434	BRASIL CONVÊNIOS
440	PIX
441	VEGAS CARD CRÉDITO
442	VEGAS CARD DÉBITO
443	VEGAS CARD ALIMENTAÇÃO
444	VEGAS CARD REFEIÇÃO
445	BRADESCARD VOUCHER

It is also possible to identify the authorizer_id of the Authorizer registered for the merchant, by accessing the Carat Portal-Portal through the site http:///e-sitef-loja (for homologation environment).

In the ID column as shown in the figure below, we have the value of authorizer_id.

Remembering that authorizers are always associated with a Routing in Carat Portal BackOffice.

This Routing defines, for example, the acquirer responsible for routing credit transactions.

PIX

Payment

This documentation describes the integration with Pix through Carat Portal, using the CardSE via SiTef routing.

Registration information

Besides the usual information for registration on Carat Portal, for integrating with Pix, more data is necessary:

REST Payment

Flow

1. The merchant creates the transaction on Carat Portal passing some additional Pix information and receives a NIT as a response.
2. The merchant calls the payment effectuation service and receives a QR code and a transaction with PEN (pending) status.
3. The merchant displays the QR code to the customer.
4. The customer scans the QR code with the Pix app and goes through the payment confirmation procedures requested by the authorizer.
5. While the customer finishes the payment, Carat Portal will query the sale situation on the authorizer until the transaction ends.
6. The merchant, in turn, must query the transaction status on Carat Portal until it doesn't have the PEN status anymore.

Attention:

If the status remains pending (PEN) after 3 (three) minutes, Carat Portal will undo the transaction alongside Pix.

Additional information when creating the transaction

For Pix transactions, the authorizer_id = 440 must be used.

Below are the additional parameters that can be sent on Pix transactions:

Example:

To use this example, don't forget to define the variable {{url}} with the value

curl 
--request POST "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/transactions"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
   "merchant_usn":"12042142155",
   "order_id":"12042142155",
   "installments":"1",
   "installment_type":"4",
   "authorizer_id":"440",
   "amount":"1000",
   "additional_data":{
      "pix_psp":"12345678",
      "pix_question":"Deseja receber 10% de desconto para sua proxima compra?",
      "pix_data":[
         {
            "key":"Pontos Ganhos",
            "value":"23"
         },
         {
            "key":"NumPromo",
            "value":"234523452345"
         }
      ],
      "items":[
         {
            "description":"ItemTeste",
            "quantity":"1",
            "sku":"1487337308522",
            "unit_price":"1000",
            "quantity_type":"u"
         },
         {
            "description":"ItemTeste2",
            "quantity":"3",
            "ean":"9283746529384675",
            "unit_price":"2500",
            "quantity_type":"g"
         }
      ],
      "ecomm_pos_ref":"12345678"
   }
}
--verbose

Payment effectuation request

When using Pix, it won't be necessary to send any card data.

Example:

To use this example, don't forget to define the variable {{url}} with the value

curl 
--request POST "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/payments/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{}
--verbose

Payment effectuation response with non-standard size

Additional response data on the payment effectuation

Observation:

Theses additional fields will also be shown when making subsequent queries.

Attention:

In case of a communication failure in this operation, it will be necessary to create another transaction.

Example:

{
  "code": "0",
  "message": "OK. Transaction successful.",
  "payment": {
    "authorizer_code": "000",
    "authorizer_message": "Transacao OK",
    "status": "PEN",
    "nit": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
    "order_id": "13034649671",
    "authorizer_id": "2",
    "acquirer_id": "1271",
    "acquirer_name": "CardSE",
    "authorizer_date": "13/07/2017T15:52",
    "authorization_number": "132030",
    "merchant_usn": "13034649671",
    "esitef_usn": "170713097340300",
    "sitef_usn": "132030",
    "host_usn": "000000000",
    "payment_date": "13/07/2017T15:52",
    "amount": "1000",
    "authorizer_merchant_id": "000000000000005",
    "pix_psp": "12345678",
    "pix_answer": "No",
    "qr_code": "The quick brown fox jumps over the lazy dog",
    "e2eid": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
  }
}

HTML Payment

There are no flow differences to the merchant.

As in the REST Payment, additional parameters on the transaction creation can be sent, using the same format.

REST Cancel

Cancel request

When using Pix, it won't be necessary to send any card data.

Example:

To use this example, don't forget to define the variable {{url}} with the value

curl 
--request PUT "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/cancellations/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
   "amount":"1000"
}
--verbose

Cancel additional response parameters

Example:

{
  "code": "0",
  "message": "OK. Transaction successful.",
  "cancellation": {
    "authorizer_code": "000",
    "authorizer_message": "Transacao OK",
    "status": "CON",
    "nit": " 1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
    "order_id": "09062259711",
    "customer_receipt": "=== COMPROVANTE ===",
    "merchant_receipt": "=== COMPROVANTE ===",
    "authorizer_id": "2",
    "acquirer_id": "1271",
    "acquirer_name": "CardSE",
    "authorizer_date": "09/11/2017T18:23",
    "authorization_number": "092423",
    "merchant_usn": "9062259711",
    "esitef_usn": "171109108051261",
    "sitef_usn": "092424",
    "host_usn": "999092424   ",
    "amount": "1000",
    "payment_type": "O",
    "authorizer_merchant_id": "000000000000000",
    "esitef_date": "09/11/2017T18:23",
    "pix_psp": "12345678"
  }
}

Generate payment link on the Merchant's Portal

It's also possible to make Pix payments using the payment link functionality of the Merchant's Portal. However, additional Pix information cannot yet be sent.

Registering Pix keys on the Merchant's Portal

When acessing the configuration for a Pix authorizer, a button to register your Pix keys will be displayed:

By clicking the "Cadastrar Chaves" button, the user will be redirected to a page containing information about the merchant and a PSP list:

Select the PSP you wish to use and click "Adicionar", Type your Pix key and your credential information and click "Salvar".

Some PSPs request the CNPJ with the credential that enables the transaction, include the CNPJ and click "Confirmar".

If you wish to alter credential information, click "Editar credencial".

After clicking on "Editar credencial", the fields referring to the credential will be displayed, as shown below.

If you do not want to change the credential, click "Cancelar", so the credential will not be changed.

If you want to delete them, click "Remover".

After making your desired changes, click "Salvar".