PayPal

Esta página tiene como objetivo presentar la configuración y los procedimientos necesarios para la integración del sitio web del comerciante como medio de pago PayPal, a través de la interfaz de pago HTML del Portal Carat, y también para contracargos a través de la interfaz WebService e pelo Portal del Comerciante.

Interfaces Portal Carat apoyado para la integración

Puede utilizar las siguientes interfaces para la integración con el enrutamiento Paypal:

• Interfaz de pago HTML 2.0
• Interfaz WebService Refund para contracargos
• Portal del Comerciante para contracargos

Código de autorización en el Portal Carat para PayPal

El código de autorización para usar PayPal es 400. Para obtener más códigos de autorización, visite el Autorizadoras.

Credenciales requeridas

Antes de realizar transacciones de PayPal con Portal Carat, deben seguirse los pasos de configuración que se presentan a continuación.

Datos de registro de la tienda de PayPal

La tienda debe crear una cuenta de PayPal si aún no tiene una. Mas información en www.paypal.com.br. Siga las instrucciones en Criar conta PayPal. Dentro de su cuenta, cree las credenciales necesarias.

PayPal permite, desde la cuenta registrada como Empresa (ou Business), que se crean cuentas virtuales para el sandbox - el entorno de prueba de PayPal. Para el proceso de aprobación en Portal Carat, se sugiere que se cree una cuenta en sandbox. Busque la opción en el sitio web dentro de su cuenta PayPal.

A continuación se muestran los datos de Registro de PayPal de la tienda que se deben obtener a través del sistema PayPal:

Nombre de campo en Portal Carat	Descripción del campo	Obligatorio
USER	Nombre de usuario asociado a la cuenta PayPal	Si
PWD	Contraseña de USER	Si
SIGNATURE	Auscripción asociada al USER	Si

Importante: Las credenciales de la zona de pruebas de PayPal se puede utilizar en el proceso de aprobación. pero en el entorno de producción, las credenciales de la cuenta real de la tienda deben registrarse en PayPal.

Inserte los datos de registro en el Portal Carat

Teniendo a mano los datos de registro de PayPal mencionados anteriormente, el comerciante debe preguntar al equipo de servicio al cliente Portal Carat:

• Activación del Autorizador de PayPal al registrar la tienda en Portal Carat.
• Si no lo tiene, un usuario y contraseña para acceder al Portal del Comerciante en Portal Carat.

El propietario de la tienda puede registrar la información obtenida con PayPal en el Portal del Comerciante de Portal Carat. Para obtener más información, vaya a Configuración del autorizador en el Portal del Comerciante.

Imagen de logotipo o encabezado personalizado en la página de PayPal

El comerciante puede elegir entre un logotipo o una imagen de encabezado (header) que se mostrará en la pantalla de PayPal. Las dimensiones del logotipo son 190 píxeles x 60 píxeles y las dimensiones del header son 915 pixels x 85 pixels. La imagen debe enviarse al equipo de PayPal, quien se encargará de editarla, haciendo coincidir el logo de la Portal Carat.

Flujo de Pago de PayPal

PayPal proporciona un modelo de pago seguro a través del Express Checkout, una solución de pago donde las llamadas se realizan con datos únicos para cada cliente y un token único se devuelve por cada transacción creada. El Portal Carat se integra con PayPal usando esta API.

El proceso de pago fluye en Portal Carat a través de PayPal de la siguiente manera:

1. El usuario inicia el pago a través de Portal Carat;
2. Se presenta al usuario la lista de autorizadores configurados en la tienda;
3. El usuario elige el método de pago de PayPal;
4. En este punto, se abrirá una nueva ventana, redirigiendo al usuario al sitio web de PayPal;
5. El usuario inicia el proceso de pago en el sitio web de PayPal, donde se realiza la autenticación del usuario y la autorización de pago;
6. El usuario completa el pago en el entorno de PayPal;
7. PayPal redirige al usuario a Portal Carat.
8. Al recibir la redirección del usuario, Portal Carat realiza una consulta a PayPal y actualiza el estado de la transacción en Portal Carat.
9. Si la tienda ha configurado la redirección automática, el usuario es redirigido a la URL de éxito o fracaso configurada en Portal Carat.

El siguiente diagrama de flujo ilustra un flujo de pago de PayPal a través de Portal Carat:

Un caso de excepción a este flujo es el caso en el que la transacción comienza con la autorización predeterminada de PayPal, donde los pasos 2 y 3 No son necesarios.

Aviso de Status

Para cada cambio de estado de transacción en Portal Carat, resultante de la comunicación entre Portal Carat y PayPal, un Aviso de Status. Para mais detalhes sobre esta funcionalidade, ver la página sobre Aviso de Status.

