PayPal

Esta página tem como objetivo apresentar as configurações e procedimentos necessários para a integração do site do lojista como meio de pagamento PayPal, através da Interface de Pagamento HTML do Carat, e também para estornos via interface WebService e pelo Portal do Lojista.

Interfaces Carat suportadas para integração#

É possível utilizar as seguintes interfaces para a integração com o roteamento Paypal:

Interface de Pagamento HTML 2.0
Interface WebService Refund para estornos
Portal do Lojista para estornos

Código de Autorizadora no Carat para PayPal#

O código de autorizadora para a utilização ddo PayPal é o 400. Para mais códigos de autorizadora, visite a página de Autorizadoras.

Credenciais necessárias#

Antes de efetuar transações PayPal com o Carat, devem ser seguidos os passos de configuração apresentados a seguir.

Dados de cadastro da loja no PayPal#

A loja deverá criar um cadastro no PayPal caso já não o possua. Mais informações em www.paypal.com.br. Siga as instruções em Criar conta PayPal. Dentro da sua conta, crie as credenciais necessárias.

O PayPal permite, a partir da conta cadastrada como Empresarial (ou Business), que sejam criadas contas virtuais para o sandbox - o ambiente de testes do PayPal. Para o processo de homologação no Carat, sugere-se que seja criada uma conta no sandbox. Procure pela opção no site dentro da sua conta PayPal.

Abaixo estão os dados Cadastrais PayPal da loja que devem ser obtidas pela sistema PayPal:

Nome do campo no Carat	Descrição do campo	Obrigatório
USER	Nome de Usuário associado à conta PayPal	SIM
PWD	Senha do USER	SIM
SIGNATURE	Assinatura associada ao USER	SIM

Importante: As credenciais do sandbox do PayPal podem ser utilizados no processo de homologação. Porém no ambiente de produção, devem ser cadastradas as credenciais da conta real da loja no PayPal.

Inserir dados cadastrais no Carat#

Tendo os dados cadastrais PayPal citados acima em mãos, o lojista deve solicitar à equipe de atendimento do Carat:

A ativação da Autorizadora PayPal no cadastro da loja no Carat.
Caso não possua, um usuário e senha de acesso para o Portal do Lojista do Carat.

O próprio lojista pode cadastrar as informações obtidas com a PayPal no Portal do Lojista do Carat. Para mais informações, acesse a página de Configuração de Autorizadora no Portal do Lojista.

Imagem de cabeçalho ou logotipo customizado na página PayPal#

O lojista poderá optar entre um logotipo ou um imagem de cabeçalho (header) para ser apresentado na tela do PayPal. As dimensões do logotipo são 190 pixels x 60 pixels e as dimensões do header são 915 pixels x 85 pixels. A imagem deverá ser enviada à equipe do PayPal, que se encarregará de editar a mesma, combinando com o logotipo do Carat.

Fluxo de Pagamento com PayPal#

O PayPal proporciona um modelo de pagamento seguro por meio do Express Checkout, uma solução de pagamento em que as chamadas são feitas com dados exclusivos para cada cliente e um token único é retornado para cada transação criada. O Carat se integra ao PayPal utilizando esta API.

O fluxo do processo de pagamento no Carat via PayPal segue como abaixo:

O usuário inicia o pagamento pelo Carat;
A lista de autorizadoras configurada na loja é apresentada para o usuário;
O usuário escolhe a forma de pagamento PayPal;
Nesse momento será aberta uma nova janela redirecionando o usuário para o site PayPal;
O usuário inicia o processo de pagamento no site do PayPal, onde ocorre a autenticação do usuário e a autorização do pagamento;
O usuário finaliza o pagamento no ambiente do PayPal;
O PayPal redireciona o usuário para o Carat.
Ao receber o redirecionamento do usuário, o Carat efetua uma consulta ao PayPal e atualiza o status da transação no Carat.
Caso a loja tenha configurado o redirecionamento automático, o usuário é redirecionado à URL de Sucesso ou Fracasso configurado no Carat.

