PayPal快速结帐NVPAPI开发指南

1PayPal快速结账NVPAPI开发指南PayPal快速结账NVPAPI开发指南2PayPal快速结账NVPAPI开发指南ECExpressCheckoutNVPName-ValuePairIPNInstantPaymentNotificationAPIApplicationProgrammingInterface概览以下列出了本文件中用到的专门术语的英文缩写和全称PayPalNVPAPI简介PayPalNVPAPI是简单的编程接口，允许您（商家）使用PayPal的业务功能来执行以下操作：使用“快速结账”功能在您的网站上接受PayPal结账。使用“直接付款”功能向信用卡收费。捕获先前通过“快速结账”、“直接付款”或“网站付款标准版”授权的付款。重新授权或作废以前的授权。使用“集中付款”功能向一位或多位收款人付款。发放全额退款或多笔部分退款。使用开始日期或其他条件搜索交易。查看特定交易的明细。PayPalNVPAPI能够简化向网络应用程序添加PayPal的过程。您构建NVP字符串并使用HTTPS将其发布到PayPal服务器。然后PayPal发回一个NVP格式的响应。NVP格式NVP是指定字符串中的名称和值的一种方法。NVP是表示URI规范中的查询的非正式名称。NVP字符串附加到URL上。NVP字符串符合以下准则：名称和值用等号(=)分隔。例如：FIRSTNAME=Robert名称/值对用与号(&)分隔。例如：FIRSTNAME=Robert&MIDDLENAME=Herbert&LASTNAME=MooreNVP字符串中每个字段的值已经过URL编码。3PayPal快速结账NVPAPI开发指南请求格式每个NVP请求都由必需的和可选的参数及其值组成。参数名称不区分大小写。本文档中的示例使用大写参数名称，并将参数分为必需的安全参数和正文参数。必需的安全参数USER=apiUsername&PWD=apiPassword&SIGNATURE=apiSignature&SUBJECT=optiona&ThirdPartyEmailAddress&VERSION=84.0以下参数始终是必需的：USERPWDSIGNATUREVERSION注意：示例采用如下方式显示必需的安全参数：[requiredSecurityParameters]正文参数&METHOD=methodName&otherRequiredAndOptionalParametersAPI凭证必需的安全参数：API凭证参数值定义USER必需您的PayPalAPI用户名。PWD必需您的PayPalAPI密码。SIGNATURE可选您的PayPalAPI签名字符串。如果您使用API证书，请勿包括该参数。重要信息：您必须在实施过程中保护USER、PWD和SIGNATURE的值。可考虑将这些值存储在安全的位置（而不是存储在Web服务器的文档根目录），并设置文件权限，以便只有执行您的电子商务应用程序的系统用户才能够访问。要访问PayPalAPI，您需要可标明您身份的API凭证（API签名或API证书）。获取API的方法请参照文档。在运行于PayPalSandbox测试环境的示例程序中使用以下示例API签名和密码。注意：如果使用示例代码，则该签名已存在于代码中的配置文件中（文件名类似Constants.*）。本节描述PayPalNVPAPI所用技术的细节。响应格式成功响应字段ACK=Success&TIMESTAMP=date/timeOfResponse&CORRELATIONID=debuggingToken&VERSION=84.0&BUILD=buildNumber[successResponseFields]API响应字段&NAME1=value1&NAME2=value2&NAME3=value34PayPal快速结账NVPAPI开发指南每个响应都包含ACK字段。如果ACK字段的值是Success或SuccessWithWarning，您就应处理API响应字段。对于成功的响应，您可忽略BUILD字段之前的所有字段（包括BUILD字段）。重要字段在BUILD字段之后开始。有关每种方法可能的成功响应字段，请参阅附录A“NVPAPI方法和字段参考”。如何处理这些字段取决于您调用的特定API方法，例如为用户填写表格、更新数据库，等等。错误响应如果ACK值为Error或Warning，就不会返回API响应字段。错误响应具有以下一般格式。错误响应字段ACK=Error&TIMESTAMP=date/timeOfResponse&CORRELATIONID=debuggingToken&VERSION=84.0&BUILD=buildNumber&L_ERRORCODE0=errorCode&L_SHORTMESSAGE0=shortMessage&L_LONGMESSAGE0=longMessage&L_SEVERITYCODE0=severityCode可能返回多个错误。每组错误都具有不同的数字后缀,以0开始，每个错误增加1。对于可能的出错原因以及如何纠正，请参阅附录B“错误消息参考”中关于特定错误代码、短消息及长消息的说明。ACK参数值下表列出了ACK参数的值。ACK参数值响应类型值成功响应SuccessSuccessWithWarning错误响应FailureFailureWithWarningWarning5PayPal快速结账NVPAPI开发指南URL编码请求和响应已经过URL编码。URL编码确保您可传输特殊字符、URL中不允许的字符以及在URL中具有特殊含义的字符，例如等号和与号。例如，以下NVP字符串：NAME=RobertMoore&COMPANY=R.H.Moore&Associates是按如下方式进行URL编码的：NAME=Robert+Moore&COMPANY=R%2E+H%2E+Moore+%26+Associates请使用以下方法对您的NVP字符串进行URL编码或URL解码：语言方法函数ASP.NET编码System.Web.HttpUtility.UrlEncode(buffer,Encoding.Default)解码System.Web.HttpUtility.UrlDecode(buffer,Encoding.Default)ClassicASP编码Server.URLEncode解码无内置函数。Internet上有若干实施示例Java编码java.net.URLEncoder.encode解码java.net.URLDecoder.decodePHP编码urlencode()解码urldecode()ColdFusion编码URLEncodedFormatstring[,charset]解码URLDecodeurlEncodedString[,charset])6PayPal快速结账NVPAPI开发指南开始集成PayPal快速结账PayPal快速结账流程从流程图上可以看出整个付款过程中调用了三次API，分别为SetExpressCheckout该方法请求PayPa使用“快速支付快速结账”从您的客户处获取付款。GetExpressCheckoutDetails该方法返回客户的信息，包括在PayPal上存储的姓名和地址。DoExpressCheckoutDetails该方法请求获取付款。7PayPal快速结账NVPAPI开发指南使用SetExpressCheckout开始结账SetExpressCheckout请求方法通知PayPal您正使用“快速结账”从您的客户处获取付款。SetExpressCheckout请求中必须始终包含以下参数：PAYMENTREQUEST_0_AMTRETURNURLCANCELURL表3.1开始快速结账请求[requiredSecurityParameters]&METHOD=SetExpressCheckout&PAYMENTREQUEST_0_AMT=10.00&RETURNURL==响应[successResponseFields]&TOKEN=EC-3DJ78083ES565113B注意：PAYMENTACTION没有指定的值，所以该参数默认为Sale。请保存TOKEN，以便用于其余的“快速结账”调用。1.在SetExpressCheckout响应中，您可获得一个唯一地标识该三步交易的TOKEN。您将请求中的该TOKEN传递给GetExpressCheckoutDetails和DoExpressCheckoutPayment。GetExpressCheckoutDetails和DoExpressCheckoutPayment都会在响应中返回该TOKEN。该示例演示使用最少参数的基本结账。2.将客户的浏览器跳转至PayPal登录页面您从SetExpressCheckout收到成功响应后，请将SetExpressCheckout响应中的TOKEN作为名称/值对添加到以下URL，并将您客户的浏览器跳转至该URL：=_express-checkout&token=value_from_SetExpressCheckoutResponse要将客户的浏览器跳转至PayPal登录页面使用GetExpressCheckoutDetails获取付款人详细信息GetExpressCheckoutDetails方法返回客户的信息，包括在PayPal上存储的姓名和地址。GetExpressCheckoutDetails中必须始终包含以下参数：TOKEN：使用来自SetExpressCheckout响应的值该响应包含该TOKEN和客户详细信息。8PayPal快速结账NVPAPI开发指南表3.2获取付款人详细信息请求[requiredSecurityParameters]&METHOD=GetExpressCheckoutDetails&TOKEN=EC-3DJ78083ES565113B响应[successResponseFields]&TOKEN=EC-3DJ78083ES565113B&EMAIL=[e-mail]&PAYERID=95HR9CM6D56Q2&PAYERSTATUS=verified&FIRSTNAME=John&LASTNAME=Smith&PAYMENTREQUEST_n_SHIPTOCOUNTRYCODE=US&PAYMENTREQUEST_nSHIPTONAME=JohnSmith&PAYMENTREQUEST_n_SHIPTOSTREET=144+Main+St.&PAYMENTREQUEST_n_SHIPTOCITY=San+Jose&PAYMENTREQUEST_n_SHIPTOSTATE=CA&PAYMENTREQUEST_n_SHIPTOCOUNTRYCODE=US&PAYMENTREQUEST_n_SHIPTOZIP=99221&PAYMENTREQUEST_n_ADDRESSSTATUS=Confirmed请确保TOKEN与SetExpressCheckout响应中的值匹配。保存PAYERID，以便用于下一次调用。使用DoExpressCheckoutPayment获取付款使用DoExpressCheckoutPayment请求，通过PayPal快速结账获取付款。默认情况下，使用DoExpressCheckoutPayment请求进行最终销售。DoExpressCheckoutPayment请求中