Parámetros de la transacción de pago via PayPal

Los parámetros utilizados para crear una transacción de pago con PayPal son los mismos que se presentan en Crear transacción de pago vía HTML.

Además de los parámetros comunes, es posible enviar los campos específicos a Paypal que se describen a continuación en la solicitud:

Nombre del parámetro	Descripción	Tamaño	Obligatorio
additional_data	Objeto de tipo ADDITIONALDATA		No

ADDITIONALDATA (additional_data)

Nombre del parámetro	Descripción	Tamaño	Obligatorio
extra_info	Informaciones adicionales.	< 127 AN	No
item_amount	Suma de los valores de los artículos del pedido en centavos. Aquí, los valores unitarios deben multiplicarse (unit_price) dlos artículos con su respectiva cantidad (quantity), para cada artículo. Limitado a US$ 10000 en cualquier moneda.	< 1024 N	No
purchase_summary	Campo para enviar texto personalizado para el texto "Resumen de compra" en la pantalla de pago.	< 1024 AN	No
insurance_amount	Montos totales del seguro para artículos de pedido en centavos. Limitado a US$ 10000 en cualquier moneda.	< 1024 N	No
handling_amount	Costo de tramitación de la venta en centavos. Limitado a US$ 10000 en cualquier moneda.	< 1024 N	No
tax_amount	Tarifas totales incluidas en artículos de pedido en centavos. limitado a US$10000 em cualquier moneda.	< 1024 N	No
items	Objeto de tipo ITEMS		No
payer	Objeto de tipo PAYER		No
shipment	Objeto de tipo SHIPMENT		No
extra_param	Objeto de tipo EXTRAPARAM		No

ITEMS (items)

Nombre del parámetro	Descripción	Tamaño	Obligatorio
id	Identificación del artículo.	< 127 AN	No
title	Título do item.	< 127 AN	No
url	URL del artículo.	< 1024 AN	No
quantity	Cantidad de objetos.	< 10 N	No
unit_price	Precio unitario del artículo en centavos. limitado a US$10000 en cualquier moneda.	< 1024N	No
weight	Corresponde al peso de cada artículo del pedido. Unidad de medida en gramos (g). Ex: 2,3 kg -> 2300	< 10 N	No
description	Descripción del Artículo.	< 127 AN	No
tax_amount	Monto de la tarifa del artículo en centavos. limitado a US$10000 en cualquier moneda.	< 1024 N	No
length	Longitud del artículo. Unidad de medida en centímetros (cm).	< 10 N	No
width	Ancho del artículo. Unidad de medida en centímetros (cm).	< 10 N	No
height	Altura del artículo. Unidad de medida en centímetros (cm).	< 10 N	No
type	Tipo de artículo: Digital – El artículo es un producto digital. Ex: e-books, músicas, etc. Physical – El artículo es un producto físico.	< 10 N	No

PAYER (payer)

Nombre del parámetro	Descripción	Tamaño	Obligatorio
email	Correo electrónico del comprador.	< 127 AN	No
identification_type	Tipo de identificación del comprador. Para Brasil: BR_CPF - CPF del comprador BR_CNPJ - CNPJ del comprador.	< 10 A	Si (NO BRASIL)
identification_number	Número de identificación del comprador.	< 14 AN	Si (NO BRASIL)

SHIPMENT (shipment)

Nombre del parámetro	Descripción	Tamaño	Obligatorio
cost	Informa el costo total de envío del pedido. Formato: centavos. limitado a US\$10000 en cualquier moneda. Ex: 123456 (R$ 1234,56)	< 1024 N	No
discount_amount	Descuento aplicado al envío, en centavos. limitado a US$10000 em cualquier moneda.	< 1024 N	No
receiver_address	Objeto de tipo RECEIVERADDRESS		No

RECEIVERADDRESS (receiver_address)

Nombre del parámetro	Descripción	Tamaño	Obligatorio
zip_code	Código postal de la dirección a entregar.	< 20 AN	Si (*)
street_name	Dirección a entregar. Hasta 100 caracteres combinados con el campo street_number.	< 100 AN	Si (*)
street_number	Número de dirección a entregar. Hasta 100 caracteres combinados con el campo street_name.	< 100 AN	Si (*)
complement	Informar el complemento (bloque, apartamento, etc.) de la dirección de envío del producto.	< 100 AN	Si (*)
city	Informa a la ciudad de la dirección de envío del producto.	< 40 AN	Si (*)
state	Informa el estado de la dirección de envío del producto. Ejemplo: SC (Santa Catarina), SP (São Paulo), etc.	< 2 AN	Si (*)
country	Informa al país de la dirección de envío del producto. seguir el modeloISO 3166-1 alpha-3 (3 letras). Ex: Brasil: BRA	< 2 A	Si (*)
name	Nombre de referencia de la persona de la dirección de envío del producto.	< 32 AN	Si (*)
phone_area_code	Código de área de teléfono de la dirección de envío del producto. Hasta 20 caracteres combinados con el campo phone_number.	< 20 AN	Si (*)
phone_number	Número de teléfono de la dirección de envío del producto. Hasta 20 caracteres combinados con el campo phone_area_code.	< 20 AN	Si (*)

