The PayPal payment gateway and 4D Business Kit 2.2

Transcription

1 The PayPal payment gateway and 4D Business Kit 2.2 Useful informations This document describes how to integrate 4D Business Kit 2.2 with the PayPal payment gateway. In this documentation, we suppose that the owner of the TEST shop has a PayPal merchant account whose login is: merchant@shop.com. You will need to replace this login by your own PayPal merchant account in the example pages. NB: For a PayPal account to receive payment with credit cards, the PayPal account needs to be a Premier or Business account. PayPal gives some documentation about its payment gateway. Two manuals are used here. 1. The PayPal Shopping Cart Manual In this manual, we use the following chapter: Add PayPal Checkout to Your 3 rd Party Cart. Method 1. Passing the Aggregate Cart Amount to PayPal. 2. The PayPal Instant Payment Notification (IPN) Manual Part I: Add PayPal Checkout to 4D Business Kit According to The PayPal Shopping Cart Manual: You may aggregate your entire shopping cart and pass the total amount into PayPal s Buy Now Code (that is, you will need to post a single name for the entire cart and the total price of the cart s contents as though it were a purchase of a single item). 4D Business Kit provides an example page called payment_paypal.htm (NB: This page is linked to the TEST shop). This page describes a way to pass information to PayPal through an html form. Content of the payment_paypal.htm html page:

2    <form method="post" action="  <input type=hidden name="cmd" value="_ext-enter"> <input type=hidden name="redirect_cmd" value="_xclick"> <input type=hidden name="business" value=""> <input type=hidden name="item_name" value=""> <input type=hidden name="amount" value=""> <input type=hidden name="currency_code" value=""> <input type=hidden name="return" value=" >/Test_Site/WebPagesUS/home.htm"> <input type=hidden name="item_number" value=""> <input type=hidden name="custom" value=""> <input type=hidden name="notify_url" value=" >/4daction/4DBKHttpPostCallBack/custom/payment_PayPal_cb.htm/1">  <input type=hidden name=" " value=""> <input type=hidden name="first_name" value=""> <input type=hidden name="address2" value=""> <input type=hidden name="city" value=""> <input type=hidden name="state" value=""> <input type=hidden name="zip" value=""> <input type=hidden name="night_phone_a" value=""> <input type=hidden name="night_phone_b" value=""> <input type=hidden name="night_phone_c" value=""> <input type=image" src=" name="submit" alt="make payment with PayPal - it's fast, free and secure!" > </form> Explanations about the hidden fields used in this form: Some parameters are required for the payment gateway, they are: - business : address on your PayPal account. - Item_name : this will be the name for the whole shopping Cart (127 characters limit). Here we are using a summary of our shopping cart but we could also use the number of the order to avoid the 127 characters limitation. - amount : this will be the total price of all items in the Shopping Cart. - image : The image for the button your buyer will press to initiate the PayPal payment process. You can substitute your own image by replacing the src with the URL of your image. Others additional parameters used by 4D Business Kit: - custom: Described in in the PayPal Shopping Cart Manual as an Optional passthrough variable that will never be presented to your customer. 256-character limit. In fact, we need to use a custom field in order to store the client s session

3 ID. This way, the gateway will send us back this session ID with the result of the transaction and we will be able to acknowledge the payment. - return : the internet URL where your customer will be returned after completing payment. - notify_url: This hidden field allows to set a call-back URL. This URL will be used by PayPal to warn 4D Business Kit of the result of a transaction through PayPal Instant Payment Notification process. - item_number: we use this field to store the number of the order in 4D Business Kit The callback URL used by PayPal to send the result of the transaction is: >/4daction/4DBKHttpPostCallBack/custom/payment_PayPal_cb.htm/1 About parameters used with the 4DBKHttpPostCallBack entry point: - «custom» : this is the name of the field posted by the payment gateway in which the session ID is stored. - «payment_paypal_cb.htm» : this is the name of the script that will be triggered by the 4DBKHttpPostCallBack entry point. - «1» : this parameter means that 4D Business Kit will create a debug file associated to the excution of the script. This file will be found in a subfolder Gateway of the Logs folder of the current site. Part II : Use PayPal Instant Payment Notification According to PayPal Instant Payment Notification Manual (IPN): Instant Payment Notification allows you to integrate your PayPal payments with your website s back-end operations, so you get immediate notification and authentication of the PayPal payments you receive. Content of the script payment_paypal_cb.htm which is the target of PayPal Instant Payment Notification   payment_status:  txn_id:  receiver_   mc_gross:  mc_currency:  item_name:  item_number:  Full POST sent by the IPN:  Modified POST:

4 We have to confirm to PayPal that 4DBK has received the Instant Payment Notification by constructing an HTTP POST  PAYPAL RESPONSE :   Order Code (has to be the same as item_number):  Total amount of the order (has to be the same as mc_gross):       ORDER VALIDATED   ITEM NUMBER IS NOT CORRECT PRICE IS NOT CORRECT FOR THE ORDER Receiver_ is not correct Payment_status is not completed INVALID ANSWER Explanations about what is done in this script file: First, we use the 4DBKHttpPostParms command to get the value of some of the fields send by the payment gateway through its POST. The value of those fields are mandatory to do some checking before validating the order. According to PayPal Instant Payment Notification Manual (IPN), here is what is to be done after our server has received the Instant Payment Notification: Once your server has received the Instant Payment Notification, you will need to confirm it by constructing an HTTP POST to PayPal. Your POST should be sent to You must post all of the form variables you received exactly as you received them. You will also need to append a variable named cmd with the value _notifyvalidate (e.g. cmd=_notify-validate) to the POST string. PayPal will respond to the post with a single word, VERIFIED or INVALID, in the body of the response. In our script, the 4DBKHttpPostParms command allows us to get the whole POST coming from PayPal

5 We use the 4DBKScriptProcess command to post-back the IPN data. This command will execute an HTTP request depending on what has been specified in the parameter script file US_PayPal.txt. In this script file we will trigger 4D Business Kit to do a POST in secured mode at the following addres: The content of this POST will be specified through the arg1 parameter which store the original modified POST. Content of the script file US_PayPal.txt ####################################### # Payment gateway script for 4D Business Kit # # PayPal # ####################################### # 4DBKScriptText returns "VERIFIED" or "INVALID" # definition [platform=]win # how to send the request [mode=]http [host=] [port=]443 # end of request : if one of these string is found (PayPal does not use Content-Length) [erx=]verified [erx2=]invalid # result processing [res_start=] [res_offset=] [res_end=] # fields processing [res_fields=][crlf] [res_code1=] [res_code2=] [res_text=]11 [res_tid=] # the request to send [req=]post /cgi-bin/webscr HTTP/1.1[crlf] Host: Content-type: application/x-www-form-urlencoded[crlf] Content-length: [length][crlf][crlf] [arg1] After the 4DBKScriptProcess command has executed, the 4DBKScriptText variable will contain PayPal response: either VERIFIED or INVALID. When a VERIFIED response is received, the following checks are performed: - We Check that the payment_status is Completed. - We make sure the receiver_ is an address registered in our PayPal account.

6 - We Check that the price ( mc_gross ) and item ( item_number ) are correct for the order. As soon as those checks are validated, we can validate the order.