Paypal国际版网站集成

 

      前段时间接到一个外贸网站的项目，集成paypal支付接口的，对象是海外用户，全部用US的信用卡结算。所以只能使用paypal国际版，还好paypal上的资料非常齐全，而 且还提供了开发者沙盒（sandbox），相比之下，国内流行的支付宝还有很长的路要走啊。

      主要分为序言、支付按钮、返回信息方式（IPN&PDT）、实例四部分组成

      首 先，你需要注册一个paypal帐户，帐户类型分为Personal（个人）、Premier（高级）和Business（商业），他们的差别对于开发者 来说主要是返回的信息，Personal的不能使用IPN和PDT等商家工具，即不能获取交易信息，但是Personal帐户收款无需手续 费；Premier和Business当然就提供了IPN和PDT功能，能够在客户支付成功后，将交易信息传给指定的网站，用来二次使用。Premier 和Business使用上的差异我不是很清楚，应该是月收款额和手续费上的区别吧。
      这里插进来介绍一下paypal sandbox，也就是沙盒，是paypal提供给开发者的一个工具，非常好用，你可以在https://developer.paypal.com/ 注册和使用它。登录以后可以新建帐户，设置余额和帐户类型，有一点要注意，每次使用时必须先登录sandbox才能使用新建的那些帐户。Sndbox里面有个测试工具，可以发送IPN的，以后会用到。

      接着上面的内容，注册完帐户以后，当然，一开始开发最好使用sandbox，不然资金转来转去手续费都扣光了，paypal的费率如下：
      
      比起国内的支付工具，paypal贵了好多，当然，和国情也有关系。
    
      接下来是按钮的代码，很简单，就是一个普通的网页表单代码：

程序代码

< form  action ="https://www.paypal.com/cgi-bin/webscr"  method ="post" >
    < input  type ="hidden"  name ="cmd"  value ="_xclick" >
    < input  type ="hidden"  name ="business"  value ="[email protected]" >
    < input  type ="hidden"  name ="item_name"  
   value ="Item Name Goes Here" >
    < input  type ="hidden"  name ="item_number"  
   value ="Item Number Goes Here" >
    < input  type ="hidden"  name ="amount"  value ="100.00" >
    < input  type ="hidden"  name ="no_shipping"  value ="2" >
    < input  type ="hidden"  name ="no_note"  value ="1" >
    < input  type ="hidden"  name ="currency_code"  value ="USD" >
    < input  type ="hidden"  name ="bn"  value ="IC_Sample" >
    < input  type ="image"  src ="https://www.paypal.com/
   en_US/i/btn/x-click-but23.gif"  
   name ="submit"  alt ="Make payments with payPal - it's fast, 
   free and secure!" >
    < img  alt =""  
   src ="https://www.paypal.com/en_US/i/scr/pixel.gif"  
   width ="1"  height ="1" >
form >

asp.net 版本：

aspx：

cs：

protected void submit_onclick () {
// 存储购物车的总额
decimal amount = Convert.ToDecimal(“280.00”);
// 存储订单ID
string orderId = “200810240101”;
// 获取网站的名称
string siteName = BalloonShopConfiguration.SiteName;
// 创建贝宝重定向的位置
string redirect = "";
redirect += "https://www.paypal.com/xclick/[email protected]";
redirect += "&item_name=" + siteName + " Order " + orderId;
redirect += "&item_number=" + orderId;
redirect += "&amount=" + String.Format("{0:0.00} ", amount);
redirect += "¤cy=USD";
redirect += "&return=http://www." + siteName + ".com    //这里是成功后返回的aspx页面 ";
redirect += "&cancel_return=http://www." + siteName + ".com/Error.aspx";    //如果失败回到的页面
// 重定向到付款页面
Response.Redirect(redirect);
}

      如果使用sandbox，action地址改成https://www.sandbox.paypal.com/cgi-bin/webscr 即可，上面这段还是很容易理解的，看下name和value基本上就能知道每个值的含义了。
      
      保存用浏览器打开，就会看到一个paypal的按钮，点击过去按照提示操作，就能付款到business指定值的帐户了。

      这就是一个最简单的paypal支付按钮。

      在付款成功之后，将信息返回到你的网站，大部分需求都是客户完成付款后返回信息到网站的数据库，记录网站客服的交易信息