O diagrama de fluxo abaixo ilustra um fluxo de pagamento PayPal via Carat:

Um caso de exceção a esse fluxo é o caso onde se inicia a transação com a autorizadora PayPal pré-fixada, onde os passos 2 e 3 não são necessários.

Aviso de Status#

Para cada alteração de status de transação no Carat, resultante de comunicação entre o Carat e o PayPal, é enviado ao servidor da loja um Aviso de Status. Para mais detalhes sobre esta funcionalidade, consulte a página sobre Aviso de Status.

Parâmetros para transação de pagamento via PayPal#

Os parâmetros usados para se criar uma transação de pagamento com o PayPal são os mesmos que os apresentados no documento de Criação de transação de pagamento via HTML.

Em adição aos parâmetros comuns, é possível enviar na requisição os campos específicos para o Paypal descritos abaixo:

Nome do parâmetro	Descrição	Tamanho	Obrigatório
`additional_data`	Objeto do tipo ADDITIONALDATA		NÃO

ADDITIONALDATA (`additional_data`)#

Nome do parâmetro	Descrição	Tamanho	Obrigatório
`extra_info`	Informações adicionais.	< 127 AN	NÃO
`item_amount`	Soma dos valores dos itens do pedido em centavos. Aqui se devem multiplicar os valores unitários (unit_price) dos itens com sua respectiva quantidade (quantity), para cada item. Limitado a US$10000 em qualquer moeda.	< 1024 N	NÃO
`purchase_summary`	Campo para envio de texto customizado para o texto "Resumo da Compra" na tela de pagamento.	< 1024 AN	NÃO
`insurance_amount`	Total dos valores de seguro dos itens do pedido em centavos. Limitado a US$10000 em qualquer moeda.	< 1024 N	NÃO
`handling_amount`	Custo de processamento da venda em centavos. Limitado a US$10000 em qualquer moeda.	< 1024 N	NÃO
`tax_amount`	Total das taxas inclusas nos itens do pedido em centavos. Limitado a US$10000 em qualquer moeda.	< 1024 N	NÃO
`items`	Objeto do tipo ITEMS		NÃO
`payer`	Objeto do tipo PAYER		NÃO
`shipment`	Objeto do tipo SHIPMENT		NÃO
`extra_param`	Objeto do tipo EXTRAPARAM		NÃO

ITEMS (`items`)#

Nome do parâmetro	Descrição	Tamanho	Obrigatório
`id`	Identificação do item.	< 127 AN	NÃO
`title`	Título do item.	< 127 AN	NÃO
`url`	URL do item.	< 1024 AN	NÃO
`quantity`	Quantidade do item.	< 10 N	NÃO
`unit_price`	Preço unitário do item em centavos. Limitado a US$10000 em qualquer moeda.	< 1024 N	NÃO
`weight`	Correspondem ao peso de cada item do pedido. Unidade de medida em gramas(g). Ex: 2,3 kg -> 2300	< 10 N	NÃO
`description`	Descrição do item.	< 127 AN	NÃO
`tax_amount`	Valor da taxa do item em centavos. Limitado a US$10000 em qualquer moeda.	< 1024 N	NÃO
`length`	Comprimento do item. Unidade de medida em centímetros (cm).	< 10 N	NÃO
`width`	Largura do item. Unidade de medida em centímetros (cm).	< 10 N	NÃO
`height`	Altura do item. Unidade de medida em centímetros (cm).	< 10 N	NÃO
`type`	Tipo do item: `Digital` – O item é um produto digital. Ex: e-books, músicas, etc. `Physical` – O item é um produto físico.	< 10 N	NÃO

PAYER (`payer`)#

Nome do parâmetro	Descrição	Tamanho	Obrigatório
`email`	E-mail do comprador.	< 127 AN	NÃO
`identification_type`	Tipo de identificação do comprador. Para o Brasil: `BR_CPF` - CPF do comprador `BR_CNPJ` - CNPJ do comprador.	< 10 A	SIM (NO BRASIL)
`identification_number`	Número de identificação do comprador.	< 14 AN	SIM (NO BRASIL)