EXTRAPARAM (extra_param)

Nombre del parámetro	Descripción	Tamaño	Obligatorio
acquirer_params	Objeto de tipo ACQUIRERPARAMS		No

ACQUIRERPARAMS (acquirer_params) (**)

Nombre del parámetro	Descripción	Tamaño	Obligatorio
key	Clave de parámetro que se enviará al adquirente o autorizador.	< 1024 AN	No
value	Valor del parámetro que se enviará al adquirente o autorizador.	< 1024 AN	No

(*) Este campo deja de ser obligatorio cuando el artículo en cuestión es exclusivamente digital, es decir, no hay entrega de un producto físico. Ejemplo: livro digital, música, etc.

ATENCIÓN : El campo que define si el ítem es digital o No es el campo type del objeto item.

(**) acquirer_params: Este objeto recopila conjuntos de parámetros en formato clave + valor (key+value), cuando hay parámetros específicos que deben enviarse a un adquirente o autorizador. En el caso de PayPal, se pueden enviar los siguientes parámetros:

Llave	Valor
reqConfirmShipping	Indica si la dirección de envío de PayPal existente debe ser una dirección validada. Para hacer esto, debe asignar uno de los siguientes valores a la variable: 0 - Si No, la dirección de envío debe ser una dirección confirmada; 1 - Si la dirección de envío debe ser una dirección confirmada. Para productos digitales o virtuales (p. Ej., Libros electrónicos y música digital - productos que se entregan a través de web), el parámetro es obligatorio y debe recibir el valor 0 (cero).
noShipping	Determina si la página de PayPal debe mostrar los campos de dirección de envío del pedido. Para productos digitales o virtuales (p. Ej., Libros electrónicos y música digital: productos que se envían a través de web), este parámetro es obligatorio y debe ser 1. 0 - La dirección de envío se muestra en la página de PayPal; 1 - PayPal no muestra los campos de dirección de envío; 2: si la tienda no pasa la dirección de envío, PayPal la obtiene a través del perfil de la cuenta del comprador.
allowNote	Permite que el comprador envíe una nota a la tienda desde la página de PayPal Valores posibles para el parámetro: 0 - El comprador no puede enviar una nota a la tienda; 1: el comprador puede enviar una nota a la tienda.
addrOverride	Determina si la página de PayPal debe mostrar la dirección de envío reenviada por la tienda y no la del sistema de PayPal para un cliente en particular. El cliente no puede editar la dirección, si la que se muestra es de PayPal. Valores posibles para el parámetro: 0 - PayPal muestra la dirección de envío de la tienda. 1 - PayPal no muestra la dirección de envío de la tienda
localeCode	Código de ubicación de la página de PayPal que se muestra durante el proceso de pago. El parámetro puede tomar uno de los siguientes valores, dependiendo de la ubicación: AU - Australia AT - Austria BE - Bélgica BR - Brasil CA - Canadá CH - Suiza CN - China DE - Alemania ES - España GB - Reino Unido FR - Francia IT - Italia NL - Países Bajos PL - Polonia PT - Portugal RU - Rusia US - Estados Unidos Para idiomas específicos en un país: da_DK - Danés (solo para Dinamarca) he_IL - Hebreo (todas las configuraciones regionales) id_ID - Indonesio (solo para Indonesia) jp_JP - Japonés (solo para Japón) no_NO - Noruego (solo para Noruega) pt_BR - Portugués brasileño (solo para Portugal y Brasil) ru_RU - Ruso (para Lituania, Letonia y Ucrania) sv_SE - Sueco (solo para Suecia) th_TH - Tailandés (solo para Tailandia) tr_TR - Turco (solo Turquía) ) zh_CN - Chino simplificado (solo en China) zh_HK - Chino tradicional (solo en Hong Kong) zh_TW - Chino tradicional (solo en China) Taiwán) NOTA: Si el parámetro no existe, PayPal selecciona el idioma según los datos de la tienda, el cliente y la sesión.
pageStyle	Nombre de estilo de página personalizado para páginas de pago asociadas con un botón o enlace. Coincide con la variable Page_style en HTML.
hdrBorderColor	Color (HTML hexadecimal de 6 dígitos) del borde del encabezado de la página de pago. El color predeterminado es el negro.
hdrBackColor	Color de fondo (HTML hexadecimal de 6 dígitos) del encabezado de la página de pago. El color predeterminado es el blanco.
payFlowColor	Color (HTML hexadecimal de 6 dígitos) del fondo de la página de pago. El color predeterminado es el blanco.
cartBorderColor	Color (HTML hexadecimal de 6 dígitos) del borde del resumen del pedido o del carrito. El color del borde es blanco en la parte superior del borde y gradualmente se acentúa al color de referencia a lo largo del borde.
landingPage	Tipo de página de acceso. Valores posibles para el parámetro: Billing - Cuando el usuario no tiene una cuenta de PayPal, se abre una página de registro. Login -Se abre una página de inicio de sesión de PayPal. Si el parámetro No se declara explícitamente, el valor predeterminado es Login.
buyerEmailOptinenable	Permite al comprador ingresar su dirección de correo electrónico en la página PayPay para ser notificado de promociones o eventos especiales. Valores posibles para el parámetro: 0 - PayPal no permite al comprador la opción de registrar su dirección de correo electrónico para recibir avisos. 1 - Permite al comprador la opción de registrar su correo electrónico para recibir avisos.
paymentRequest_0_paymentReason	Identificador de tipo de transacción. Valores posibles para el parámetro: None - Transacción sin tipo. Refund - Transacción de reembolso.
paymentRequest_0_insuranceOptionOffered	Indica si el comprador tendrá la opción de seguro en la página de “review” Se puede especificar para hasta 10 pagos en una transacción de compra, donde el valor de "n" varía de "0" a "9", inclusive. Valores posibles para el parámetro: true - Com opção. false - Sin opción.
paymentRequest_0_custom	Campo para uso gratuito. Puede especificarse para hasta 10 pagos en una transacción de compra, donde el valor de "n" varía entre "0" y "9", inclusive.
paymentRequest_0_noteText	Nota para el comerciante. Puede especificarse para hasta 10 pagos en una transacción de compra, donde el valor de "n" varía entre "0" y "9", inclusive.