引用内容

什么是即时付款通知IPN
当您收到新的付款交易或者已发生的付款交易的状态发生变化时，PayPal都将异步（即不作为网站付款流程的一部分） 发送付款详细数据到您所指定的URL，以便您了解买家付款的具体情况并做出相应的响应。这个过程我们称作即时付款通知（简称 IPN）。

      相 信大部分网站集成Paypal都希望能够实现客户支付完成后返回信息到自己的网站，然后处理这些信息。比如客户在你的网站上购买了一个产品，通过 Paypal完成了支付，接着Paypal告诉你的网站客户完成了支付以及支付信息，最后你的网站将这些信息记录到你自己的数据库中，并且将你的客户订单状态设为已支付，接着你就可以进行一系列的相关订单的后续操作。
      IPN就能帮助我们实现这个功能，IPN示意图如下（来自Paypal.com）：
      

      当客户完成支付，Paypal会在后台通过post方式向你的服务器传送交易数据，来实现网站集成的功能。
接下来我们就来看IPN的实现方法。
      第一步，你需要一个sandbox的帐号，这很重要，因为它能让你随心所欲的进行测试，而不用担心资金在天上飞。注册地址：https://developer.paypal.com/
      第二步，登陆sandbox，新建一个商家帐号（卖方）和一个客户账号（买方），其中卖方帐号必须是Premier或者Business，不然无法使用IPN功能。
      

      新建买家帐号的时候记得在Account Balance中加上金额，不然你就没钱买东西了，如果paypal.com的帐号也能这样加钱多好。
      新建完两个帐号：
      

      卖家帐号的test mode要设为enabled。
      选中business帐号，点击下面的Enter Sandbox Test Site进入sandbox Test Site，登录，就像普通Paypal帐号的管理页面一样。
      

      点 击Profile，在Selling Preferences中选择Instant Payment Notification Preferences，点击edit加入IPN信息返回的地址，记得勾上前面那个选项，我是用.net写的接受文件，所以我的IPN地址是http://www.Test.org/ipn.aspx ,地址只要能在互联网上访问到就可以了。
      

      在 Profile -> Selling Preferences ->Website Payment Preferences选项中，有一个Auto Return的选项，将它设为on，并且在下面的return地址中填入你希望的客户支付完成后返回的地址：
      

       以上就完成了商家端的设置。

      接下来是你网站上ipn.aspx文件的编写，这个是用来接收支付数据的，是非常关键的一个文件。
      文件环境，.net 2.0，语言C#。
      Ipn.aspx文件：此文件不用修改任何东西，代码都在cs文件中。
      Ipn.aspx.cs文件：关键代码

      定义一个VerifyIPN()函数：

程序代码

bool  VerifyIPN()
{
         string  strFormValues  =  Request.Form.ToString();
         string  strNewValue;
         string  strResponse;
         string  serverURL  =   " https://www.sandbox.paypal.com/cgi-bin/webscr " ;

        HttpWebRequest req  =  (HttpWebRequest)WebRequest.Create(serverURL);
        req.Method  =   " POST " ;
        req.ContentType  =   " application/x-www-form-urlencoded " ;
        strNewValue  =  strFormValues  +   " &cmd=_notify-validate " ;
        req.ContentLength  =  strNewValue.Length;

        StreamWriter stOut  =   new  StreamWriter(req.GetRequestStream(), System.Text.Encoding.ASCII);
        stOut.Write(strNewValue);
        stOut.Close();

        StreamReader stIn  =   new  StreamReader(req.GetResponse().GetResponseStream());
        strResponse  =  stIn.ReadToEnd();
        stIn.Close();

         return  strResponse  ==   " VERIFIED " ;
}

       这段代码的作用是判断IPN信息是否来自Pyapal，如果不进行判断，那么恶意用户完全可以模拟一个信息post到你的网站上，让你认为订单已经完成支付，所以，必须首先对接受到的信息进行验证。

      代码的基本原理，serverURL定义了验证地址，sandbox为：https://www.sandbox.paypal.com/cgi-bin/webscr ，Paypal.com就是https://www.paypal.com/cgi-bin/webscr 。
      将paypal发送过来的所有信息加上一个&cmd=_notify-validate参数，表示对这个信息进行验证，全部发送回paypal验证，如果信息确实存在，则返回VERIFIED字符串。
