|
IMPORTANTE
ANTES DE PROBAR ESTOS EJEMPLOS USTED DEBE CAMBIAR ALGUNAS COSAS
* En el codigo fuente de estos ejemplos DEBE CAMBIAR
yourname_nnnnnnnnnn_biz@yourdomain.com con su propio email de prueba PayPal IPN.
* Dentro del script ipn.php reemplace estos valores:
$to_address = 'alcides@valega.com';
$from_address = 'sales@valega.com';
$from_name = 'av-soft.com';
$confirmation_subject = 'Payment Confirmation';
EJEMPLOS PAYPAL IPN
Items
1. Que es el servicio IPN de PayPal?
2. Que es el Sandbox de PayPal?
3. Utilizar IPN con el OLM desde una aplicación Delphi
4. El Ejemplo 1
5. Detalles adicionales
6. El ejemplo 2
Que es el servicio IPN de PayPal?
El IPN (Instant Payment Notification) es un servicio de mensaje que notifica los eventos relacionados con una transacción PayPal.
Esta notificación es enviada a una URL que Ud. especifica, que llamamos Listener (oyente) y que es la encargada de procesar las transacciones realizadas en su cuenta de PayPal. De esta manera al efectuarse una transacción por ejemplo un pago a su cuenta, su URL recibirá instantaneamente toda la información relativa a esta operación.
Hay dos maneras de especificar la URL Listener a fin de que PayPal sepa donde enviar las notificaciones IPN.
1. Seleccionando Instant Payment Notification en el perfil de su cuenta y especificando la URL listener y marcando la casilla [x]Activate it.
2. En forma dinámica incluyendo la URL Listener junto con los datos al solicitar un pago, por ejemplo desde un botón [Pagar Ahora].
Nosotros en nuestro ejemplo utilizaremos la segunda opción, especificando la URL Listener junto con los datos de la solicitud de pago.
Puede obtener más información descargando la quia IPN desde el siguiente vínculo: https://cms.paypal.com/cms_content/US/en_US/files/developer/IPNGuide.pdf
Que es el Sandbox de PayPal?
Cuando se está implementando el listener, que en nuestro caso es un script php (ipn.php), se hace necesario probarlo y depurarlo como cualquier otra pieza de software, y estas pruebas no se pueden hacer utilizando nuestra cuenta real de PayPal (Live PayPal), para ello, PayPal tiene un sitio aparte que es llamado el Sandbox (caja de arena) donde se pueden realizar las pruebas utilizando cuentas ficticias.
Para crear las cuentas ficticias debe antes crear una cuenta en el Sandbox de PayPal. Este es el vínculo deonde podrá hacerlo:
https://developer.paypal.com
Cree su cuanta utilizando una dirección de email distinta a la de su cuenta real de PayPal. Una vez creada su cuenta seleccione "Test Accounts"
Después Cree cómo mínimo dos cuentas; una para simular al venderdor y otra para el comprador. La de vendedor debe ser una cuenta Busines, y la del comprador una cuenta Personal. Vea un ejemplo en la imagen de abajo:
Puede obtener más información descargando la quia del usuario del Sandbox desde el siguiente vínculo:
https://cms.paypal.com/cms_content/US/en_US/files/developer/PP_Sandbox_UserGuide.pdf
Utilizar IPN con el OLM desde una aplicación Delphi
La idea es poner un botón [Pagar Ahora] en el formulario de registración de la aplicación que al ser pulsado por el usuario lo redirija al sitio de PayPal para realizar el pago. Una vez realizado el pago PayPal envía automáticamente al Listener un mensaje instantaneo con toda la información relativa al pago realizado. Nuestro Listener es el script ipn.php que ubicamos en la carpeta del OLM de nuestro sitio. A continuación, ipn.php verifica la información recibida y modifica el registro correspondiente del OLM poniendo (Paid = Y) si la operación tiene el estado "Completed" o poniendo (Paid = P) si el estado es "Pending".
Después de realizado el pago y transcurridos algunos segundos, el usuario puede hacer click en el botón [Activate] para activar la aplicación. Vemos que este método es totalmente automático; no se necesita enviar el installcode al desarrollador y esperar que este le calcule el código de registración, el usuario simplemente realiza el pago y ya tiene su aplicación registrada. Además, ipn.php le enviará un email a Ud. con toda la información pertinente, en el caso de tener el estado "Pending", deberá verificar la operación en su cuenta de PayPal y cuando la operación quede completada debe ir al panel de control del OLM y editar el registro correspondiente poniendo (Paid = Y) para que el usuario después pueda activar la aplicación con el botón [Activate].
La mayoría de los pagos normales de PayPal tienen el estado "Completed", pero cuando opera con el Sandbox puede darse lo contrario, que la mayoría sea de estado "Pending".
El Ejemplo 1
En este ejemplo hemos colocado varios botones con distintos tipos de registración cada uno con su precio como se puede ver abajo:
Son cuatro los elementos que intervienen en el ejemplo:
1. La Aplicación Delphi
2. El script ipn.php (el listener) ubicado en la carpeta del OLM de nuestro sitio
3. El script prices.php ubicado en la carpeta del OLM de nuestro sitio
4. Un fichero texto con los precios para cada uno de los botones que ubicamos en a carpeta del OLM de nuestro sitio. Su nombre esta formado por el AppID con la extensión txt. Para nuestro caso '12310.txt'. De esta forma al cambiar este fichero se cambian los precios sin necesidad de tocar la aplicación. Este fichero puede ser creado con el Notepad de Windows o con el editor de texto plano que utilice habitualmente. Abajo puede ver el contenido del fichero 12310.txt de nuestro ejemplo utilizando el Notepad:
Los montos corresponden a las configuraciones para cada uno de los botones que hemos colocado. Cada vez que desee cambiar los precios debe editar este fichero y subirlo a la carpeta del OLM de su sitio reemplazando al existente.
Antes de explicar más detalles veamos en funcionamiento nuestro ejemplo, al correrlo por primera vez entraremos directamente al formulario de registración que se verá como la imagen de abajo:
Hagamos click en el botón [Start Trial] y veremos el resultado de la operación:
Después de iniciado el periodo trial, se podrán ver los botones de registración:
Ahora probemos con el boton [90 days]. El código utilizado es el siguiente:
procedure TRegForm.Btn90Click(Sender: TObject);
begin
Purchase(90,1,'TestApp 90 days registration');
end;
procedure TRegForm.Purchase(days,idx:integer;product:string);
begin
ShellExecute(0, 'open',
Pchar('https://www.sandbox.paypal.com/cgi-bin/webscr?business=alcide_1223630230_biz@valega.com'+
'¬ify_url=http://valega.com/olm51/ipn.php&cmd=_xclick&item_name='+product+
'&amount='+avfloat2str(prices[idx])+'¤cy_code=USD&item_number='+Form1.AVLock.InstallCode+'|'+
inttostr(Form1.AVLock.AppId)+'|'+inttostr(idx)+
'&custom='+inttostr(days)), nil, nil, SW_SHOWMAXIMIZED);
end;
Los parámetros tienen el siguiente significado:
days : Días del nuevo periodo a registrar (90 en el ejemplo)
idx : Indice (0 .. 4) del monto a utilizar, 1 en nuestro ejemplo que corresponde al monto 25.15 (ver fichero appid.txt).
product : Descripción del producto, en nuestro ejemplo 'TestApp 90 days registration'.
Los valores que se pasan al sitio PayPal son los siguientes:
1. La URL del servidor PayPal (En este caso el SandBox)
https://www.sandbox.paypal.com/cgi-bin/webscr
Note que después de hechas las pruebas con el SandBox, en la versión definitiva de su aplicación deberá reemplazar la URL del SandBox por la del sitio PayPal para transacciones reales https://www.paypal.com/cgi-bin/webscr
2. La dirección de email del vendedor
business=alcide_1223630230_biz@valega.com
3. La URL de nuestro Listener
¬ify_url=http://valega.com/olm51/ipn.php
4. El tipo de origen de la solicitud enviada a PayPal. En este caso desde un click a un botón.
cmd=_xclick
5. Nombre del Item (producto que se vende)
item_name='+product
en nuestro caso 'TestApp 90 days registration'
6. Monto de la operación
amount='+avfloat2str(prices[idx])
este código asigna a la variable amount el valor del precio correspondiente al indice idx dado, en nuestro caso 25.15. la función avfloat2str convierte el valor flotante del importe al formato con dos decimales, utilizando siempre el punto como separador decimal . No podemos utilizar aqui FormatFloat porque utiliza el separador decimal de la configuración de Windows que varía para cada país.
7. Codigo de la moneda utilizada
currency_code=USD
8. Número del Item. Utilizamos esta variable para pasar los tres valores necesarios que después utilizaremos en ipn.php para identificar el registro en el OLM. Estos tres valores son: el InstallCode, el AppID y el Indice del precio, separados por barras verticales '|' para poder extraerlos posteriormente en el script ipn.php:
item_number='+Form1.AVLock.InstallCode+'|'+inttostr(Form1.AVLock.AppId)+'|'+inttostr(idx)
9. Custom es una variable pass-through que permite al desarrollador pasar cualquier valor que considere conveniente, en este caso pasamos los días del periodo a ser registrado.
custom=90
Haciendo click en el botón [90 days] somos redirigidos al Sandbox de PayPal para realizar el pago:
Como email ingresamos nuestro email ficticio Personal del Sanbox con la password correspondiente y hacemos click en [Log In]. Pasamos a la siguiente pantalla:
Hacemos click en [Pay Now] y pasamos a la siguiente pantalla:
Ya se ha realizado el pago. Esperamos un minuto y vemos si llegó el email con la información enviada por ipn.php. La información recibida es la siguiente:
___________________________________________________________________
Payment received from User
TRANSACTION DETAILS
Transaction result: NO_ERROR
Total amount: 25.15 USD
Payment Type: instant
Payment status: Pending
Pending reason: paymentreview
Payment date: 19:13:34 Feb 09, 2011 PST
Transaction ID: 0BL35875YB607512V
Transaction Type: web_accept
Transaction Fee: 1.03
Total handling amount:
Total shipping amount:
Authorization amount:
Authorization expiration:
Authorization ID:
Authorization status:
Receiver Id: K3CEMHUWHBLC2
Receiver email: alcide_1222630237_biz@valega.com
Business: alcide_1222630237_biz@valega.com
Item name: TestApp 90 days registration
Item number: A2D0FB3CB909|12310|1
Verify sign: Aunr11ygbUpo21nDKjl6DT0GFOVqAoVEU3KPLYYcT36q0kgWm5BsS1wx
Transaction subject: 90
Custom: 90
PAYER DETAILS
First name:
Last name: User
Address city: San Jose
Address country: United States
Residence country: US
Address state: CA
Address status: confirmed
Address street: 1 Main St
Address zip: 95131
Address name: Test User
Payer ID: D8QJ77BWFW94W
Payer status: verified
Payer email: alcid_1296531902_per@valega.com
MEMO:
___________________________________________________________________
Veamos como quedó el registro correspondiente en el OLM:
Notamos los campos (Days = 90) que son los días del nuevo periodo a activar, (Paid = P) que indica que por alguna razón el pago no se ha completado y está pendiente de revisión y Other que contiene los campos más importantes de la transacción.
A continuación entramos al panel de control del OLM http://av-soft.com/olm51/s5cp.com y editamos el registro correspondiente asignandop (Paid = Y) a fin de que el usuario pueda activar el nuevo periodo. Seleccionamos la opción correspondiente como se muestra en la imagen se abajo y hacemos click sobre el botón [Save Record].
Después de esto el usuario ya está en condiciones de activar el nuevo periodo. Vayamos nuevamente a la aplicación ejemplo y hagamos click sobre el botón [Activate].
Después de recibir el mensaje 'Registration activated' vemos que cambia el estado de registración, ahora tenemos "Temporal 120 days - 120 days left". Que ha pasado?, acaso no iniciamos un nuevo periodo de 90 días?
Lo que sucede es que utilizamos el método OnlineRenew2() para activar el nuevo periodo. Hay tres formas distintas de activar el nuevo periodo:
1. Utilizando el método OnlineRenew(). De esta manera se inicia un nuevo periodo de acuerdo a lo especificado sin rescatar los dias restantes del periodo anterior. En este caso el resultado hubiese sido "Temporal 90 days - 90 days left".
2. Utilizando el método OnlineRenew2(). De esta manera a los días del nuevo periodo se le suman los días restantes del periodo anterior (en este caso los 30 días del periodo trial), asi obtuvimos el resultado (30+90)=120 "Temporal 120 days - 120 days left".
3. Esta opción que también utiliza OnlineRenew() no permite que el usuario active el nuevo periodo antes de haber consumido totalmente el anterior, asi que en este caso deberá esperar los 30 días restantes para recién entonces iniciar el nuevo periodo de 90 días. El código utilizado es el siguiente:
if (keydata.KeyType = Trial) then AVLock.OnlineRenew(0)
else if (keydata.KeyType = Temporal) then
begin
if (keydata.DaysLeft = 0) or (keydata.Status = expired)
then begin
res:=AVLock.OnlineRenew(0);
end else showmessage('You have '+inttostr(keydata.DaysLeft)+' days remaining '+
'on your actual period, so please press this button when the current period expires');
end;
Para más información vea la sección (Usando AVLock SIMPLE > Conceptos Básicos > "Como registrar la aplicación mediante el OLM".
Algunos detalles adicionales
Como hemos visto los precios están guardados en el fichero appid.txt (12310.txt del ejemplo). Estos precios de leen desde la aplicación delphi utilizando el script prices.php. El código utilizado en el ejemplo es el siguiente:
procedure TRegForm.GetPrices;
var phpfile,postdata,s:string;
arr:tarrstr;
i:integer;
begin
with Form1 do begin
for i:=0 to 4 do prices[i]:=0;
phpfile := avlock.OlmPath+ '/prices.php';
postdata := inttostr(AVLock.AppID);
s := trim(OnlineRequest(phpfile, postdata, avlock.EncryptionKey2, avlock.WebHost));
arr := explode('|', s, 0);
for i:=0 to (length(arr)-1) do begin
if avisnum(arr[i]) then prices[i]:=avstr2float(arr[i]);
end;
end;
end;
el precio del item y el indice (posición dentro de la lista) son pasados a PayPal a través de la solicitud de pago y reenviados al script ipn.php a través del mensaje IPN que le envía PayPal después de realizada la operación.
Además dentro del script ipn.php se vuelve a obtener el precio leyendo el fichero appid.txt (12310.txt en nuestro ejemplo) y el valor obtenido se compara con el recibido desde PayPal con el mensaje IPN y si no coinciden se aborta la operación y el email recibido tendrá el mensaje de error correspondiente: "AMOUNT MISMATCH".
La nueva versión del RegMonitor permite ver los datos de la transacción guardados en el campo Other como campos separados (uno por linea), como se ve en la imagen abajo:
El Ejemplo 2
Este ejemplo implementa cupones de descuento. El formulario de registración en lugar de botones para las opciones utiliza botones de radio.
Para cada cupon se debe crear un fichero con el nombre del cupon y extension txt. El contenido de este fichero es un codigo que determina la acción a tomar. Se pueden crear dos clases de cupones; de descuento y de registración sin costo. Abajo se describen algunos archivos ejemplo que hemos implementado y están alojados en http://av-soft.com/olm51
Cupon Fichero Contenido Acción a aplicar
------ ---------- --------- -----------------
AX125C AX125C.txt F365 Registración gratuita por 365 días
NM12RA NM12RA.txt P25 Descuento del 25%
451KLJ 451KLJ.txt P50 Descuento del 25%
Junto con los ficheros del ejemplo se incluyen los ficheros de los cupones. Recuerde que para que tengan efecto deben colocarse en la carpeta del OLM.
Vemos como al aplicar el cupon NM12RA (contenido P25) los precios se reducen un 25%
Abajo podemos ver como al aplicar el cupon AX125C (contenido F365) la aplicación se registra automáticamente por un periodo de 365 días. Vemos que al codificar el cupon ponemos 'P' para aplicar descuentos y 'F' para registración gratuita. Cuando se pone 'P' el numero determina el porcentaje de descuento a aplicar y cuando se usa 'F' el numero determina la cantidad de días a registrar en forma gratuita.
Cuando se utiliza un cupón 'F' no hace falta activar ya que este proceso se hace automáticamente, lo único que hay que hacer es ingresar el cupon y hacer click en [Apply].
Cuando se utiliza un cupón 'P', al hacer click en [Apply] se reducen los precios a pagar. Después hay que realizar el pago con [Pay Now] y activar con [Activate] como lo hicimos en el ejemplo 1.
| 
