ESCUELA SUPERIOR DE INGENIER IA INGENIER INFORMATICA IA

Manual de Integracin con Paypal o

Ma Isaura Galafate Marque Jose Manuel Llerena Carmona Juan Vzquez Murga a 25 de octubre de 2011

Cap tulo 1

Introduccin o
1.1. Qu es Paypal? e

Paypal perteneciente a Ebay, es una empresa del sector del comercio electrnico que se o dedica en exclusiva al movimiento de dinero entre sus usuarios. No se considera un banco y, por tanto, no se rige por las mismas leyes que stos. Paypal ofrece a sus usuarios una forma e de realizar transacciones gil a travs de internet. Por otro lado, orientado a empresas que a e venden servicios por internet, Paypal les ofrece los siguientes servicios:

Ventas simples o pagos instantneos, productos que ofertan las empresas y cuyos cliena tes pueden realizar el pago a travs de su cuenta con Paypal. e

Donaciones. Organizaciones o empresas que desean ofrecer un servicio de donaciones a sus visitantes y/o clientes.

Subscripciones, lo que se convierte en pagos regularizados.

Carritos de Compra, orientados al sector del Comercio electrnico (tiendas online, ...) o ofrecen una gestin de pagos de los productos que el usuario posee en su carrito. o

Estos servicios ofertados por Paypal conllevan una comisin en forma de porcentaje de o la transaccin realizada y que solo se cargar a la parte que vende u ofrece el servicio en o a cuestin. El funcionamiento de la sincronizacin de Paypal con nuestro sistema es simple, o o en el siguiente grco podremos ver como se realiza. a 1

CAP ITULO 1. INTRODUCCION

Figura 1.1: Esquema de interoperabilidad con Paypal. El Instant Payment Notication (IPN), noticacin instantnea de pago conrma que o a el pago se ha realizado a nuestra aplicacin y esta devuelve el OK a Paypal, es lo que se o conoce como la sincronizacin de pago. o

1.2.

Alta en Paypal

El primer paso hacia la integracin de los servicios de Paypal en nuestra aplicacin, es o o darnos de alta. Existen cuatro tipos de cuentas:

Figura 1.2: Esquema de interoperabilidad con Paypal. Claramente, para implantar un sistema de cobros por medio de Paypal, debemos abrirnos una cuenta Premier o Empresas. La diferencia entre ambos, es la posibilidad de administrar usuarios unicamente, asi que, dependiendo de nuestras necesidades elegiremos la que mejor se adapte a nuestra necesidad.

Cap tulo 2

Integracin de Paypal o
Dependiendo del servicio que deseamos ofrecer, tendremos que desarrollar un tipo de formulario adecuado a l. Paypal dispone de un generador automtico de HTML para cada e a uno de los botones necesarios para integrar dichos servicios. Solo debemos indicarle el tipo de botn o servicio que deseamos incluir en nuestra aplicacin y sta herramienta generar el o o e a cdigo HTML que luego incluiremos en el cdigo de nuestra aplicacin. o o o A continuacin, vamos a ver un ejemplo de la generacin de algunos de los servicios que o o ofrece Paypal.

2.1.

Ejemplos de integracin de servicios o

Comprar ahora.

< form action =" https :// www . paypal . com / cgi - bin / webscr " method =" post " > <! - - Identify your business so that you can collect the payments . --> < input type =" hidden " name =" business " value =" h e r s c h e l g o m e z @ x y z z y u . com " > <! - - Specify a Buy Now button . --> < input type =" hidden " name =" cmd " value =" _xclick " > <! - - Specify details about the item that buyers will purchase . --> < input type =" hidden " name =" item_name " value =" Hot Sauce -12 oz . Bottle " > < input type =" hidden " name =" amount " value ="5.95" > < input type =" hidden " name =" currency_code " value =" USD " > <! - - Display the payment button . --> < input type =" image " name =" submit " border ="0" src =" https :// www . paypal . com / en_US / i / btn / btn_buynow_LG . gif " alt =" PayPal - The safer , easier way to pay online " > < img alt ="" border ="0" width ="1" height ="1" src =" https :// www . paypal . com / en_US / i / scr / pixel . gif " > </ form >

Formulario de Donacin o

CAP ITULO 2. INTEGRACION DE PAYPAL