SHIPMENT (`shipment`)#

Nome do parâmetro	Descrição	Tamanho	Obrigatório
`cost`	Informa o valor total de frete do pedido. Formato: centavos. Limitado a US\$10000 em qualquer moeda. Ex: 123456 (R$ 1234,56)	< 1024 N	NÃO
`discount_amount`	Desconto aplicado ao frete, em centavos. Limitado a US$10000 em qualquer moeda.	< 1024 N	NÃO
`receiver_address`	Objeto do tipo RECEIVERADDRESS		NÃO

RECEIVERADDRESS (`receiver_address`)#

Nome do parâmetro	Descrição	Tamanho	Obrigatório
`zip_code`	CEP do endereço a ser entregue.	< 20 AN	SIM (*)
`street_name`	Endereço a ser entregue. Até 100 caracteres combinados com o campo `street_number`.	< 100 AN	SIM (*)
`street_number`	Número do endereço a ser entregue. Até 100 caracteres combinados com o campo `street_name`.	< 100 AN	SIM (*)
`complement`	Informa o complemento (bloco, apartamento, etc.) do endereço de envio do produto.	< 100 AN	SIM (*)
`city`	Informa a cidade do endereço de envio do produto.	< 40 AN	SIM (*)
`state`	Informa o estado do endereço de envio do produto. Exemplo: SC (Santa Catarina), SP (São Paulo), etc.	< 2 AN	SIM (*)
`country`	Informa o país do endereço de envio do produto. Segue o padrão ISO 3166-1 alpha-3 (3 letras). Ex: Brasil: `BRA`	< 2 A	SIM (*)
`name`	Nome de referência da pessoa do endereço de envio do produto.	< 32 AN	SIM (*)
`phone_area_code`	Código do área do telefone do endereço de envio do produto. Até 20 caracteres combinados com o campo `phone_number`.	< 20 AN	SIM (*)
`phone_number`	Número do telefone do endereço de envio do produto. Até 20 caracteres combinados com o campo `phone_area_code`.	< 20 AN	SIM (*)

EXTRAPARAM (`extra_param`)#

Nome do parâmetro	Descrição	Tamanho	Obrigatório
`acquirer_params`	Objeto do tipo ACQUIRERPARAMS		NÃO

ACQUIRERPARAMS (`acquirer_params`) (**)#

Nome do parâmetro	Descrição	Tamanho	Obrigatório
`key`	Chave do parâmetro a ser enviado para a adquirente ou autorizadora.	< 1024 AN	NÃO
`value`	Valor do parâmetro a ser enviado para a adquirente ou autorizadora.	< 1024 AN	NÃO

(*) Esse campo deixa de ser obrigatório quando o item em questão for exclusivamente digital, ou seja, não houver entrega de produto físico. Exemplo: livro digital, música, etc.

ATENÇÃO: O campo que define se o item é digital ou não é o campo type do objeto item.

(**) acquirer_params: Este objeto coleta conjunto de parâmetros em formato chave+valor (key+value), quando existem parâmetros específicos que devem ser enviados para um adquirente ou autorizadora. No caso do PayPal, os seguintes parâmetros são possíveis de envio:

Chave	Valor
`reqConfirmShipping`	Indica se é necessário que o endereço de envio existente no PayPal precisa ser um endereço validado. Para isso deve atribuir à variável um dos valores abaixo: `0` - Se não é necessário que o endereço de envio seja um endereço confirmado; `1` - Se é necessário que o endereço de envio seja um endereço confirmado. Para produtos digitais ou virtuais (Ex: livros eletrônicos e músicas digitais - produtos que são entregues via web), o parâmetro é obrigatório e deve receber o valor `0` (zero).
`noShipping`	Determina se a página do PayPal deve mostrar os campos de endereço para envio do pedido. Para produtos digitais ou virtuais (Ex: livros eletrônicos e músicas digitais - produtos que são entregues via web), este parâmetro é obrigatório e deve ser `1`. `0` - É mostrado o endereço de envio na página do PayPal; `1` - PayPal não mostra campos do endereço de envio; `2` - Se a loja não passa o endereço de envio, PayPal obtém ele por meio do perfil da conta do comprador.
`allowNote`	Torna possível para o comprador enviar uma nota para a loja a partir da página do PayPal. Valores possíveis para o parâmetro: `0` - O comprador não é capaz de enviar uma nota para a loja; `1` - O comprador é capaz de enviar uma nota para a loja.
`addrOverride`	Determina se a página do PayPal deve mostrar o endereço de envio encaminhado pela loja e não o existente no sistema do PayPal para um determinado cliente. O cliente não consegue editar o endereço, se o mostrado for oriundo do PayPal. Valores possíveis para o parâmetro: `0` - O PayPal mostra o endereço de envio proveniente da loja. `1` - O PayPal não mostra o endereço de envio proveniente da loja
`localeCode`	Código da localidade da página do PayPal mostrada durante o processo de compra. O parâmetro pode assumir um dos seguintes valores, de acordo com a localidade: `AU` - Austrália `AT` - Áustria `BE` - Bélgica `BR` - Brasil `CA` - Canadá `CH` - Suíça `CN` - China `DE` - Alemanha `ES` - Espanha `GB` - Reino Unido `FR` - França `IT` - Itália `NL` - Holanda `PL` - Polônia `PT` - Portugal `RU` - Rússia `US` - Estados Unidos Para línguas específicas em um país: `da_DK` - Dinamarquês (somente para a Dinamarca) `he_IL` - Hebraico (todas as localidades) `id_ID` - Indonésio (apenas para a Indonésia) `jp_JP` - Japonês (somente para o Japão) `no_NO` - Norueguês (somente para a Noruega) `pt_BR` - Português Brasileiro (apenas para Portugal e Brasil) `ru_RU` - Russo (para a Lituânia, Letônia, e Ucrânia) `sv_SE` - Sueco (apenas para a Suécia) `th_TH` - Tailandês (apenas para a Tailândia) `tr_TR` - Turco (Somente para a Turquia) `zh_CN` - Chinês simplificado (apenas para China) `zh_HK` - Chinês tradicional (apenas para Hong Kong) `zh_TW` - Chinês tradicional (apenas para Taiwan) NOTA: Se o parâmetro não existir, o PayPal seleciona a língua com base nos dados da loja, do cliente e da sessão.
`pageStyle`	Nome do estilo da página customizada para páginas de pagamento associadas a um botão ou link. Corresponde a variável Page_style em HTML.
`hdrBorderColor`	Cor (em HTML hexadecimal de 6 dígitos) da borda do cabeçalho da página de pagamento. A cor padrão é preta.
`hdrBackColor`	Cor (em HTML hexadecimal de 6 dígitos) de fundo do cabeçalho da página de pagamento. A cor padrão é branca.
`payFlowColor`	Cor (em HTML hexadecimal de 6 dígitos) de fundo da página de pagamento. A cor padrão é branca.
`cartBorderColor`	Cor (em HTML hexadecimal de 6 dígitos) da borda do resumo do pedido ou carrinho. A cor da borda é branca no topo da borda e gradativamente ela vai acentuando-se até a cor de referência ao decorrer da borda.
`landingPage`	Tipo de página de acesso. Valores possíveis para o parâmetro: `Billing` - Quando o usuário não tem conta no PayPal é aberta uma página de cadastro. `Login` - É aberta uma página de login no PayPal. Se o parâmetro não for declarado explicitamente, o valor padrão é `Login`.
`buyerEmailOptinenable`	Permite que o comprador possa inserir seu endereço de e-mail na página do PayPay para ser notificado de promoções ou eventos especiais. Valores possíveis para o parâmetro: `0` - PayPal não habilita o comprador a opção de cadastrar seu e-mail para eventuais avisos. `1` - Habilita o comprador a opção de cadastrar seu e-mail para eventuais avisos.
`paymentRequest_0_paymentReason`	Identificador do tipo de transação. Valores possíveis para o parâmetro: `None` - Transação sem tipo. `Refund` - Transação de reembolso.
`paymentRequest_0_insuranceOptionOffered`	Indica se o comprador terá a opção de seguro na página de “review” do PayPal. Pode ser especificado para até 10 pagamentos em um transação de compra, em que o valor de `n` varia entre `0` e `9`, inclusive . Valores possíveis para o parâmetro: `true` - Com opção. `false` - Sem opção.
`paymentRequest_0_custom`	Campo de livre uso. Pode ser especificado para até 10 pagamentos em um transação de compra, em que o valor de `n` varia entre `0` e `9`, inclusive.
`paymentRequest_0_noteText`	Nota para o lojista. Pode ser especificado para até 10 pagamentos em um transação de compra, em que o valor de `n` varia entre `0` e `9`, inclusive.

