PagSeguro · e-SiTef

This document describes the integration with PagSeguro payment platform, as well as explaining about the configurations that must be made at e-SiTef environment.

ATTENTION: in UAT environment, the behavior of PagSeguro will be simulated by e-SiTef in order to make the UAT process more reliable and adequate, as PagSeguro's sandbox environment does not provide yet all the functionalities available in Production.

Therefore, the behavior of transactions made with PagSeguro authorizer in e-SiTef's UAT environment may not reflect the behavior of PagSeguro's production environment.

Despite the efforts to keep the simulator always updated, changes made by PagSeguro can occur without prior notice to the e-SiTef team.

Supported Interfaces

HTML Payment
REST Cancel
Merchant's Portal Cancel

e-SiTef required configurations

Before performing PagSeguro transactions with e-SiTef, the configuration steps below must be followed:

PagSeguro's account data

The Merchant must have an active account in PagSeguro. More information at PagSeguro website (in portuguese)
Following table shows PagSeguro credentials that must be retrieved by the merchant, which will be registered in e-SiTef later:

Parameter	Description	Mandatory
`email`	Client identification	YES
`token`	Access token	YES

Insert account data in e-SiTef

Having the PagSeguro account data above, the merchant must request to the e-SiTef support team:
- activation of PagSeguro as an active authorizer on e-SiTef.
- a username and password for accessing e-SiTef's Merchant's Portal, if not taken already.
As soon as the PagSeguro authorizer is associated with the store, the merchant must access the Merchant's Portal and inform PagSeguro's account data in the "Configuração de Autorizadoras" (Authorizers Configuration) menu.

Authorizer Code for PagSeguro in e-SiTef

To make payments with the pre-defined authorizer, send code 403, which refers to PagSeguro authorizer.

Parameters for transaction via PagSeguro

The parameters used to make a payment transaction with PagSeguro must be sent to e-SiTef in JSON format, using the following URL:

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

For further details concerning HTML Payment Interface, refer to the specific section in this document.

ATTENTION: Transactions that start a dispute on PagSeguro will remain with status confirmed (CON) on e-SiTef as well as their possible results (refund or confirmed payment). It is up to the client to verify the transaction status with PagSeguro.

Below are listed the parameters that the merchant is able to send to e-SiTef to allow the client to make a payment on PagSeguro.

Parameter	Description	Format	Mandatory
	`additional_data`
`extra_info`	Additional information.	< 1024	NO
`currency`	Currency in which the payment will be made, using ISO 4217 format. Currently, the only available option is `BRL` (Real).	< 1024	NO
`extra_amount`	Specify an extra amount that must be added to or subtracted from the payment total value. This amount may represent an extra tax to be charged in the payment or a discount to be granted, if the amount is negative. Format: cents. Example: `123456` (R$1234, 56) or `-123456` (R$-1234,56)	< 1024	NO
	`additional_data` `.items[]`
`id`	Item identification.	< 1024	NO
`title`	Item title.	< 1024	YES
`quantity`	Item quantity.	< 1024	YES
`unit_price`	Unit price of the item in cents.	< 1024	YES
`description`	Item description.	< 1024	NO
`shipping_cost`	The shipping cost of every item being paid.	< 1024	NO
`weight`	The weight (in grams) of every item being paid. Used to calculate the shipping cost, if it is not informed. Example: `3000` (3kg)	< 1024	NO
	`additional_data` `.payer`
`name`	Payer name.	< 1024	NO
`surname`	Payer surname.	< 1024	NO
`email`	Payer e-mail.	< 1024	NO
`phone_area_code`	Payer area code.	< 1024	NO
`phone_number`	Payer phone number.	< 1024	NO
`identification_type`	Payer identification type. Only the value `CPF` is accepted.	< 1024	NO
`identification_number`	Payer identification number.	< 1024	NO
`address_street_name`	Payer address.	< 1024	NO
`address_street_number`	Payer address number.	< 1024	NO
`born_date`	Date of birth of the payer. ISO 8601 format.	< 1024	NO
	`additional_data` `.shipment`
`cost`	Total shipment amount of the order. Format: cents. Example: `123456` (R$1234, 56)	< 1024	NO
`type`	Shipment type to be used to deliver the product. Accepted values: `1` – Regular order (PAC) `2` – SEDEX `3` – Shipment type not specified.	< 1024	NO
	`additional_data` `.shipment` `.receiver_address`
`zip_code`	Receiver address ZIP. Format: 8-digit number. Example: `12345678`	< 1024	NO
`street_number`	Receiver address number.	< 1024	NO
`street_name`	Receiver address.	< 1024	NO
`floor`	Receiver address floor number.	< 1024	NO
`apartment`	Receiver address apartment number.	< 1024	NO
`district`	Receiver address district.	< 1024	NO
`complement`	Receiver address complement (block, apartment, etc.).	< 1024	NO
`city`	Receiver address city.	< 1024	NO
`state`	Receiver address state. Example: `SC` (Santa Catarina), `SP` (São Paulo), etc.	< 1024	NO
`country`	Receiver address country. Currently only `BRA` value is allowed.	< 1024	NO
	`additional_data` `.extra_param` `.metadata[]`
`key`	Allows adding extra information, grouped or not, in your payment request. Only the values described in here are accepted.	< 1024	NO
`value`	Allows specifying values for the metadata defined in your payment request.	< 1024	NO
`group`	Allows grouping two or more metadata, e.g. CPF and name for the same passenger.	< 1024	NO