验证成功后，就可以用如下形式获得交易信息：

程序代码

string  ppTx  =  Request.Form[ " txn_id " ].ToString();
string  ppStatus  =  Request.Form[ " payment_status " ].ToString();
string  ppDate  =  Request.Form[ " payment_date " ].ToString();
string  ppItem  =  Request.Form[ " item_name " ].ToString();
string  ppPrice  =  Request.Form[ " mc_gross " ].ToString();

      每个变量的解释可以参考Paypal网站上的说明，我这里就不再重复。

     .cs代码结构如下：

程序代码

public   partial   class  paypal_ipn : System.Web.UI.Page
{
     protected   void  Page_Load( object  sender, EventArgs e)
    {
         if  (VerifyIPN()) // 验证成功
        {
             string  ppTx  =  Request.Form[ " txn_id " ].ToString(); // 获取post中的各项变量值
                …
            执行将数据写入数据库等操作
        }   
    }

     bool  VerifyIPN()
{
        具体代码见上。
    }
}

PayPal将回复该 POST，并在回复的正文中包含一个单词“VERIFIED ”或“INVALID”。当您收到 VERIFIED 回复时，您需要在实施订单之前执行若干检查：

确认“payment_status”为“Completed”，因为系统也会为其他结果（如“Pending”或“Failed”）发送 IPN。
检查“txn_id”是否未重复，以防止欺诈者重复使用旧的已完成的交易。
验证“receiver_email”是已在您的PayPal账户中注册的电子邮件地址，以防止将付款发送到欺诈者的账户 。
检查其他交易详情（如物品号和价格），以确认价格未改变完成了以上检查后，您可以使用 IPN 数据更新您的数据库，并处理购物。

如果收到“无效”通知，则应将其视为可疑通知，并应对其进行调查。

      这样，就实现了将支付信息传回网站的功能。注：当交易状态发生改变时，paypal也会返回一个ipn，比如完成支付，退款等等。

      介绍一下sandbox中IPN测试工具，登陆sandbox主帐号，就是你在sandbox上注册的那个，不是那些卖家/买家帐号。
      选择Test Tools -> Instant Payment Notification (IPN) Simulator：

      输入你的ipn接受文件地址，选择ipn信息的方式，然后会让你填具体信息内容，再点击Send IPN，就能模拟一个ipn到你网站的页面，可以用来测试IPN是否正常工作。
      
      
      不过这个工具有个小BUG，就是发送的IPN里不包括contact_phone这个变量，但是实际的IPN里是有的，这里要注意一下。
      注： 可以在商家帐号的Profile -> Selling Preferences ->Website Payment Preferences中，选择Contact Telephone Number这一栏，来确定是否需要发送买家联系电话。
      

      通过IPN，你的网站就开始从真正意义上的集成了Paypal。

PDT的介绍

引用内容

什么是PDT
PDT是一个安全获取付款明细的方式。在买家付完款后，卖家可以通过此方式即时获取付款明细并显示给买家看。

      

      上图是PDT的流程示意。
      1.首先买家付款后通过事先设定好的返回url（return）回到您的网站。
      2.接着paypal在返回url后面加上tx变量，即交易号。
      3.然后网站将收到的tx和您的令牌（paypal账户里申请）发回paypal。
      4.paypal验证令牌通过后，将交易明细发回网站。
      5.最后网站将交易明细显示给客户。

PayPal 提供附加变量，用于自定义您的 Form Post。所有可用变量如下（变量名称必须用小写 ）：

可用变量

