PayPal Package

The Morfik PayPal package contains a single widget (BuyNow button) and a number of supporting classes that provide a thorough implementation of the PayPal Express Checkout API. To use this widget for live payments, a PayPal Merchant Account is required; for testing transactions a developer account is required.


package-view.png
package-down.png


A quick walkthrough

To use the Morfik PayPal package simply add the package to the project by utilizing the “Used Packages” command on the project ribbon (see Figure 1 Used Packages Command), or simply drag the package file onto the application main client area. Once added two widgets will appear on the home ribbon when the form designer is active (see Figure 2 Widget Gallery). These widgets can be placed on application forms and provide immediate functionality with minimal coding.


security-fig1.png
Figure 1: Used Packages Command


The quickest way to utilize this package is to place the BuyNow button on your purchase form and set the properties discussed below.


pp.PNG
Figure 1: Widget Gallery


To use the package, you will first need to initialize the PayPal Express Checkout Manager on the server side (the XApp OnStart event is recommended) and include the mfk_ppServices unit.


FX Code

Uses mfk_ppServices;
...
Procedure sampleXApp.XAppStart(Sender: TObject);
Begin
    InitializePayPalExpressCheckoutManager(‘Api Username’, ‘Api Password’, ‘Api Signature’);
End;


The Api Username, Api password and Api Signature can be obtained by creating a PayPal Sandbox test account (https://developer.paypal.com/cgi-bin/devscr?cmd=_). The account information needs to be set before a submitting any PayPal transaction for processing.


PayPal BuyNow Button Widget

Drop a mfk_ppBuyNowBtn widget on a form and set the following properties: Amount, Cancel URL, Currency Code, Mode (Sandbox), Payment Action and Return URL (for parameters, see below). You can then run the application and click on the Buy Now button.

To understand the Express Checkout process, take a look at the steps and events as they will occur.

  • BuyNow button is clicked
  • OnPrepareForCheckout (browser) event called
  • PayPal SetExpressCheckout request API called and return values received
  • OnBeforeCheckout (browser) event called
  • Browser directed to PayPal login page *
  • Purchase Approved or Cancelled in PayPal site *
  • OnAfterCheckout (server) event called
  • If customer agreed, browser is redirected to Return URL
  • If customer didn’t agree, browser is redirected to Cancel URL


Note: * indicates steps that take place when the browser is redirected to the PayPal website


The following design-time properties of the BuyNow widget should be set before processing the transaction:

Amount (optional): If you have a fixed amount the customer will be billed, you can enter it in this field at design-time. If not, the amount will have to be set later in the PrepareForCheckout event. The amount should include two digits following the decimal point (which must be a period). You can refer to the Amt property in the documentation at https://www.x.com/docs/DOC-1208.

Return URL: The URL that the browser will be directed to after successfully completing the PayPal transaction. You can use this page to display information about the completed transaction (see Result in URL property).

Cancel URL: The URL that the browser will be directed to after cancelling the PayPal option (see Result in URL property). Button Type: Determines the image that will be displayed for the button. Options are: Buy Now, Donate, Buy Gift Certificate and Subscribe.

Currency Code: Select the PayPal currency type that will be used for the transaction.

Description: A description that will appear in the merchant’s log for the transaction.

Mode: Select whether the transaction is a test (Sandbox) transaction or a Live transaction.

Payment Action: Select from the three available action types: Sale (default), Authorization or Order.

Result in Url Parameter: When set to True, the Return Url and Cancel Url will receive detailed transaction information in a parameter (‘Response’ if successfully processed; ‘Error otherwise). The parameter is a string that contains a comma-delimited list of name-value pairs that are URI encoded. See note regarding AutoSum below.

Events

Procedure PrepareForCheckout(Sender: TObject; DOMEvent: TDOMEvent; PaypalExpressCheckoutClient: TPaypalExpressCheckoutClient);

The PaypalExpressCheckoutClient can be used to provide details of the transaction before it is submitted to PayPal. If the Amount was not specified at design time, then it must be specified in this event. Refer to the description of the TPaypalExpressCheckoutClient class below. After this event is called, the PayPal SetExpressCheckout API is called.

Procedure BeforeCheckout (Sender: TObject; ExpressCheckoutDetails: String; SetExpressCheckoutSuccess: Boolean; ErrorMessage, LoginURL: String);

This event is raised after completion of the call to the SetExpressCheckout API. The ExpressCheckoutDetails will contain a string similar to ‘TOKEN=EC-4FL305211D756151T,TIMESTAMP=2010-04-27T00:13:04Z,CORRELATIONID=36b3b4d2876d,ACK=Success,VERSION=61.0,BUILD=1268624,"STATUS=HTTP/1.1 200 OK"’. The SetExpressCheckoutSuccess will contain True if the call was successful but the finalization of the purchase can be cancelled by setting this parameter to False. If unsuccessful, the ErrorMessage parameter will contain information on why the API call failed. Finally the LoginURL contains the address that will be called for the PayPal login page. If you need to add any parameters to the loginURL, you may do so here.

AfterCheckout (Procedure AfterCheckoutEvent(Success: Boolean; Token: String; CheckoutDetails: TStringList);)

This event occurs after the PayPal transaction is finalized and could be used, for example, to log transactions to a database. This is a server-side event and cannot be assigned in the property inspector but can be assigned in code. Below is a sample of code in a server-side module:

FX Code

Unit ModAfterCheckout;
Interface
Uses SystemClasses, mfk_ppServices;
Procedure AfterCheckoutEvent(Success: Boolean; Token: String; CheckoutDetails: TStringList);
Implementation
Procedure AfterCheckoutEvent(Success: Boolean; Token: String; CheckoutDetails: TStringList);
Begin
    DebugOut(Token + ':' + CheckoutDetails.Text);
End;


The event could then be assigned in the XApp OnStart event:

FX Code

AfterCheckout := AfterCheckoutEvent;


Note: AutoSum is a property that is turned on by default and controls whether the Amount is calculated (when AutoSum is True) or must be specified otherwise.


To turn off AutoSum in the BuyNow widget, do so using the following code in the PrepareForCheckout event:

FX Code

PaypalExpressCheckoutClient.AutoSumEnabled := False;


AutoSum uses the following formulas when enabled: Amt = ItemAmt + TaxAmt + ShippingAmt + HandlingAmt + InsuranceAmt + ShippingDiscount. MaxAmt = Amt + GiftwrapAmount


Discussion of Classes

TPaypalExpressCheckoutClient

This class contains the AutoSum property discussed above and the important SetExpressCheckOutRequest property which should be used to configure the transaction during the PrepareForCheckout event if it cannot be set at design-time. For example, to specify the total amount of the transaction, use the PaymentDetails property of the SetExpressCheckoutRequest to set the field Amt (see AutoSum note), as shown below:

FX Code

PaypalExpressCheckoutClient.SetExpressCheckOutRequest.PaymentDetails.Amt := 100;


And to specify the shipping charges, use:

FX Code

PaypalExpressCheckoutClient.SetExpressCheckOutRequest.PaymentDetails.ShippingAmt := 19.95;


The complete TSetExpressCheckoutRequest and TPaymentDetails classes are well documented in comments in the mfk_ppServices unit.

Complete documentation on the PayPal API’s can be found on the PayPal Developer Network web site https://www.x.com/. You can find PayPal Express Checkout documentation at https://www.x.com/docs/DOC-1122 and Direct Payment documentation at https://www.x.com/docs/DOC-1308 .

Information on debugging

The complete PayPal ExpressCheckout process cannot be run entirely in the debugger due to the implementation of the PayPal sandbox. Debugging on the browser side is possible up until the PayPal login screen appears. The server side can be debugged using a different browser, for example: Launch a browser (say IE) and log in to the sandbox test account you will be using. Run the Morfik application and from the debug browser launch the same browser (IE). You will be able to log in to complete the test transaction.


See Also

Back to top