1. Introduction

2. Types of PayPal payments

3. Payment process

3.1 "One-click" shopping

A code of the simplest form:

<form method="post" action= "https://www.paypal.com/cgi-bin/webscr">
    <input type="hidden" name="cmd" value="_xclick">
    <input type="hidden" name="business" value="my@email.com">
    <input type="hidden" name="item_name" value="Item name">
    <input type="hidden" name="item_number" value="1234">
    <input type="hidden" name="amount" value="19.95">
    <input type="hidden" name="no_shipping" value="1">
    <input type="submit" value="Buy Now">
</form>

Description of main parameters

4. IPN

  The received POST variables contain transaction information. The most widely used variables are the following:

5. An example of IPN processing

<Goods>
    <Good id="0" name="Sample of good" price="10.99" /> 
</Goods>

Where...

• id is a unique item identifier;
• name is the item name;
• price is the item price.

<Carts>
    <Cart rec_id="0" cart_id="1" item_id="0" price="10.99" quantity="1" /> 
</Carts>

Where...

• rec_id is a unique record identifier;
• cart_id is an identifier of the cart that contains this item;
• id is an item identifier;
• price is the item price;
• quantity is the quantity of ordered items.

<Requests>
    <Request request_id="0" cart_id="1" price="10.99" 
        request_date="5/28/2007 1:15:18 PM" /> 
</Requests>

Where...

• request_id is a unique request identifier;
• cart_id is an identifier of the cart being paid;
• price is the cost of goods;
• request_date is the date and the time when the request is created.

<Responses>
    <Response   payment_id="0" 
                txn_id="3PP58082BD3079037"
                payment_date="5/28/2007 1:22:40 PM"
                payment_price="10.99"
                email= my@email.com 
                first_name=""
                last_name=""
                street=""
                city=""
                state=""
                zip=""
                country=""
                request_id="0"
                is_success="True"
                reason_fault="" 
    /> 
</Responses>

Where...

• payment_id is a unique payment identifier;
• txn_id is the unique number of the PayPal transaction;
• payment_date is the date and time when payment is performed;
• payment_price is the payment amount;
• email is the buyer's e-mail;
• first_name is the buyer's first name;
• last_name is the buyer's last name;
• street is the buyer's street;
• city is the buyer's city;
• state is the buyer's state;
• zip is the buyer's ZIP code;
• country is the buyer's country;
• request_id is an identifier of payment request;
• is_success indicates whether the payment was successfully performed;
• reason_fault is a possible reason of payment failure.

<form id="payForm" method="post" action="<%Response.Write (URL)%>">
      <input type="hidden" name="cmd" value="<%Response.Write (cmd)%>">
      <input type="hidden" name="business" 
          value="<%Response.Write (business)%>">
      <input type="hidden" name="item_name" 
          value="<%Response.Write (item_name)%>">
      <input type="hidden" name="amount" value="<%Response.Write (amount)%>">
      <input type="hidden" name="no_shipping" 
          value="<%Response.Write (no_shipping)%>">
      <input type="hidden" name="return" 
          value="<%Response.Write (return_url)%>">
      <input type="hidden" name="rm" value="<%Response.Write (rm)%>">
      <input type="hidden" name="notify_url" 
          value="<%Response.Write (notify_url)%>">
      <input type="hidden" name="cancel_return" 
          value="<%Response.Write (cancel_url)%>">
      <input type="hidden" name="currency_code" 
          value="<%Response.Write (currency_code)%>">
      <input type="hidden" name="custom" 
          value="<%Response.Write (request_id)%>">
</form>

Where...