business 您的PayPal账户上的电子邮件地址
quantity 物品数量。大于 1 时，会与金额相乘
item_name 物品名称（或购物车名称）。必须是字母数字字符，最多为 127 个字符
item_number 用于跟踪付款的可选传递变量。必须是字母数字字符，最多为 127 个字符
amount 物品的价格（购物车中所有物品的总价格）
shipping 该物品的运送成本
shipping2 每增加一件物品所需的运送成本
handling 手续费
tax 基于交易的税额。如果使用该变量，传递值将覆盖所有用户信息税收设置（不管买家所在位置）。
no_shipping 送货地址。如果设为 “1″，则不会要求您的客户提供送货地址。该变量为可选项；如果省略或设为 “0″，将提示您的客户输入送货地址
cn 可选标签，会在提示栏上显示（最多 40 个字符）
no_note 为付款加入提示。如果设为 “1″，则不会提示您的客户输入提示。该变量为可选项；如果省略或设为 “0″，将提示您的客户输入提示。
on0 第一选项栏名称。最多 64 个字符
os0 第一组选项值。最多 200 个字符。”on0″ 必须定义，以便识别 “os0″。
on1 第二选项栏名称。最多 64 个字符
os1 第二组选项值。最多 200 个字符。”on1″ 必须定义，以便识别 “os1″。
custom 决不会向您的客户显示的可选转递变量。可用于跟踪存货
invoice 决不会向您的客户显示的可选转递变量。可用于跟踪账单号
notify_url 仅与 IPN 一起使用。发送 IPN Form Post 的互联网 URL
return 您的客户完成付款后将返回的互联网 URL
cancel_return 您的客户取消付款后将返回的互联网 URL
image_url 您要用作图标的图片的互联网 URL，图片大小为 150 X 50 像素
cs 设置您的付款页面的背景色。如果设为 “1″，背景色将为黑色。该变量为可选项；如果省略或设为 “0″，背景色将为白色

扩展变量

PayPal 允许您粘贴扩展变量，条件是将改变以下 “cmd” 值： 到：

 
 
通过上述 “cmd” 值修改，您还可使用以下变量：

扩展变量
email 客户的电子邮件地址
first_name 客户的名。必须是字母数字字符，最多为 32 个字符
last_name 客户的姓。必须是字母数字字符，最多为 64 个字符
address1 客户地址所在国家或地区。必须是字母数字字符，最多为 100 个字符
address2 客户地址第二行。必须是字母数字字符，最多为 100 个字符
city 客户地址所在城市。必须是字母数字字符，最多为 100 个字符
state 客户地址所在州。必须是正式的 2 个字母缩写
zip 客户地址的邮政编码
night_phone_a 客户夜间联系电话号码的区号
night_phone_b 客户夜间联系电话号码前三位
day_phone_a 客户白天联系电话号码的区号
day_phone_b 客户白天联系电话号码前三位
   
提示：若要更改”用户信息”中的默认运费和手续费设置，请转至您的用户信息，编辑您的运费计算，然后点击”允许采用基于交易的运费”复选框。

将单个物品传递给PayPal

如果您的第三方购物车可设置成向PayPal传递单个物品，有关物品的信息将加入买家和卖家的记录日志和系统通知中。要加入该物品的信息，您需要将 HTML 格式元素粘贴至PayPal购物车流程的新版本。该过程与 #1 节”将总购物车数量传递给PayPal”描述的非常相似，不同之处在于：

将 “cmd” 变量设置到 “_cart”
更换必要的 HTML 行

与
 
添加称为 “upload” 的新变量
在 <表格> 和 标签之间新增以下行：
 
定义物品明细
对于以下各特定物品参数，定义与通过您的合作商购物车购买的各物品对应的一组新值。将 “_x” 附加到变量名称，其中 x 是物品号码，从 1 开始，每加入一物品增加一。

item_name_x （物品 #x 需要）购物车中物品 #x 的名称。必须是字母数字字符，最多为 127 个字符
item_number_x 与购物车中物品 #x 关联的可选传递变量。必须是字母数字字符，最多为 127 个字符
amount_x （物品 #x 需要）物品 #x 的价格
shipping_x 运送物品 #x 的第一件（数量 1）的成本
shipping2_x 每增加一件运送物品 #x（数量 2 或更多）所需的运送成本
handling_x 物品 #x 的处理成本
on0_x 物品 #x 的第一选项栏名称。最多 64 个字符
os0_x 物品 #x 的第一组选项值。最多 200 个字符。”on0_x” 必须定义，以便识别 “os0_x”。
on1_x 物品 #x 的第二选项栏名称。最多 64 个字符
os1_x 物品 #x 的第二组选项值。最多 200 个字符。”on1_x” 必须定义，以便识别 “os1_x”。 