< form action =" https :// www . paypal . com / cgi - bin / webscr " method =" post " > <! - - Identify your business so that you can collect the payments . --> < input type =" hidden " name =" business " value =" d o n a t i o n s @ k c p a r k f r i e n d s . org " > <! - - Specify a Donate button . --> < input type =" hidden " name =" cmd " value =" _donations " > <! - - Specify details about the contribution --> < input type =" hidden " name =" item_name " value =" Friends of the Park " > < input type =" hidden " name =" item_number " value =" Fall Cleanup Campaign " > < input type =" hidden " name =" currency_code " value =" USD " > <! - - Display the payment button . --> < input type =" image " name =" submit " border ="0" src =" https :// www . paypal . com / en_US / i / btn / btn_donate_LG . gif " alt =" PayPal - The safer , easier way to pay online " > < img alt ="" border ="0" width ="1" height ="1" src =" https :// www . paypal . com / en_US / i / scr / pixel . gif " > </ form >

Formulario de Carro de Compra A adir a carro de compra: n

A ade un elemento al carrito, puede indicarse la cantidad de ste de n e forma opcional.

< form target =" paypal " action =" https :// www . paypal . com / cgi - bin / webscr " method =" post " > <! - - Identify your business so that you can collect the payments . --> < input type =" hidden " name =" business " value =" kin@kinskards . com " > <! - - Specify a PayPal Shopping Cart Add to Cart button . --> < input type =" hidden " name =" cmd " value =" _cart " > < input type =" hidden " name =" add " value ="1" > <! - - Specify details about the item that buyers will purchase . --> < input type =" hidden " name =" item_name " value =" Birthday - Cake and Candle " > < input type =" hidden " name =" amount " value ="3.95" > < input type =" hidden " name =" currency_code " value =" USD " > <! - - Display the payment button . --> < input type =" image " name =" submit " border ="0" src =" https :// www . paypal . com / en_US / i / btn / btn_cart_LG . gif " alt =" PayPal - The safer , easier way to pay online " / > < img alt ="" border ="0" width ="1" height ="1" src =" https :// www . paypal . com / en_US / i / scr / pixel . gif " > </ form >

Revisar lista de elementos del carrito.

 2.1. EJEMPLOS DE INTEGRACION DE SERVICIOS

Visualiza el listado del carrito.

< form target =" paypal " action =" https :// www . paypal . com / cgi - bin / webscr " method =" post " > <! - - Identify your business so that you can collect the payments . --> < input type =" hidden " name =" business " value =" kin@kinskards . com " > <! - - Specify a PayPal Shopping Cart View Cart button . --> < input type =" hidden " name =" cmd " value =" _cart " > < input type =" hidden " name =" display " value ="1" > <! - - Display the View Cart button . --> < input type =" image " name =" submit " border ="0" src =" https :// www . paypal . com / en_US / i / btn / bt n_ v ie wc ar t _L G . gif " alt =" PayPal - The safer , easier way to pay online " / > < img alt ="" border ="0" width ="1" height ="1" src =" https :// www . paypal . com / en_US / i / scr / pixel . gif " / > </ form >

Formulario de Subscripcin. o

< form action =" https :// www . paypal . com / cgi - bin / webscr " method =" post " > <! - - Identify your business so that you can collect the payments . --> < input type =" hidden " name =" business " value =" alice@mystore . com " > <! - - Specify a Subscribe button . --> < input type =" hidden " name =" cmd " value =" _xclick - subscriptions " > <! - - Identify the subscription . --> < input type =" hidden " name =" item_name " value =" Alice s Weekly Digest " > < input type =" hidden " name =" item_number " value =" DIG Weekly " > <! - - Set the terms of the regular subscription . --> < input type =" hidden " name =" currency_code " value =" USD " > < input type =" hidden " name =" a3 " value ="5.00" > < input type =" hidden " name =" p3 " value ="1" > < input type =" hidden " name =" t3 " value =" M " > <! - - Display the payment button . --> < input type =" image " name =" submit " border ="0" src =" https :// www . paypal . com / en_US / i / btn / b t n _ s u b s c r i b e _ L G . gif " alt =" PayPal - The safer , easier way to pay online "/ > < img alt ="" border ="0" width ="1" height ="1" src =" https :// www . paypal . com / en_US / i / scr / pixel . gif " / > </ form >

Todo este codigo HTML es generado automticamente por la herramienta de integracin a o que ofrece Paypal a sus usuarios. Por tanto, slo tendremos que ir a nuestra cuenta y en dicha o herramienta indicar el servicio que deseamos integrar indicando nuestros datos y copiar el cdigo generado en nuestra aplicacin. o o

CAP ITULO 2. INTEGRACION DE PAYPAL

Cap tulo 3

