REST Payment

Overview#

Carat Portal has two interfaces for integration with the virtual store, HTTPS POST and HTTPS Web Services, enabling the proper way of interaction between the merchant and Carat Portal, according to the programming language and the platform of the virtual store.

On the REST Web Service interface, the payment and card data will be collected by the merchant and Carat Portal will only make the payment with the financial institution.

This interface provides payments with credit, debit or voucher cards. For payments such as electronic transfer or boleto, the POST/HTML interface must be used instead.

And to learn more about these nomenclatures (Bin, Software Express, Carat, e-Sitef) Learn more

Communication#

To make a Web Service transaction, the whole communication must be done via HTTPS/TLS. It's important that the merchant's server supports encryption of a minimum of 128 bits. The merchant's server must make calls on specific addresses to do REST transactions.

Each service must be called using the base URL concatenated with the desired resource (see the chapter related to the service to be consumed). The HTTP method (GET, POST or PUT) indicates the expected action on the selected resource. Listed below are the base URLs of Carat Portal:

Production base URL:

https://esitef.softwareexpress.com.br/e-sitef/api

Homologation base URL:

https://esitef-homologacao.softwareexpress.com.br/e-sitef/api

Every call received by the services will be responded synchronously.

Attention:
Never use the IP instead of the esitef.softwareexpress.com.br domain. The IP can change at any time without previous warning, so it's important to use the domain when accessing Carat Portal.

Important:
Besides the response parameters of the services described in this specification, Carat Portal can return other parameters without previous warning.
It's important that the application is prepared to receive the unknown parameters besides the fields already specified and simply ignore them.

Flow#

The payment flow will be initiated by the merchant's application after the customer completes the purchase and sends the payment data.

There are two types of payment flow: with automatic confirmation, where Carat Portal is responsible for confirming the payment with the acquirer; and with late confirmation, where the merchant's application is responsible for confirming the payment by consuming the confirmation service.

The late confirmation is usually used when the merchant's application allows paying with more than one card or when some validation is done before confirming the payment.

Payment with automatic confirmation#

Flow description:

The merchant creates a transaction via API passing information such as the merchant ID, number of installments and the order ID and obtains as response a NIT (Transaction Identifier Number).
The merchants then proceeds consuming the payment effectuation service, passing the NIT and the customer's card data. In case of success, the payment transaction will change its status to CON (confirmed).

Example

To use this example, don't forget to define the variable {{url}} with the value
esitef-homologacao.softwareexpress.com.br

Request:

curl --location 'https://{{url}}/e-sitef/api/v2/payments/' --header 'Content-Type: application/json' --header 'merchant_id: xxxxxxxxx' --header 'merchant_key: xxxxxxxxxxxxxx' --data '{
    "merchant_usn": "12050620649",
   "order_id":"1686591679260",
    "installments": "1",
    "installment_type": "4",
    "authorizer_id": "2",
    "amount": "1100",
    "card": {
        "expiry_date": "1222",
        "security_code": "123",
        "number": "5555555555555555",
        "cryptogram": "ALRzlt6NKQtPAAZAkOuIAAADFA==",
        "wallet_type": "network_token"
    }
}'

Response: (note the transaction status, that is CON of Confirmed)

{
    "code": "0",
    "message": "OK. Transaction successful.",
    "payment": {
        "authorizer_code": "000",
        "authorizer_message": "APROVADA",
        "status": "CON",
        "nit": "dc8a370d394e3868de756b53b912a3b41cffdf28e26bff405ddb20737bce5e06",
        "order_id": "1686591679260",
        "customer_receipt": "==== customer receipt ====",
        "merchant_receipt": "==== merchant receipt ====",
        "authorizer_id": "2",
        "acquirer_id": "229",
        "acquirer_name": "Bin",
        "authorizer_date": "12/06/2023T14:41",
        "authorization_number": "000026",
        "merchant_usn": "12050620649",
        "esitef_usn": "230612015722270",
        "sitef_usn": "000026",
        "host_usn": "006000026   ",
        "amount": "1100",
        "payment_type": "C",
        "issuer": "2",
        "authorizer_merchant_id": "000000000000000",
        "terminal_id": "ES000001",
        "payment_date": "12/06/2023T14:41",
        "recurrency_tid": "999988887777666"
    }
}

Payment with late confirmation#

Flow description:

As in the payment flow with automatic confirmation, the merchant creates a transaction via API passing the payment data. In addition, they must send the postpone_confirmation parameter with the value true.
The merchant then proceeds consuming the payment effectuation service, passing the NIT and the customer's card data. In case of success, the payment transaction will change its status to PPC (pending payment confirmation).
Concluding, the merchant calls the payment confirmation service, passing the NIT again and the parameter confirm with value true, resulting in a transaction with status CON (confirmed). There is also the possibility for the merchant to undo de transaction instead of confirming. For this, the confirm parameter must be sent with the value false, which will result in a transaction with status PPN (undone).

Exemplo

To use this example, don't forget to define the variable {{url}} with the value
esitef-homologacao.softwareexpress.com.br

Note the parameter postpone_confirmation included with true value, and the transaction status that now is PPC.

curl --location 'https://{{url}}/e-sitef/api/v2/payments/' --header 'Content-Type: application/json' --header 'merchant_id: xxxxxxxxx' --header 'merchant_key: xxxxxxxxxxxxxx' --data '{
    "merchant_usn": "12050620649",
   "order_id":"1686592079260",
    "installments": "1",
    "installment_type": "4",
    "authorizer_id": "2",
    "amount": "1100",
    "card": {
        "expiry_date": "1222",
        "security_code": "123",
        "number": "5555555555555555",
        "cryptogram": "ALRzlt6NKQtPAAZAkOuIAAADFA==",
        "wallet_type": "network_token"
    },
    "additional_data": {
        "postpone_confirmation": "true"
    }
}'

Response:

{
    "code": "0",
    "message": "OK. Transaction successful.",
    "payment": {
        "authorizer_code": "000",
        "authorizer_message": "APROVADA",
        "status": "PPC",
        "nit": "7321992585edcd4683b3a242426cb30f9a1643dbcea634a55ae81599d8ea5081",
        "order_id": "1686592079260",
        "customer_receipt": " ==== customer receipt ====",
        "merchant_receipt": " ==== merchant receipt ====",
        "authorizer_id": "2",
        "acquirer_id": "229",
        "acquirer_name": "Bin",
        "authorizer_date": "12/06/2023T14:48",
        "authorization_number": "000027",
        "merchant_usn": "12050620649",
        "esitef_usn": "230612015722290",
        "sitef_usn": "000027",
        "host_usn": "006000027   ",
        "amount": "1100",
        "payment_type": "C",
        "issuer": "2",
        "authorizer_merchant_id": "000000000000000",
        "terminal_id": "ES000001",
        "payment_date": "12/06/2023T14:48",
        "recurrency_tid": "999988887777666"
    }
}

Home

Overview#

Communication#

Flow#

Payment with automatic confirmation#

Payment with late confirmation#