PayPal · e-SiTef

This document goal is show the required configurations and guidelines to make possible merchant integration with PayPal by e-SiTef HTML Interface, and e-SiTef Merchant's Portal and Web Services for Refunding.

e-SiTef supported interfaces for integration

The following interfaces are available for Integrations using PayPal:

HTML Payment Interface 2.0
Refund Web Service
Refunding by e-SiTef Merchant's Portal

PayPal authorizer id code in e-SiTef

The authorization code for using PayPal is 400. For more authorizer codes, visit the Authorizers page.

Required Configurations

Before start making transactions using PayPal in e-SiTef, merchants must follow the steps below.

Merchant's account data at PayPal

The store must create a PayPal account if you no longer have it. More information at www.paypal.com.br. Follow the instructions at Create PayPal Account. Within your account, create the required credentials.

PayPal allows from the registered Business account to create virtual accounts for the sandbox - PayPal's testing environment. For the e-SiTef homologation process, it is suggested that an account be created in the sandbox. Look for the option on the website within your PayPal account.

The Table below show then required PayPal credentials:

Field name in e-SiTef	Field description	Mandatory
USER	User name on PayPal account.	YES
PWD	USER's password.	YES
SIGNATURE	USER's signature.	YES

Note: Sandbox account data can be used in e-SiTef test and Certification environment, but in e-SiTef Production environment, merchant must use real PayPal account data.

Register PayPal account data in e-SiTef

Merchant must contact e-SiTef Support Team to register PayPal account data at e-SiTef, and the additional steps below is required:

PayPal authorizer activation in merchant account in e-SiTef;
Username and password to access e-SiTef Merchant's Portal.

For more information, go to the Authorizer Configuration in the Merchant's Portal page.

Header Image and customized logo in PayPal page

Merchants can choose on using customized logo and/or header image in PayPal payment page. Logo size must be 190 pixels x 60 pixels and header image size must be 915 pixel x 85 pixels.

Merchant logo and header image must be submitted to PayPal support team to validation and combination with e-SiTef logo.

Payment Flow with PayPal

e-SiTef uses PayPal's Express Checkout API to payment integration.

The common payment flow using e-SiTef to integrate with PayPal API is described in steps below:

The user starts payment in e-SiTef;
Configured authorizers for mechant are presented to the user;
The user choose PayPal;
At this moment a new window opens, redirecting the user to PayPal page;
The user starts payment process in PayPal page, where authentication and authorization occours;
The user ends payment in PayPal environment;
PayPal redirects user back to e-SiTef;
After receiving redirected user, e-SiTef makes a query on PayPal and updates the transaction status on e-SiTef;
If the merchant configured automatic redirecting in e-SiTef, the user is automatic redirected to registered Success URL or Failure URL.

The input/output diagram below shows a PayPal payment flow via e-SiTef:

Fluxo PayPal

There is only one case where this flow is different, when transaction begin is made with pre-fixed PayPal authorizer. In this case, steps 2 and 3 is not necessary.

Status Notification

For each transaction status change in e-SiTef resulting from communication between e-SiTef and PayPal, a Status Notification is sent to the merchant's server. For more details, see the Status Notification page.

Transaction required parameters for PayPal payments in e-SiTef

The parameters used to create a payment transaction with PayPal are the same as those presented in the HTML Payment Transaction Creation document.

In addition to the common parameters, it is possible to send in the request the specific fields for Paypal described below:

Parameter	Description	Size	Mandatory
`additional_data`	ADDITIONALDATA object.		NO

ADDITIONALDATA (`additional_data`)

Parameter	Description	Size	Mandatory
`extra_info`	Additional info about payment.	< 127 AN	NO
`item_amount`	Order items amount summary, in cents. This summary must match unit_price field value multiplied by quantity field value, for all items. Maximum value allowed is US$10000, in any currency.	< 1024 N	NO
`purchase_summary`	Customizeable text to "Purchase Summary" field in e-SiTef payment screen.	< 1024 AN	NO
`insurance_amount`	Order items insurance amount, in cents. Maximum value allowed is US$10000, in any currency.	< 1024 N	NO
`handling_amount`	Sale handling amount, in cents. Maximum value allowed is US$10000, in any currency.	< 1024 N	NO
`tax_amount`	Order total tax amoutn summary, in cents. Maximum value allowed is US$10000, in any currency.	< 1024 N	NO
`items`	ITEMS object array.		NO
`payer`	PAYER object.		NO
`shipment`	SHIPMENT object.		NO
`extra_param`	EXTRAPARAM object.		NO

ITEMS (`items`)