Integracin de Paypal en o proyectos Ruby on Rails

3.1. Introduccin o

Para integrar Paypal en un proyecto desarrollado bajo el framework Ruby on Rails existen numerosas gemas o plugins que nos facilitan en gran medida esta labor. Por poner un ejemplo, si nos vamos a cualquier terminal y escribimos la siguiente orden:
gem list -- remote | grep paypal

Podremos ver una lista de gemas que se dedican a integrar aplicaciones con Paypal. Para este tutorial vamos a basarnos en una gema que es usada en conocidos proyectos de Ruby on Rails llamada ActiveMerchant.

3.2.

Integrando la gema ActiveMerchant

A continuacin, vamos a ver como en una serie de pasos podemos integrar la gema o ActiveMerchant en nuestro proyecto. En este tutorial, vamos a implantar un carro de la compra desde la instalacin de la gema hasta su integracin con el modelo. o o

3.2.1.

Instalacin o

Para instalarnos ActiveMerchant nos dirigimos a la terminal y escribimos la siguientes lineas:

gem install activem erchant

Con este comando automticamente se aadir la gema al listado disponible para nuestro a n a proyecto.

3.2.2.

Conguracin o

El siguiente paso tras instalar la gema es indicar los datos de la cuenta de Paypal con la que gestionaremos los pagos de nuestro producto o servicio a nuestros clientes. Para ello, vamos a los archivos de entorno que se encuentran en RAILS ROOT/conf/environment/. Para cada entorno indicaremos una conguracin distinta dependiendo de si es entorno de o produccin, desarrollo o testing. o cong/environment/development.rb

CAP ITULO 3. INTEGRACION DE PAYPAL EN PROYECTOS RUBY ON RAILS

config . a f t e r _ i n i t i a l i z e do Acti veMerch ant :: Billing :: Base . mode = : test :: GATEWAY = ActiveMe rchant :: Billing :: PaypalGateway . new ( : login = > " s e l l e r _ 1 2 2 9 8 9 9 1 7 3 _ b i z _ a p i 1 . railscasts . com " , : password = > " F X WU 5 8 S 7 K X F C 6 H B E " , : signature = > " AGjv6SW . mTiKxtkm6L9DcSUCUgePAUDQ3L - k T d s z k P G 8 m R f j a R Z D Y t S u " ) end

cong/environment/test.rb
config . a f t e r _ i n i t i a l i z e do Acti veMerch ant :: Billing :: Base . mode = : test :: GATEWAY = ActiveMe rchant :: Billing :: BogusGateway . new end

cong/environment/production.rb
config . a f t e r _ i n i t i a l i z e do Acti veMerch ant :: Billing :: Base . mode = : production :: GATEWAY = ActiveMe rchant :: Billing :: PaypalGateway . new ( : login = > " s e l l e r _ 1 2 2 9 8 9 9 1 7 3 _ b i z _ a p i 1 . railscasts . com " , : password = > " F X WU 5 8 S 7 K X F C 6 H B E " , : signature = > " AGjv6SW . mTiKxtkm6L9DcSUCUgePAUDQ3L - k T d s z k P G 8 m R f j a R Z D Y t S u " ) end

Una vez establecida la conguracin para cada entorno, debemos congurar los parmeo a tros de inicializacin de la gema. Esto se realiza aadiendo la siguiente linea al archivo o n conf/environment.rb:
config . gem " acti vemerch ant " , : lib = > " a ct iv e _m er ch a nt " , : version = > "1.4.1"

Con esto slo nos queda integrar dentro de nuestro cdigo los mtodos de la gema para o o e realizar la interoperabilidad con Paypal.

3.2.3.

Integracin en la capa de vista y controlador o

A continuacin, vamos a ver un ejemplo de como integrar Paypal en nuestra cesta de la o compra usando ActiveMerchant. El primer paso es aadir a nuestro controllers/application.rb la siguiente linea al princin pio:
f i l t e r _ p a r a m e t e r _ l o g g i n g : card_number , : c a r d _ v e r i f i c a t i o n

El siguiente paso, en el controlador donde generamos nuestro carro de la compra (suo o ponemos cart controller.rb), tenemos una accin como la que se muestra a continuacin:
def create @order = current_cart . build_order ( params [: order ]) @order . ip_address = request . remote_ip if @order . save if @order . purchase render : action = > " success " # Comunicacion realizada con exito else render : action = > " failure " # Error de comunicacion con Paypal end else render : action = > " new " # Nuevo carro de la compra end end

