Using PayPal’s PayFlowPro to Achieve Recurring Billing

• Download tutorial files - 69.38 KB

Introduction

Have you ever come across a client who needed to not only accept credit cards over the Web, but to do so in a fashion that allowed for recurring processing? For the sake of this white paper, let’s also assume that your client does not want users to have to leave their site at any time during the payment processing. How do you achieve this? Well, PayPal has introduced a powerful product called PayFlowPro (PFP), which with some customization will achieve exactly the results you are looking for! This white paper will demonstrate how to set up recurring billing with PayFlowPro.

Of course, the first step is to set up a business account with PayPal in addition to creating an Internet Merchant Account which will allow you to work with PFP. These tasks are beyond the scope of this white paper and this article assumes that these items have already been established. For more information on this, please visit PayPal.

When the accounts are established, the next step is to download the PayFlowPro SDK from PayPal and install it. Once installed and properly referenced in your Web project, you are ready to begin your adventure into getting your site customized to work with PFP!

The way that PFP manages recurring billing is through a vehicle called Profiles. For each customer that you wish to bill on a recurring basis, you will be required to create a Profile. On most sites, this would be done at the initial time of billing.

This paper also assumes that you have some working knowledge of the Invoice, Card, Bill and Ship objects. These are not discussed in this paper, but are shown in the code sample at the end. Please see the PFP documentation if you need more information on these objects.

To create a PayPal profile, you use an object of type RecurringInfo from the PFP SDK. After creating an instance of the object, you need to set some very key properties:

• Start
• ProfileName
• PayPeriod
• Term
• OptionalTrx
• OptionalTrxAmount

Let’s cover each of these in more detail.

Start Property

This property reflects the date that the first payment will be processed. The important thing to note on this property is that the date must be greater than the current date and it must also be formatted as mmddyyyy. In most cases, this date value will represent the next date upon which you want the recurring billing to begin. Now, you may be asking what about current charges? We will cover this when we get to the OptionalTrx property.

For example, let’s say that we are developing a site that will allow you to read a newspaper or a magazine online and they have decided that you will be charged $7.95 per month on a recurring basis. In this case, the initial payment would be due up front and this will be covered in the optionaTrx property below, but for the sake of argument, let's say that today is the first of October. You would then set this property to equal November 1st, since that’s the day that the recurring billing will actually begin. The value would be 11012008.

ProfileName

This property is used to give the profile that you are about to create a human readable name for reference within PayPal’s Web based management tool called PayPalManager. This field is a text string and can be any value that you wish, but I would strongly recommend using something that makes sense, like the customer's first and last name. This is important because when you use PayPalManager to view the profiles created, this is how the manager loads the profiles – by Profile name. So, continuing our sample from above, let’s set this to a value of Bush, George.

PayPeriod

This property represents the frequency at which the recurring charges are to occur. It is also a text string and sample values include WEEK, MONTH, SMYR, QTER, etc. For our sample, we will be using a value of MONTH.

Term

This property describes the total number of payments to process. Use 0 to process indefinitely (or at least until the customer cancels his contract!).

OptionalTrx

This property represents whether or not we wish to process an optional transaction with the profile when we create it. The field is important because it can serve two purposes: the first is to bill the customer for the initial period if desired. In our sample here, we are not going to give away a free trial, so this is where we tell PayPal that we wish to bill $7.95 today. We set the value of this to S to denote Sale.
The second use for this property is that perhaps you wish to give users a free trial, but you want to make sure that the credit card they enter is valid, well, here is where you can do that by setting this value to A for Authorization.

Regardless of how you use this field, if you use this field, the amount you wish to process or authorize is set in the OptionalTRXAmount property described next.

OptionalTRXAmount

This property is exactly as it sounds – the dollar amount of the sale or authorization that you wish to perform when creating the profile. Generally for authorizations, you would use $1.00 and of course, if you are doing a sale, the amount is equal to whatever the sale price is. So, for our example, we would enter 7.95. There is one important thing to mention about this property – the value is of type Currency within the PFP object library, so you need to create a Currency type and set the amount within the object.

After you have set the all the necessary properties for the various objects, it’s time to submit the transaction to PayPal and have our profile created! To do this, we simply create an instance of the RecurAddTransaction object and an instance of the Response object and set it equal to the SubmitTransacton method of the RecurAddTransaction object.

Return Codes

After we submit the transaction to PayPal, we need to wait for the response to come back. When the call returns, we need to examine the response object to determine if our profile was created and to ensure that our optional transaction was (hopefully) approved. You can find more information on the various return codes from the PFP documentation; however you will note that a result code of 0 indicates a successful transaction. Please see the code routine at the end of this article.

