PayPal

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

Carat Portal supported interfaces for integration#

The following interfaces are available for Integrations using PayPal:

HTML Payment Interface 2.0
Refund Web Service
Refunding by Carat Portal Merchant's Portal

PayPal authorizer id code in Carat Portal#

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 Carat Portal, 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 Carat Portal 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 Carat Portal	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 Carat Portal test and Certification environment, but in Carat Portal Production environment, merchant must use real PayPal account data.

Register PayPal account data in Carat Portal#

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

PayPal authorizer activation in merchant account in Carat Portal;
Username and password to access Carat Portal 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 Carat Portal logo.

Payment Flow with PayPal#

Carat Portal uses PayPal's Express Checkout API to payment integration.

The common payment flow using Carat Portal to integrate with PayPal API is described in steps below:

The user starts payment in Carat Portal;
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 Carat Portal;
After receiving redirected user, Carat Portal makes a query on PayPal and updates the transaction status on Carat Portal;
If the merchant configured automatic redirecting in Carat Portal, the user is automatic redirected to registered Success URL or Failure URL.

The input/output diagram below shows a PayPal payment flow via Carat Portal:

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 Carat Portal resulting from communication between Carat Portal 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 Carat Portal#

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 Carat Portal 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) `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, Carat Portal supports only one item group in a single payment.

JSON request examples to begin PayPal transaction in Carat Portal#

Below are shown request examples to begin a PayPal transaction in Carat Portal.

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 Carat Portal 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

Home