Pix via CardSE · e-SiTef

This documentation describes the integration with Pix through e-SiTef, using the CardSE via SiTef routing.

Registration information

Besides the usual information for registration on e-SiTef, 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 e-SiTef 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, e-SiTef will query the sale situation on the authorizer until the transaction ends.
The merchant, in turn, must query the transaction status on e-SiTef until it doesn't have the PEN status anymore.

Attention:

If the status remains pending (PEN) after 3 (three) minutes, e-SiTef 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 e-SiTef will be used.	< 8 AN	NO
`pix_question`	Question from the merchant to the customer (will be displayed on the app).	< 140 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.	< 255 AN	NO
`sku`	SKU product code. Attention: if EAN and SKU are sent simultaneously, only EAN will be considered.	< 255 AN	NO
`description`	Product description.	< 255 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:

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

Payment effectuation request

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

Example:

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

Additional response data on the payment effectuation

Parameter	Description	Format
payment
`pix_psp`	Payment service provider.	< 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:

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.	< 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". After submitting your data, if you wish to alter your information, click "Editar". If you want to delete them, click "Remover":

After making your desired changes, click "Salvar".