PagSeguro payment flow

After submitting the transaction creation data and selecting the PagSeguro payment method, the following UI flow will be initiated:

A PagSeguro LightBox window will be opened in the browser to make the payment:

"Lightbox PagSeguro"

If the transaction is aborted, the following screen will be shown:

"Aborted transaction"

If the transaction is confirmed, the following screen will be shown:

"Confirmed payment case"

If the transaction is not confirmed, the following screen will be shown:

"Loading screen"

Status Notification – specific data

In Status Notification for payments made with PagSeguro, the following fields are additionally returned:

Parameter	Description	Format
`pagseguro_status_payment`	Transaction status in PagSeguro. `1` = Awaiting payment `2` = Under analysis `3` = Paid `4` = Available `5` = In dispute `6` = Returned `7` = Cancelled	< 15 AN
`pagseguro_type`	Transaction type in PagSeguro. Typically, type `1` = Payment	< 5 AN
`pagseguro_cancellation_source`	Cancellation source in PagSeguro, only when the `pagseguro_status_payment` parameter is equal to `7`. `INTERNAL` = PagSeguro `EXTERNAL` = Financial Institutions	< 10 AN
`pagseguro_discount_amount`	Discount amount granted.	< 10 AN
`pagseguro_fee_amount`	Total amount of fees charged.	< 10 AN

Attention: the data presented is returned by PagSeguro, so e-SiTef does not have control over them. Besides that, they may not always be returned.

Refund Transaction - REST Cancel

In order to refund a PagSeguro transaction, use the Cancel REST interface. For further details, refer to the specific section on this document.

Merchant's Portal

For general guidelines about the Merchant's Portal, please refer to the specific section on this document.

Merchant's Portal access URL – Production:

https://esitef-ec.softwareexpress.com.br/e-sitef-loja

Merchant's Portal access URL – UAT:

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

To refund a PagSeguro transaction, go to the Merchant's Portal and access the "Cancelamento" (Cancel) menu, as exemplified below:

"Cancel Menu"

Look for the transaction you wish to refund using the filters:

"Transactions List"

Click the transaction you wish to refund; the following screen will open:

"Transaction Details"

Verify if the data are correct and click on "Cancelar Pagamento" (Cancel payment) and then confirm it. If the transaction is successfully refunded, a refund receipt similar to the one below will be presented:

"Successful Cancel"

Appendices

Key values for Metadata

Value	Description	Format
`PASSENGER_CPF`	Passenger CPF	[0-9]{11}
`PASSENGER_PASSPORT`	Passenger passport	.+
`PASSENGER_NAME`	Passenger name	.+
`ORIGIN_CITY`	Origin city	.+
`DESTINATION_CITY`	Destination city	.+
`ORIGIN_AIRPORT_CODE`	Origin airport code	.+
`DESTINATION_AIRPORT_CODE`	Destination airport code	.+
`GAME_NAME`	Game name	.+
`PLAYER_ID`	Player ID	.+
`TIME_IN_GAME_DAYS`	Time in game	[0-9]+
`MOBILE_NUMBER`	Mobile number	([0-9]{2})?([0-9]{2})([0-9]{4,5}[0-9]{4})

JSON Sample

{
    "merchant_id": "CODIGO_LOJA",
    "order_id": "1123456",
    "redirect": "M",
    "authorizer_id": "600",
    "amount": "2000",
    "installments": "1",
    "back_url": {
        "url_success": "relative success url registered on e-SiTef",
        "url_failure": "relative failure url registered on e-SiTef",
        "url_cancel": "relative cancel url registered on e-SiTef"
    },
    "additional_data": {
        "extra_info": "dados extras",
        "currency":"BRL",
        "items": [
            {
                "description": "descricao",
                "id": "123",
                "quantity": "2",
                "title": "Produto 1",
                "unit_price": "1000",
                "weight": "4000",
                "shipping_cost": "1000"
            },
            {
                "description": "descricao",
                "id": "1234",
                "quantity": "3",
                "title": "Produto 2",
                "unit_price": "2000",
                "weight": "3000",
                "shipping_cost": "1000"
            }
        ],
        "payer": {
            "name": "João",
            "surname": "Silva",
            "email": "joao.silva@exemplo.com",
            "phone_area_code": "11",
            "phone_number": "78945123",
            "identification_type": "CPF",
            "identification_number": "12345678906",
            "address_street_name": "Rua do Exemplo",
            "address_street_number": "123",
            "born_date": "12/12/1900"
        },
        "shipment": {
            "cost": "2000",
            "type": "1",
            "receiver_address": {
                "zip_code": "12345678",
                "street_number": "Rua do Exemplo",
                "street_name": "123",
                "floor": "3",
                "apartment": "901",
                "city": "São Paulo",
                "complement": "Sobreloja 3",
                "country": "BRA",
                "district": "Jardim do Exemplo",
                "state": "SP"
            }
        },
        "extra_param": {
            "metadata": [
                {
                    "key": "PASSENGER_CPF",
                    "value": "12345678901",
                    "group": "1"
                },
                {
                    "key": "PASSENGER_PASSPORT",
                    "value": "1594825512",
                    "group": "1"
                }
            ]
        }
    }
}