In our case, we can see via the PayPal Manager site that our new profile was in fact created, and this customer is ready to be billed on a recurring basis until we cancel the account.

The transaction looks like this:

Modify, Inquire, etc.

The PFP SDK provides objects to handle all sorts of transactions dealing with recurring payments and profiles. The ability to modify and inquire is all present, but beyond the scope of this white paper. For further information on these objects, please see the documentation.

Conclusion

With seamless integration in .NET, PayFlowPro offers a simple, yet extremely powerful way to manage recurring billing and credit card processing for .NET based Internet (or Windows Forms) applications all the while never having to require your users to leave your site.

Code

public int AddUpdateProfileWithTransaction()
{
    PayflowConnectionData Connection = new PayflowConnectionData();UserInfo User = 
        new UserInfo("<user>", "<vendor>", "<partner>", "<password>");
    // Create InvoiceInvoice Inv = new Invoice();
    // Set Amount
    Currency Amt = new Currency(new decimal(7.95), "USD");
    Inv.Amt = Amt;Inv.InvNum = "xxxxx";

    // Create and set Bill To Info
    BillTo Bill = new BillTo();
    Bill.Street = "1600 Pennsylvania Ave.";
    Bill.Zip = "20006";Bill.City = "Washington";
    Bill.State = "DC";Bill.FirstName = "George";
    Bill.LastName = "Bush";Bill.BillToCountry = "US";
    Bill.Email = "president@whitehouse.gov";

    Inv.BillTo = Bill;

    PayPal.Payments.DataObjects.CreditCard CC = 
        new PayPal.Payments.DataObjects.CreditCard
        ("5105555555550155", string.Format("{0}{1}","05","09"));
    CC.Cvv2 = "123";

    // Create a new Tender - Card Tender data object.
    CardTender Card = new CardTender(CC);

    RecurringInfo RecurInfo = new RecurringInfo();
    
    // The date that the first payment will be processed. 
    // Note - this value must be greater
    // than the current date! We will charge the customer 
    // for the first month in a sep. Transaction
    // Format must be mmddyyyyDateTime StartBilling = DateTime.Now.AddMonths(1);

    RecurInfo.Start = StartBilling.ToString("MMddyyyy");
    RecurInfo.ProfileName = string.Format("{0}, {1}", "Bush" , "George");
    // Specifies how often the payment occurs. All PAYPERIOD values must use 
    // capital letters and can be any of WEEK / BIWK / SMMO / FRWK / MONT / 
    // QTER / SMYR / YEAR
    RecurInfo.PayPeriod = "MONT";
    RecurInfo.Term = 0; // Number of payments 0 = indef.

    // Perform an Optional Transaction. Verify that we need to do this!!
    RecurInfo.OptionalTrx = "S"; // S = Sale, A = Authorization

    // Set the amount if doing a "Sale" for the Optional Transaction.
    Currency oTrxAmt = new Currency(new decimal(7.95), "USD");
    RecurInfo.OptionalTrxAmt = oTrxAmt;

    // Create a new Recurring Add Transaction.
    RecurringAddTransaction Trans = new RecurringAddTransaction(
    User, Connection, Inv, Card, RecurInfo, PayflowUtility.RequestId);

    // Submit the Transaction
    Response Resp = Trans.SubmitTransaction();

    // Return the transaction response parameters.
    if (Resp != null)
    {
        // Get the Transaction Response parameters.
        TransactionResponse TrxnResponse = Resp.TransactionResponse;

        // Get the Recurring Response parameters.
        RecurringResponse RecurResponse = Resp.RecurringResponse;

        if ((TrxnResponse != null) && (RecurResponse != null))
        {
            if (TrxnResponse.Result == 0)
            {
                // Return the ProfileID if desired
                // ProfileID = RecurResponse.ProfileId;
                return 0; //Success!!!
            }
            else
            {
                try
                {
                    int RetCode = int.Parse(RecurResponse.TrxResult);
                    return RetCode; 
                }
                catch (Exception)
                {
                    return TrxnResponse.Result;
                }
            }
        }    
        else
        {
            _TransactionID = "";
            return -1;
        }
    }    
    else
    {
        _TransactionID = "";
        return -1;
    }
}

About the Author

Andrew Schmidt is a consultant with Custom Software by Preston. He has over 10 years of software development experience in a range of industries including manufacturing, government, health care, and telecommunications. He has developed enterprise systems that integrate with PayPal and other card processing systems. He resides in Chicago with his wife and 1 year old son and can be reached via email at andy@customsoftwarebypreston.com or at Custom Software by Preston.