Importante: aunque PayPal admite varios grupos de artículos, Portal Carat solo admite 1 artículo por compra.

Ejemplos de request JSON para iniciar transacciones de PayPal

A continuación se muestran ejemplos de requests JSON para iniciar una transacción de PayPal. Ejemplo 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"

}

}

}

Ejemplo 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!"

}

]

}

}

}

Cancelación de transacciones de PayPal

La cancelación o reversión de transacciones de PayPal está disponible en Portal Carat a través de dos interfaces:

• WebService Cancel REST y;
• Portal del Comerciante.

Cancelación a través del Portal de comerciantes

Al cancelar una transacción a través de PayPal Portal del Comerciante aAparecerá la siguiente pantalla durante el proceso:

A continuación se muestran las descripciones de los campos del formulario:

Nombre del parámetro	Descripción	Requerido
Valor	Importe a revertir en la transacción.	Si
Tipo de Reembolso	Tipo de reversión que desea realizar sobre el pago. Valores permitidos: Total - Se desea la reversión total del pago. Parcial – Se desea la reversión parcial del pago.	Si
Fonte do Reembolso	Fuente de fondos del comerciante que se utilizará para realizar la reversión. Valores permitidos: Qualquer disponível – El comerciante No tiene preferencia. Se utilizará cualquier fuente de fondos disponible. Padrão - Se utilizará la fuente de fondos configurada en la cuenta del comerciante. Imediato - El saldo del vendedor se utilizará como fuente de fondos. eCheck - La opción eCheck se utilizará como fuente de fondos. Si el saldo del comerciante puede cubrir el contracargo, se utilizará el saldo.	Si
Tentar novamente até	formato AAAA-MM-DDTHH:MM:SS. Fecha límite y hora hasta la que se intentará la reversión.	No
Invoice ID	Código de pedido del reembolso del propio comerciante para futuras consultas o seguimiento.	No
Message ID	Esta identificación identificará de forma única el mensaje y se puede utilizar para solicitar los últimos resultados de una solicitud anterior sin la necesidad de crear una nueva solicitud. Esto se puede hacer, por ejemplo, en llamadas canceladas por timeout o errores durante el proceso.	No
Store ID	Se usa si es un Punto de Venta.	No
Terminal ID	Se usa si es un Punto de Venta.	No
Refund Advice	Indicador para un cliente de que ya se ha recibido un reembolso por una transacción determinada. Valores permitidos: Verdadeiro - si el cliente ya ha realizado una reversión en una transacción determinada. Falso - si el cliente no ha realizado ninguna reversión en la transacción dada.	No
Anotações	Mensaje personalizado para recordatorios de contracargos.	No
Detalhes da loja	Información del establecimiento comercial.	No