Importante: Apesar do PayPal oferecer suporte a vários grupos de itens, o Carat suporta apenas 1 grupo por compra.

Exemplos de request JSON para iniciar transações PayPal#

Seguem exemplos de requests JSON para iniciar uma transação PayPal. Exemplo de request mínimo:

Objeto JSON request mínimo:

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

Exemplo de request completo:

{
  "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!"
        }
      ]
    }
  }
}

Cancelamento de transações PayPal#

O cancelamento ou estorno de transações PayPal estão disponíveis no Carat através de duas interfaces:

Cancelamento via Portal do Lojista#

Ao realizar um cancelamento de uma transação PayPal via Portal do Lojista a seguinte tela será exibida durante o processo:

Cancelamento via Portal -no-filter

Abaixo estão as descrições dos campos do formulário:

Nome do parâmetro	Descrição	Obrigatório
`Valor`	Valor a ser estornado na transação.	SIM
`Tipo de Reembolso`	Tipo de estorno que se deseja realizar sobre o pagamento. Valores permitidos: `Total` - É desejado o estorno completo do pagamento. `Parcial` – É desejado o estorno parcial do pagamento.	SIM
`Fonte do Reembolso`	Fonte de fundos do lojista que será utilizado para realizar o estorno. Valores permitidos: `Qualquer disponível` – O lojista não tem preferência. Será utilizado qualquer fonte de fundos disponível. `Padrão` - Será utilizado a fonte de fundos configurada na conta do lojista. `Imediato` - Será utilizado o balanço do vendedor como fonte de fundos. `eCheck` - Será utilizado a opção eCheck como fonte de fundos. Se o balanço do lojista puder cobrir o estorno, será utilizado o balanço.	SIM
`Tentar novamente até`	formato AAAA-MM-DDTHH:MM:SS. Data e hora limite até a qual será realizada a tentativa do estorno.	NÃO
`Invoice ID`	Código de pedido do estorno próprio do lojista para futura consulta ou rastreamento.	NÃO
`Message ID`	Esse ID identificará de maneira única a mensagem e poderá ser utilizado para requisitar os últimos resultados de um requisição anterior sem a necessidade de criar uma nova requisição. Isso pode ser realizado, por exemplo, em chamadas que foram canceladas por timeout ou erros durante o processo.	NÃO
`Store ID`	Utilizado caso seja um Ponto de Venda.	NÃO
`Terminal ID`	Utilizado caso seja um Ponto de Venda.	NÃO
`Refund Advice`	Indicador para cliente que já foi recebido algum estorno da determinada transação. Valores permitidos: `Verdadeiro` - caso o cliente já tenho realizado algum estorno na determinada transação. `Falso` - caso o cliente não tenha feito nenhum estorno na determinada transação.	NÃO
`Anotações`	Mensagem personalizada para lembretes sobre o estorno.	NÃO
`Detalhes da loja`	Informações sobre o estabelecimento do lojista.	NÃO

Home