为购物车中每件物品重复此设定
为您的买家购物车中的各物品加入以上表格中的一组必需的变量和任何选项变量。购物车中的第一物品必须用以 “_1″ 结束的参数定义，如 “item_name_1″、”amount_1″ 等。同样，第二物品应用变量 “item_name_2″、”amount_2″ 等命名。提示：”_x” 值必须以一为单位按序递增，以便识别。如果从 item #1 跳到 item #3 而不定义 item #2，则第三个物品会被忽略。

要指定币种：所有货币变量（金额、运费、运费 2、手续费、税款）将以粘贴在付款上的 “currency_code” 变量指定的币种显示。因为其不是随物品不同的，无需向变量名称附加 “_x”。如果没有粘贴 “currency_code” 变量，我们将假定所有货币变量值为美元。

PayPal提供了多个API接口供开发者使用。在使用API之前，你必须先申请一个高级个人账户或者企业账户，同时你必须获取API 凭证供每次调用API 时使用。
一旦你获取了API凭证，您就可以调用相关的API接口了。目前，我们提供两种API接口方式，NVP和SOAP。一般来说我们推荐您使用 NVP 接口。
• Name-Value Pair（NVP）接口 – 请求和响应都是使用简单的HTTP。该接口简单易实现，适合于初级开发者和需要快速完成集成的人员；
• SOAP接口 – 请求和响应都是通过SOAP来完成。该接口适合于面向对象工程的开发；

PayPal API：NVP（名称/值对）接口

通过NVP API接口， 您只需给PayPal发送一个HTTP请求，并通过“名称=值”的形式指定请求参数，即可充分利用PayPal的API功能。

NVP API 是 PayPal 的业务功能、风险管理和业务逻辑的简单接口。NVP API 最基本的使用方法是通过到 PayPal 服务器的 HTTPS 连接发送一个 NVP 字符串，然后处理响应（也是一个 NVP 字符串）。执行 NVP API 调用的基本步骤如下：

• 为特定的 API 方法构造一个请求参数字符串。
• 通过 HTTPS 连接向 PayPal 服务器发送这个参数字符串。
• 处理服务器响应中的 NVP。

每个NVP API请求字符串包含有API用户名、API密码、所要调用API的名称及用来标识交易的令牌，如： [email protected]&PWD=mypassword &METHOD=GetExpressCheckoutDetails&TOKEN=EC-23T233ZP3DFB…

成功的应答包含以下要素：ACK=Success ，以及一个用来标识交易的唯一令牌。 ACK=Success&TIMESTAMP=date/timeOfResponse &CORRELATIONID=debuggingToken&VERSION=2.300000&BUILD=buildNumber [email protected] &PAYERID=95HR9CM6D56Q2&PAYERSTATUS=verified &FIRSTNAME=John&LASTNAME=Smith…

您可以使用NVP API完成以下操作：
• 搜索已完成的交易记录，以及查询交易详情；
• 自动化后端功能，例如，捕获授权，以及处理退款等；

API Profile

进入商家账号得到相应的APIProfile，如果是以中文语言查看，在-用户信息-API 访问-中得到，其中里面申请API时，有两个选项，第一个是用签名的方式,第二种是以证书的方式来认证商家身份，当你选择下载数字证时，可以到 www.paypaltech.com/tools/pem2p12.php转换为.p12文件，也可以采用OpenSSL的命令完成，一句话搞定，要输 入密码喔~。这里的链接有详细说明www.paypal.com/IntegrationCenter/ic_certificate.html

相应参考资料请参考连接www.paypal.com/IntegrationCenter/ic_expresscheckout.html 了解关于Express Checkout的原理；
在此基础上，你可以访问www.paypal.com/IntegrationCenter/ic_nvp.html 获取相关测试代码；
关于PayPal的测试环境你可以访问www.paypal.com/IntegrationCenter/ic_sandbox.html,
API Reference https://www.paypal.com/IntegrationCenter/ic_api-reference.html

参考：

PayPal 集成资源

  PayPal Order Management Integration Guide (unknown, 17 hits)
You need to be a registered user to download this file.

  PayPal WebsitePaymentsStandard IntegrationGuide (unknown, 16 hits)
You need to be a registered user to download this file.

  PayPal-网站付款标准版集成指南 (unknown, 33 hits)
You need to be a registered user to download this file.

  PayPal-订单管理集成指南 (unknown, 29 hits)
You need to be a registered user to download this file.

  PayPal PHP CLASS (13.5 KiB, 1,451 hits)