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:

Field	Description	Format	Mandatory
`psp`	Payment service provider. If it isn't sent, the value registered on SiTef will be used.	< 8 N	NO

REST Payment

Flow

The merchant creates the transaction on Carat Portal passing some additional Pix information and receives a NIT as a response.
The merchant calls the payment effectuation service and receives a QR code and a transaction with PEN (pending) status.
The merchant displays the QR code to the customer.
The customer scans the QR code with the Pix app and goes through the payment confirmation procedures requested by the authorizer.
While the customer finishes the payment, Carat Portal will query the sale situation on the authorizer until the transaction ends.
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:

Parameter	Description	Format	Mandatory
additional_data
`pix_psp`	Payment service provider. If it isn't sent, the value registered on Carat Portal will be used.	< 8 AN	NO
`pix_question`	Question from the merchant to the customer (will be displayed on the app).	< 140 AN	NO
`ecomm_pos_ref`	This field will send an identification that will appear on the SiTef Web report for e-commerce transactions.	< 8 AN	NO
additional_data.pix_data[]		Free content list. Allows sending data to the customer's app like acquired services list, promotional information or other desired data.
`key`	Field identification.	< 50 AN	NO
`value`	Field value.	< 200 AN	NO
additional_data.items[]
`ean`	EAN product code. Attention: if EAN and SKU are sent simultaneously, only EAN will be considered.	< 17 AN	NO
`sku`	SKU product code. Attention: if EAN and SKU are sent simultaneously, only EAN will be considered.	< 17 AN	NO
`description`	Product description.	< 30 AN	NO
`quantity`	Product quantity.	< 15 N	NO
`quantity_type`	Quantity type: `u` - Units `g` - Grams `ml` - Mililiters	< 2 AN	NO
`unit_price`	Unit price of the product in cents.	< 12 N	NO

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

Parameter	Description	Format
`authorization_number`	Authorization number.	< 100 AN
`host_usn`	Host USN.	< 30 AN

Additional response data on the payment effectuation

Observation:

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

Parameter	Description	Format
payment
`pix_psp`	Payment service provider. It is only returned for `Pix with Long Expiration`	< 8 AN
`pix_answer`	Response to the `pix_question`.	< 140 AN
`qr_code`	QR code to be displayed to the customer.	< 9999 AN
`e2eid`	Id sent by PSP upon payment confirmation.	< 130 AN

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

Parameter	Description	Format
cancellation
`pix_psp`	Payment service provider. It is only returned for `Pix with Long Expiration`	< 8 AN

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".

-no-filter

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

-no-filter

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

-no-filter

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

-no-filter

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

-no-filter

After making your desired changes, click "Salvar".

-no-filter

Updated 15 days ago