Parameter	Description	Size	Mandatory
`id`	Item identification code.	< 127 AN	NO
`title`	Item title.	< 127 AN	NO
`url`	Item URL.	< 1024 AN	NO
`quantity`	Item quantity.	< 10 N	NO
`unit_price`	Item unit price, in cents. Maximum value allowed is US$10000, in any currency.	< 1024 N	NO
`weight`	Item unit weight, in grams (g). Ex: 2,3 kg -> 2300.	< 10 N	NO
`description`	Item description.	< 127 AN	NO
`tax_amount`	Item unit tax amount, in cents. Maximum value allowed is US$10000, in any currency.	< 1024 N	NO
`length`	Item length, in centimeters (cm).	< 10 N	NO
`width`	Item width, in centimeters (cm).	< 10 N	NO
`height`	Item height, in centimeters (cm).	< 10 N	NO
`type`	Item type: `Digital` – The item is a digital product. Ex: e-books, songs, etc. `Physical` – The item is a physical product.	< 10 N	NO

PAYER (`payer`)

Parameter	Description	Size	Required
`email`	Customer / Payer e-mail address.	< 127 AN	NO
`identification_type`	Customer / Payer identification type. For Brazil: `BR_CPF` - Buyer's CPF `BR_CNPJ` - Buyer's CNPJ.	< 10 A	YES (FOR BRAZIL)
`identification_number`	Customer / payer identification number.	< 14 AN	YES (FOR BRAZIL)

SHIPMENT (`shipment`)

Parameter	Description	Size	Mandatory
`cost`	Order total shipment cost. Format: cents. Maximum value allowed is US$10000, in any currency. Ex: 123456 (R$ 1234,56)	< 1024 N	NO
`discount_amount`	Shipment cost discount amount, in cents. Maximum value allowed is US$10000, in any currency.	< 1024 N	NO
`receiver_address`	RECEIVERADDRESS object.		NO

RECEIVERADDRESS (`receiver_address`)

Parameter	Description	Size	Required
`zip_code`	Receiver address zip code (or CEP for Brazil).	< 20 AN	SIM (*)
`street_name`	Receiver address street name. Maximum size allowed, combined with `street_number` field, is 100 characters.	< 100 AN	SIM (*)
`street_number`	Receiver address number. Maximum size allowed, combined with `street_address` field, is 100 characters.	< 100 AN	SIM (*)
`complement`	Receiver address complement (block, apartment, etc.).	< 100 AN	SIM (*)
`city`	Receiver address city.	< 40 AN	SIM (*)
`state`	Receiver address state. Example in Brazil: SC (Santa Catarina), SP (São Paulo), etc.	< 2 AN	SIM (*)
`country`	Receiver address country code, using ISO 3166-1 alpha-3 (3 letters). Ex: Brazil: `BRA`	< 2 A	SIM (*)
`name`	Receiver reference name.	< 32 AN	SIM (*)
`phone_area_code`	Receiver address phone area code. Maximum size allowed, combined with `phone_number` field, is 20 characters.	< 20 AN	SIM (*)
`phone_number`	Receiver address phone number. Maximum size allowed, combined with `phone_area_code` field, is 20 characters.	< 20 AN	SIM (*)

EXTRAPARAM (`extra_param`)

Parameter	Description	Size	Mandatory
`acquirer_params`	ACQUIRERPARAMS object.		NO

ACQUIRERPARAMS (`acquirer_params`) (**)

Parameter	Description	Size	Mandatory
`key`	Parameter key to send to acquirer/authorizer.	< 1024 AN	NO
`value`	Parameter value to send to acquirer / authorizer.	< 1024 AN	NO

(*) This field is not required if the product item is a digital product (see item object, type field), so there is no product delivery. Ex: e-books, digital songs, etc.

NOTE: The field that defines whether the item is digital or not is the type field of the item object.

(**) acquirer_params: This field groups key + value format parameters, to specific acquirer parameters. In PayPal case, the following parameters can be sent here:

Key	Value
`reqConfirmShipping`	Indicates whether or not merchant with PayPal be a confirmed address. For digital products, this field is required, and merchant must set it to 0 (zero). It is one of the following values: `0` - Merchant do not require the buyer's shipping address be a confirmed address; `1` - Merchant require the buyer's shipping address be a confirmed address; For digital or virtual products (eg electronic books and digital music - products that are delivered via the web), the parameter is required and must be set to `0` (zero).
`noShipping`	Determines where or not PayPal displays shipping address fields on the PayPal pages. For digital goods, this field is required, and merchant must set it to `1`. It is one of the following values: `0` - PayPal displays the shipping address on the PayPal pages; `1` - PayPal does not display shipping address fields whatsoever; `2` - If merchant do not pass the shipping address, PayPal obtains it from the buyer's account profile.
`allowNote`	Enables the buyer to enter a note to the merchant on the PayPal page during checkout. It is one of the following values: `0` - The buyer is unable to enter a note to the merchant; `1` - The buyer is able to enter a note to the merchant.
`addrOverride`	Determines whether or not the PayPal pages should display the shipping address set by merchant in request, not the shipping address on file with PayPal for this buyer. Displaying the PayPal street address on file does not allow the buyer to edit that address. It is one of the following values: `0` - The PayPal pages should not display the shipping address; `1` - The PayPal pages should display the shipping address.
`localeCode`	Locale of pages displayed by PayPal during Express Checkout. It is one of the following values supported by PayPal: `AU` - Australia `AT` - Austria `BE` - Belgium `BR` - Brazil `CA` - Canada `CH` - Switzerland `CN` - China `DE` - Germany `ES` - Spain `GB` - United Kingdom `FR` - France `IT` - Italy `NL` - Netherlands `PL` - Poland `PT` - Portugal `RU` - Russia `US` - United States For country-specific languages: `da_DK` - Danish (only for Denmark) `he_IL` - Hebrew (all the locations) `id_ID` - Indonesian (Indonesia only) `jp_JP` - Japanese (Japan only) `no_NO` - Norwegian (Norway only) `pt_BR` - Brazilian Portuguese (only for Portugal and Brazil) `ru_RU` - Russian (for Lithuania, Latvia, and Ukraine) `sv_SE` - Swedish (only for Sweden) < br /> `th_TH` - Thai (Thailand only) `tr_TR` - Turkish (Turkey Only) `zh_CN` - Simplified Chinese (C only) hina) `zh_HK` - Traditional Chinese (Hong Kong Only) `zh_TW` - Traditional Chinese (Taiwan Only) NOTE: If the locale code is not supplied or the supplied value is not one of the above-listed values, it is defaulted by PayPal. The default is determined using information about the current merchant, user, and other information for the session.
`pageStyle`	Name of the Custom Payment Page Style for payment pages associated with this button or link. It corresponds to the HTML variable page_style for customizing payment pages. Max 30 alphabetic characters.
`hdrBorderColor`	Sets the border color around the header of the payment page. The border is a 2-pixel perimeter around the header space, which is 750 pixels wide by 90 pixels high. By default, the color is black. Max 6-character HTML hexadecimal ASCII color code.
`hdrBackColor`	Sets the background color for the header of the payment page. By default, the color is white. Max 6-character HTML hexadecimal ASCII color code.
`payFlowColor`	Sets the background color for the payment page. By default, the color is white. Max 6-character HTML hexadecimal ASCII color code.
`cartBorderColor`	The HTML hex code for merchant's principal identifying color. PayPal blends merchant's color to white in a gradient fill that borders the cart review area of the PayPal checkout user interface. Max 6-character HTML hexadecimal ASCII color code.
`landingPage`	Type of PayPal page to display. It is one of the following values: `Billing` - Non-PayPal account; `Login` - PayPal account login. Default value is `Login`.
`buyerEmailOptinenable`	Enables the buyer to provide their email address on the PayPal pages to be notified of promotions or special events. Is one of the following values: `0` - Do not enable buyer to provide email address; `1` - Enable the buyer to provide email address.
`paymentRequest_0_paymentReason`	Indicates the type of transaction. It is one of the following values: `None` - Transaction is not identified as a particular type; `Refund` - Identifies the transaction as a refund.
`paymentRequest_0_insuranceOptionOffered`	Indicates whether insurance is available as an option the buyer can choose on the PayPal Review page. Merchant can specify up to `10` payments, where `n` is a digit between `0` and `9` , inclusive. Is one of the following values: `true` - With option. `false` - Without option.
`paymentRequest_0_custom`	A free-form field for merchant use. Merchant can specify up to `10` payments, where `n` is a digit between `0` and `9`, inclusive. Max 256 alphanumeric characters
`paymentRequest_0_noteText`	Note to the merchant. Merchant can specify up to `10` payments, where n is a digit between `0` and `9` , inclusive. Max 255 characteres.

Important: Despite of PayPal support for multiple item groups, e-SiTef supports only one item group in a single payment.

JSON request examples to begin PayPal transaction in e-SiTef

Below are shown request examples to begin a PayPal transaction in e-SiTef.

Minimum request example:

Minimum request JSON object:

{
    "merchant_id":"CODIGOLOJA",
    "amount":"1000",
    "authorizer_id":"400",
    "additional_data":{
        "currency":"BRL",
        "payer":{
            "identification_type":"BR_CPF",
            "identification_number":"12345678901"
        }
    }
}

Complete request example:

{
    "merchant_id":"CODIGOLOJA",
    "merchant_usn":"1234567890",
    "order_id":"pedido45687",
    "authorizer_id":"400",
    "amount":"1000",
    "redirect":"M",
    "style":"P",
    "soft_descriptor":"MINHALOJA",
    "additional_data":{
        "item_amount":"1000",
        "tax_amount":"0",
        "insurance_amount":"0",
        "handling_amount":"0",
        "extra_info":"descricao",
        "currency":"BRL",
        "items":[
            {
                "id":"1",
                "title":"bola 1",
                "quantity":"1",
                "unit_price":"500",
                "currency":"BRL",
                "url":"http://sportv.globo.com/platb/files/1103/2011/08/bola_futebol.gif",
                "type":"Physical",
                "description":"bola para jogar 1",
                "weight": "100",
                "length": "20",
                "width": "20",
                "height": "20",
                "tax_amount": "0"
            },
            {
                "id":"2",
                "title":"bola 2",
                "quantity":"2",
                "unit_price":"250",
                "currency":"BRL",
                "url":"http://sportv.globo.com/platb/files/1103/2011/08/bola_futebol.gif",
                "type":"Physical",
                "description":"bola para jogar 2",
                "weight": "200",
                "length": "20",
                "width": "20",
                "height": "20",
                "tax_amount": "0"
            }
        ],
        "payer":{
            "email":"js@softexpress.com.br",
            "identification_type":"CPF",
            "identification_number":"09719224703"
        },
        "shipment":{
            "cost": "0",
            "discount_amount": "0",
            "receiver_address":{
                "zip_code": "12345678",
                "street_number": "Rua do Exemplo",
                "street_name": "123",
                "name": "Rafael do Mel",
                "phone_area_code": "11",
                "phone_number": "912341234",
                "city": "São Paulo",
                "complement": "Sobreloja 3",
                "country": "BRA",
                "state": "SP"
            }
        },
        "extra_param": {
            "acquirer_params": [
                {
                    "key": "reqConfirmShipping",
                    "value": "0"
                },
                {
                    "key": "noShipping",
                    "value": "1"
                },
                {
                    "key": "allowNote",
                    "value": "1"
                },
                {
                    "key": "addrOverride",
                    "value": "1"
                },
                {
                    "key": "localeCode",
                    "value": "pt_BR"
                },
                {
                    "key": "pageStyle",
                    "value": ""
                },
                {
                    "key": "hdrBorderColor",
                    "value": ""
                },
                {
                    "key": "hdrBackColor",
                    "value": ""
                },
                {
                    "key": "payFlowColor",
                    "value": ""
                },
                {
                    "key": "cartBorderColor",
                    "value": ""
                },
                {
                    "key": "landingPage",
                    "value": ""
                },
                {
                    "key": "buyerEmailOptinenable",
                    "value": "0"
                },
                {
                    "key": "paymentRequest_0_paymentReason",
                    "value": "none"
                },
                {
                    "key": "paymentRequest_0_insuranceOptionOffered",
                    "value": "false"
                },
                {
                    "key": "paymentRequest_0_custom",
                    "value": ""
                },
                {
                    "key": "paymentRequest_0_noteText",
                    "value": "Obrigado por comprar na Loja Teste!"
                }
            ]
        }
    }
}

PayPal transactions cancelling

The PayPal transaction cancelling or refunding are available in e-SiTef at two interfaces:

REST Cancel WebService and;
Merchant's Portal.

Refund using Merchant's Portal

When cancelling a PayPal transaction via Merchant's Portal the following screen will be displayed during the process:

Cancelamento via Portal

The following table shows the description of the form fields:

Parameter	Description	Mandatory
`Valor`	Refund amount.	YES
`Tipo de Reembolso`	Type of refund the merchant is making. Allowed values: `Total` - Full refund. `Parcial` - Partial refund.	YES
`Fonte do Reembolso`	Type of PayPal funding source (balance or eCheck) that can be used for auto refund Allowed values: `Qualquer disponível` - The merchant does not have a preference. Use any available funding source. `Padrão` - Use the merchant's preferred funding source, as configured in the merchant's profile. `Imediato` - Use the merchant's balance as the funding source. `eCheck` - The merchant prefers using the eCheck funding source. If the merchant's PayPal balance can vocer the refund amount, use the PayPal balance.	YES
`Tentar novamente até`	Format: YYYY-MM-DDTHH:MM:SS. Maximum time until merchant must retry the refund.	NO
`Invoice ID`	Merchant invoice or tracking number.	NO
`Message ID`	A message ID used for idempotence to uniquely identify a message. This ID can later be used to request the latest results for a previous request without generating a new request. Examples of this include requests due to timeouts or errors during the original request.	NO
`Store ID`	Identifier of the merchant store at which the refund is given. This field is required for point-of-sale transactions.	NO
`Terminal ID`	ID of the terminal, in point-of-sale transactions.	NO
`Refund Advice`	Flag to indicate that the buyer was already given store credit for a given transaction. Allowed values: `Verdadeiro` - The buyer was already given store credit for a given transaction. `Falso` - The buyer was not given store credit for a given transaction.	NO
`Anotações`	Custom memo about the refund.	NO
`Detalhes da loja`	Information about the merchant store.	NO