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:

Free content list. Allows sending data to the customer's app like acquired services list, promotional information or other desired data.

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[]
`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
esitef-homologacao.softwareexpress.com.br

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
esitef-homologacao.softwareexpress.com.br

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#

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

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

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
esitef-homologacao.softwareexpress.com.br

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.