• URL is the URL to work with, depending on whether sandbox or a real PayPal account should be used;
• cmd is a command that is sent to PayPal;
• business is the seller's e-mail;
• item_name is the item name -- i.e. what buyer pays for -- that will be shown to user;
• amount is the payment amount;
• no_shipping is a parameter that determines whether the delivery address should be requested;
• return_url is the URL that the buyer will be redirected to when payment is successfully performed;
• rm is a parameter that determines the way in which information about a successfully finished transaction will be sent to the script specified in the return parameter;
• notify_url is the URL PayPal will send information about transaction (IPN) to;
• cancel_url is the URL that the buyer is redirected to when he cancels payment;
• currency_code is the currency code;
• request_id is an identifier of payment request.

    private void Page_Load(object sender, EventArgs e)
    {
        string requestUriString;
        CultureInfo provider = new CultureInfo("en-us");
        string requestsFile = this.Server.MapPath(
            "~/App_Data/PaymentRequests.xml");
        requests.Clear();
        if (System.IO.File.Exists(requestsFile))
        {
            requests.ReadXml(requestsFile);
        }
        else
        {
            Carts.CreateXml(requestsFile, "Requests");
            requests.ReadXml(requestsFile);
        }
        string responseFile = this.Server.MapPath(
            "~/App_Data/PaymentResponses.xml");
        responses.Clear();
        if (System.IO.File.Exists(responseFile))
        {
            responses.ReadXml(responseFile);
        }
        else
        {
            Carts.CreateXml(responseFile, "Responses");
            responses.ReadXml(responseFile);
        }
        string strFormValues = Encoding.ASCII.GetString(
            this.Request.BinaryRead(this.Request.ContentLength));

        // getting the URL to work with
        if (String.Compare(
            ConfigurationManager.AppSettings["UseSandbox"].ToString(),
            "true", false) == 0)
        {
            requestUriString = 
                "https://www.sandbox.paypal.com/cgi-bin/webscr";
        }
        else
        {
            requestUriString = "https://www.paypal.com/cgi-bin/webscr";
        }

        // Create the request back
        HttpWebRequest request = 
            (HttpWebRequest)WebRequest.Create(requestUriString);

        // Set values for the request back
        request.Method = "POST";
        request.ContentType = "application/x-www-form-urlencoded";
        string obj2 = strFormValues + "&cmd=_notify-validate";
        request.ContentLength = obj2.Length;

        // Write the request back IPN strings
        StreamWriter writer = 
            new StreamWriter(request.GetRequestStream(), Encoding.ASCII);
        writer.Write(RuntimeHelpers.GetObjectValue(obj2));
        writer.Close();

        //send the request, read the response
        HttpWebResponse response = (HttpWebResponse)request.GetResponse();
        Stream responseStream = response.GetResponseStream();
        Encoding encoding = Encoding.GetEncoding("utf-8");
        StreamReader reader = new StreamReader(responseStream, encoding);

        // Reads 256 characters at a time.
        char[] buffer = new char[0x101];
        int length = reader.Read(buffer, 0, 0x100);
        while (length > 0)
        {
            // Dumps the 256 characters to a string
            string requestPrice;
            string IPNResponse = new string(buffer, 0, length);
            length = reader.Read(buffer, 0, 0x100);
            try
            {
                // getting the total cost of the goods in 
                // cart for an identifier
                // of the request stored in the "custom" variable
                requestPrice = 
                    GetRequestPrice(this.Request["custom"].ToString());
                if (String.Compare(requestPrice, "", false) == 0)
                {
                    Carts.WriteFile("Error in IPNHandler: amount = \");
                    reader.Close();
                    response.Close();
                    return;
                }
            }
            catch (Exception exception)
            {
                Carts.WriteFile("Error in IPNHandler: " + exception.Message);
                reader.Close();
                response.Close();
                return;
            }

            NumberFormatInfo info2 = new NumberFormatInfo();
            info2.NumberDecimalSeparator = ".";
            info2.NumberGroupSeparator = ",";
            info2.NumberGroupSizes = new int[] { 3 };

            // if the request is verified
            if (String.Compare(IPNResponse, "VERIFIED", false) == 0)
            {
                // check the receiver's e-mail (login is user's 
                // identifier in PayPal)
                // and the transaction type
                if ((String.Compare(this.Request["receiver_email"], 
                    this.business, false) != 0) ||
                    (String.Compare(this.Request["txn_type"], 
                    "web_accept", false) != 0))
                {
                    try
                    {
                        // parameters are not correct. Write a 
                        // response from PayPal
                        // and create a record in the Log file.
                        this.CreatePaymentResponses(this.Request["txn_id"],
                            Convert.ToDecimal(
                            this.Request["mc_gross"], info2),
                            this.Request["payer_email"], 
                            this.Request["first_name"],
                            this.Request["last_name"], 
                            this.Request["address_street"],
                            this.Request["address_city"], 
                            this.Request["address_state"],
                            this.Request["address_zip"], 
                            this.Request["address_country"],
                            Convert.ToInt32(this.Request["custom"]), false,
                            "INVALID paymetn's parameters" + 
                            "(receiver_email or txn_type)");
                        Carts.WriteFile(
                            "Error in IPNHandler: INVALID payment's" +
                            " parameters(receiver_email or txn_type)");
                    }
                    catch (Exception exception)
                    {
                        Carts.WriteFile("Error in IPNHandler: " + 
                            exception.Message);
                    }
                    reader.Close();
                    response.Close();
                    return;
                }

                // check whether this request was performed 
                // earlier for its identifier
                if (this.IsDuplicateID(this.Request["txn_id"]))
                {
                    // the current request is processed. Write 
                    // a response from PayPal
                    // and create a record in the Log file.
                    this.CreatePaymentResponses(this.Request["txn_id"],
                        Convert.ToDecimal(this.Request["mc_gross"], info2),
                        this.Request["payer_email"], 
                        this.Request["first_name"],
                        this.Request["last_name"], 
                        this.Request["address_street"],
                        this.Request["address_city"], 
                        this.Request["address_state"],
                        this.Request["address_zip"], 
                        this.Request["address_country"],
                        Convert.ToInt32(this.Request["custom"]), false, 
                        "Duplicate txn_id found");
                    Carts.WriteFile(
                        "Error in IPNHandler: Duplicate txn_id found");
                    reader.Close();
                    response.Close();
                    return;
                }

                // the amount of payment, the status of the 
                // payment, amd a possible reason of delay
                // The fact that Getting txn_type=web_accept or 
                // txn_type=subscr_payment are got odes not mean that
                // seller will receive the payment.
                // That's why we check payment_status=completed. The 
                // single exception is when the seller's account in
                // not American and pending_reason=intl
                if (((String.Compare(
                    this.Request["mc_gross"].ToString(provider), 
                    requestPrice, false) != 0) ||
                    (String.Compare(this.Request["mc_currency"], 
                    this.currency_code, false) != 0)) ||
                    ((String.Compare(this.Request["payment_status"], 
                    "Completed", false) != 0) &&
                    (String.Compare(this.Request["pending_reason"], 
                    "intl", false) != 0)))
                {
                    // parameters are incorrect or the payment 
                    // was delayed. A response from PayPal should not be
                    // written to DB of an XML file
                    // because it may lead to a failure of 
                    // uniqueness check of the request identifier.
                    // Create a record in the Log file with information 
                    // about the request.
                    Carts.WriteFile(
                        "Error in IPNHandler: INVALID paymetn's parameters."+
                        "Request: " + strFormValues);
                    reader.Close();
                    response.Close();
                    return;
                }
                try
                {
                    // write a response from PayPal
                    this.CreatePaymentResponses(this.Request["txn_id"],
                        Convert.ToDecimal(this.Request["mc_gross"], info2),
                        this.Request["payer_email"], 
                        this.Request["first_name"],
                        this.Request["last_name"], 
                        this.Request["address_street"],
                        this.Request["address_city"], 
                        this.Request["address_state"],
                        this.Request["address_zip"], 
                        this.Request["address_country"],
                        Convert.ToInt32(this.Request["custom"]), true, "");
                    Carts.WriteFile(
                        "Success in IPNHandler: PaymentResponses created");

                    ///////////////////////////////////////////////////
                    // Here we notify the person responsible for 
                    // goods delivery that 
                    // the payment was performed and providing 
                    // him with all needed information about
                    // the payment. Some flags informing that 
                    // user paid for a services can be also set here.
                    // For example, if user paid for registration 
                    // on the site, then the flag should be set 
                    // allowing the user who paid to access the site
                    //////////////////////////////////////////////////
                }
                catch (Exception exception)
                {
                    Carts.WriteFile(
                        "Error in IPNHandler: " + exception.Message);
                }
            }
            else
            {
                Carts.WriteFile(
                    "Error in IPNHandler. IPNResponse = 'INVALID'");
            }
        }
        reader.Close();
        response.Close();
    }

Private Sub Page_Load(ByVal sender As System.Object, 
    ByVal e As System.EventArgs) Handles MyBase.Load

        Dim ci As CultureInfo = New CultureInfo("en-us")
        Dim requestsFile As String = Server.MapPath(
            "~/App_Data/PaymentRequests.xml")
        requests.Clear()

        If File.Exists(requestsFile) Then
            requests.ReadXml(requestsFile)
        Else
            KBSoft.Carts.CreateXml(requestsFile, "Requests")
            requests.ReadXml(requestsFile)
        End If

        Dim responseFile As String = Server.MapPath(
             "~/App_Data/PaymentResponses.xml")
        responses.Clear()

        If File.Exists(responseFile) Then
            responses.ReadXml(responseFile)
        Else
            KBSoft.Carts.CreateXml(responseFile, "Responses")
            responses.ReadXml(responseFile)
        End If

        Dim strFormValues As String = Encoding.ASCII.GetString(
            Request.BinaryRead(Request.ContentLength))
        Dim strNewValue

        ' getting the URL to work with

        Dim URL As String
        If AppSettings("UseSandbox").ToString = "true" Then
            URL = "https://www.sandbox.paypal.com/cgi-bin/webscr"
        Else
            URL = "https://www.paypal.com/cgi-bin/webscr"
        End If

        ' Create the request back

        Dim req As HttpWebRequest = CType(WebRequest.Create(URL), 
            HttpWebRequest)


        ' Set values for the request back
        req.Method = "POST"
        req.ContentType = "application/x-www-form-urlencoded"
        strNewValue = strFormValues + "&cmd=_notify-validate"

        req.ContentLength = strNewValue.Length

        ' Write the request back IPN strings
        Dim stOut As StreamWriter = New StreamWriter(
            req.GetRequestStream(), _
        Encoding.ASCII)
        stOut.Write(strNewValue)
        stOut.Close()

        'send the request, read the response
        Dim strResponse As HttpWebResponse = CType(req.GetResponse(), 
            HttpWebResponse)
        Dim IPNResponseStream As Stream = strResponse.GetResponseStream
        Dim encode As Encoding = System.Text.Encoding.GetEncoding("utf-8")
        Dim readStream As New StreamReader(IPNResponseStream, encode)

        Dim read(256) As [Char]
        ' Reads 256 characters at a time.
        Dim count As Integer = readStream.Read(read, 0, 256)

        While count > 0
            ' Dumps the 256 characters to a string

            Dim IPNResponse As New [String](read, 0, count)
            count = readStream.Read(read, 0, 256)
            Dim amount As String
            Try                
                ' getting the total cost of the goods in cart for an 
                ' identifier of the request stored in the "custom"
                ' variable
                amount = GetRequestPrice(Request("custom").ToString)
                If amount = "" Then
                    KBSoft.Carts.WriteFile("Error in IPNHandler: amount = """)
                    readStream.Close()
                    strResponse.Close()
                    Return
                End If

            Catch ex As Exception
                KBSoft.Carts.WriteFile("Error in IPNHandler: " + ex.Message)
                readStream.Close()
                strResponse.Close()
                Return
            End Try

            Dim provider As NumberFormatInfo = New NumberFormatInfo()
            provider.NumberDecimalSeparator = "."
            provider.NumberGroupSeparator = ","
            provider.NumberGroupSizes = New Integer() {3}

            ' if the request is verified
            If IPNResponse = "VERIFIED" Then                
                ' check the receiver's e-mail (login is user's 
                ' identifier in PayPal) and the transaction type
                If Request("receiver_email") <> business Or Request(
                    "txn_type") <> "web_accept" Then
                    Try                        
                        ' parameters are not correct. Write a response from 
                        ' PayPal and create a record in the Log file.
                        CreatePaymentResponses(Request("txn_id"), 
                        Convert.ToDecimal(Request("mc_gross"), provider), _
                        Request("payer_email"), Request("first_name"), 
                        Request("last_name"), Request("address_street"), _
                        Request("address_city"), Request("address_state"), 
                        Request("address_zip"), Request("address_country"), _
                        Convert.ToInt32(Request("custom")), False, 
                        "INVALID paymetn's parameters (
                        receiver_email or txn_type)")
                        KBSoft.Carts.WriteFile(
                        "Error in IPNHandler: INVALID paymetn's parameters"+
                        " (receiver_email or txn_type)")
                    Catch ex As Exception
                        KBSoft.Carts.WriteFile(
                        "Error in IPNHandler: " + ex.Message)
                    End Try
                    readStream.Close()
                    strResponse.Close()
                    Return
                End If                
                ' check whether this request was performed earlier for its 
                ' identifier
                If IsDuplicateID(Request("txn_id")) Then                    
                    ' the current request is processed. Write a response from 
                    ' PayPal and create a record in the Log file.
                    CreatePaymentResponses(Request("txn_id"), 
                    Convert.ToDecimal(Request("mc_gross"), provider), _
                    Request("payer_email"), Request("first_name"), 
                    Request("last_name"), Request("address_street"), _
                    Request("address_city"), Request("address_state"), 
                    Request("address_zip"), Request("address_country"), _
                    Convert.ToInt32(Request("custom")), False, 
                    "Duplicate txn_id found")
                    KBSoft.Carts.WriteFile(
                    "Error in IPNHandler: Duplicate txn_id found")
                    readStream.Close()
                    strResponse.Close()
                    Return
                End If
                ' the amount of payment, the status of the payment, amd a 
                ' possible reason of delay
                ' The fact that Getting txn_type=web_accept or 
                ' txn_type=subscr_payment are got odes not mean that
                ' seller will receive the payment.
                ' That's why we check payment_status=completed. The 
                ' single exception is when the seller's account in
                ' not American and pending_reason=intl
                If Request("mc_gross").ToString(ci) <> amount Or Request(
                    "mc_currency") <> currency_code Or _
                (Request("payment_status") <> "Completed" And Request(
                    "pending_reason") <> "intl") Then
                    ' parameters are incorrect or the payment was delayed. 
                    ' A response from PayPal should not be
                    ' written to DB of an XML file
                    ' because it may lead to a failure of uniqueness check of 
                    ' the request identifier.
                    ' Create a record in the Log file with information about 
                    ' the request.
                    KBSoft.Carts.WriteFile(
                    "Error in IPNHandler: INVALID paymetn's parameters."+
                    " Request: " + strFormValues)
                    readStream.Close()
                    strResponse.Close()
                    Return
                End If

                Try                    
                    ' write a response from PayPal
                    CreatePaymentResponses(Request("txn_id"), 
                    Convert.ToDecimal(Request("mc_gross"), provider), _
                    Request("payer_email"), Request("first_name"), 
                    Request("last_name"), Request("address_street"), _
                    Request("address_city"), Request("address_state"), 
                    Request("address_zip"), Request("address_country"), _
                    Convert.ToInt32(Request("custom")), True, "")
                    KBSoft.Carts.WriteFile(
                    "Success in IPNHandler: PaymentResponses created")
                    
                    ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
                    ' Here we notify the person responsible for goods delivery
                    ' that the payment was performed and providing him with 
                    ' all needed information about the payment. Some flags 
                    ' informing that user paid for a services can be also
                    ' set here. For example, if user paid for registration 
                    ' on the site, then the flag should be set 
                    ' allowing the user who paid to access the site
                    ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''

                Catch ex As Exception
                    KBSoft.Carts.WriteFile(
                        "Error in IPNHandler: " + ex.Message)
                End Try

            Else
                KBSoft.Carts.WriteFile(
                    "Error in IPNHandler. IPNResponse = 'INVALID'")
            End If
        End While

        readStream.Close()
        strResponse.Close()
    End Sub

6. Parameters of web.config adjustment

<appSettings>        
    <!--  PayPay parameters-->
    <add key="BusinessEmail" value="mymail@mail.com"/>
    <add key="CancelPurchaseUrl" value="http://YOUR_IP/paypal/default.aspx"/>
    <add key="ReturnUrl" value="http://YOUR_IP/paypal/payment_success.aspx"/>
    <add key="NotifyUrl" value="http://YOUR_IP/paypal/IPNHandler.aspx"/>
    <add key="CurrencyCode" value="USD"/>
    <add key="UseSandbox" value="true"/>
    <add key="SendToReturnURL" value="true"/>

</appSettings> 

7. Use of the source code

8. Conclusion

9. References