The PayPal payment gateway and 4D Business Kit 2.2

(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:

[email protected]

.

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

https://www.paypal.com/en_US/pdf/shopping_cart.pdf

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

https://www.paypal.com/en_US/pdf/ipn.pdf

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)

 

<input type=hidden name="business" value=""> <input type=hidden name="item_name" value=""> <inputtype=hidden name="amount" value=""> <inputtype=hidden name="currency_code" value=""> <inputtype=hidden name="return" value="http:///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="http:///4daction/4DBKHttpPostCallBack/custom/payment_PayPal_cb.htm/1">

<inputtype=image" src="http://images.paypal.com/images/x-click-but01.gif" 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

: Email 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

pass-through 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:

http://<!--#

4DBKField

/Host-->/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_email:

 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_email 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

https://www.paypal.com/cgi-bin/webscr

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:

www.paypal.com/cgi-bin/webscr

. 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=]www.paypal.com [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: www.paypal.com[crlf]

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_email” is an email address registered in our PayPal

account.

(6)