Tenemos 3 acciones para las que debemos desarrollar 3 plantillas donde se generar la a respuesta HTML. La plantilla new, contendr el formulario donde realizaremos el pedido, a success indicar el xito de la operacin y failure que la operacin no ha tenido xito. Veamos a e o o e una posible implementacin de estas tres plantillas: o

3.2. INTEGRANDO LA GEMA ACTIVEMERCHANT new.html.erb

< % form_for @order do | f | %> < %= f . error _messag es %> <p > < %= f . label : first_name %><br / > < %= f . text_field : first_name %> </p > <p > < %= f . label : last_name %><br / > < %= f . text_field : last_name %> </p > <p > < %= f . label : card_type %><br / > < %= f . select : card_type , [[" Visa " , " visa "] , [" MasterCard " , " master "] , [" Discover " , " discover "] , [" A </p > <p > < %= f . label : card_number %><br / > < %= f . text_field : card_number %> </p > <p > < %= f . label : card_verification , " Card Verification Value ( CVV )" %><br / > < %= f . text_field : c a r d _ v e r i f i c a t i o n %> </p > <p > < %= f . label : c ar d _e xp ir e s_ on %><br / > < %= f . date_select : card_expires_on , : discard_day = > true , : start_year = > Date . today . year , : end_year </p > <p >< %= f . submit " Submit " %></p > < % end %>

success.html.erb
<p > Operacion realizada con exito ! </p >

failure.html.erb
<p > Error en la operacion </p >

Ya tenemos realizada la integracin en la capa de vista y en la de controlador, solo nos o falta la capa del modelo de datos.

3.2.4.

Integracin con el modelo de datos o

En el modelo de datos necesitamos relacionar el carro de la compra con las ordenes de compra, que son las que contendrn la informacin de la transaccin a realizar. Veamos la a o o conguracin en el modelo de datos en los siguientes pasos: o models/cart.rb
has_one : order

models/order.rb
class Order < ActiveRecord :: Base belongs_to : cart has_many : transactions , : class_name = > " Or d e r T r a n s a c t i o n " attr_accessor : card_number , : c a r d _ v e r i f i c a t i o n v a l i d a t e _ o n _ c r e a t e : validate_card def purchase

10

CAP ITULO 3. INTEGRACION DE PAYPAL EN PROYECTOS RUBY ON RAILS

response = GATEWAY . purchase ( price_in_cents , credit_card , p u r c h a s e _ o p t i o n s ) transactions . create !(: action = > " purchase " , : amount = > price_in_cents , : response = > response ) cart . u p d a t e _ a t t r i b u t e (: purchased_at , Time . now ) if response . success ? response . success ? end def price_i n_cents ( cart . total_price *100). round end private def p u r c h a s e _ o p t i o n s { : ip = > ip_address , : bi ll i ng _a d dr es s = > { : name = > " Ryan Bates " , : address1 = > "123 Main St ." , : city = > " New York " , : state = > " NY " , : country = > " US " , : zip = > "10001" } } end def validate_card unless credit_card . valid ? credit_card . errors . full_messages . each do | message | errors . add_to_base message end end end def credit_card @credit_card ||= Ac tiveMer chant :: Billing :: CreditCard . new ( : type = > card_type , : number = > card_number , : v e r i f i c a t i o n _ v a l u e = > card_verification , : month = > c ar d_ e xp ir es _ on . month , : year = > c ar d _e xp i re s_ on . year , : first_name = > first_name , : last_name = > last_name ) end end

models/order transaction.rb
class O r d e r T r a n s a c t i o n < ActiveRecord :: Base belongs_to : order serialize : params def response =( response ) self . success = response . success ? self . authorization = response . authorization self . message = response . message self . params = response . params rescue Activ eMercha nt :: A c t i v e M e r c h a n t E r r o r = > e self . success = false self . authorization = nil self . message = e . message self . params = {} end end

Este es un ejemplo de implementacin de la gema ActiveMerchant en nuestro proyecto o Ruby on Rails. Debe de tomarse como una gu y consultar el manual del proyecto para a adaptarla lo mejor posible y para usar el resto de servicios que Paypal ofrece.

Bibliograf a
[1] http://www.scribd.com/doc/2218618/PayPal-integration-guide [2] https://cms.paypal.com/es/cgi-bin/?cmd=_render-content&content_ID= developer/e_howto_html_buynow_buttons [3] http://www.streamhead.com/paypal-integration-guide/ [4] http://www.streamhead.com/choose-your-paypal-api-making-sense-of-the-mess/ [5] http://www.activemerchant.org/

11