1
PayPal 快速结账 NVP API 开发指南
PayPal 快速结账 NVP API 开
发指南
2
PayPal 快速结账 NVP API 开发指南
EC
Express Checkout
NVP
Name-Value Pair
IPN
Instant Payment Notification
API
Application Programming Interface
概览
以下列出了本文件中用到的专门术语的英文缩写和全称
PayPal NVP API 简介
PayPal NVP API 是简单的编程接口,允许您(商家)使用 PayPal 的业务功能来执行以下操
作:
使用“快速结账”功能在您的网站上接受 PayPal 结账。
使用“直接付款”功能向信用卡收费。
捕获先前通过“快速结账”、“直接付款”或“网站付款标准版”授权的付款。
重新授权或作废以前的授权。
使用“集中付款”功能向一位或多位收款人付款。
发放全额退款或多笔部分退款。
使用开始日期或其他条件搜索交易。
查看特定交易的明细。
PayPal NVP API 能够简化向网络应用程序添加 PayPal 的过程。您构建 NVP 字符串并使用
HTTPS 将其发布到 PayPal 服务器。然后 PayPal 发回一个 NVP 格式的响应。
NVP 格式
NVP 是指定字符串中的名称和值的一种方法。NVP 是表示 URI 规范中的查询的非正式名称。
NVP 字符串附加到 URL 上。
NVP 字符串符合以下准则:
名称和值用等号(=)分隔。例如:
FIRSTNAME=Robert
名称/值对用与号(&)分隔。例如:
FIRSTNAME=Robert&MIDDLENAME=Herbert&LASTNAME=Moore
NVP 字符串中每个字段的值已经过 URL 编码。
3
PayPal 快速结账 NVP API 开发指南
请求格式
每个 NVP 请求都由必需的和可选的参数及其值组成。参数名称不区分大小写。本文档中的
示例使用大写参数名称,并将参数分为必需的安全参数和正文参数。
必需的安全参数
USER=apiUsername&PWD=apiPassword&SIGNATURE=apiSignature&SUBJEC
T=optiona&ThirdPartyEmailAddress&VERSION=84.0
以下参数始终是必需的:
USER PWD SIGNATURE VERSION
注意:示例采用如下方式显示必需的安全参数:
[requiredSecurityParameters]
正文参数
&METHOD=methodName&otherRequiredAndOptionalParameters
API 凭证
必需的安全参数:API 凭证
参数
值
定义
USER
必需
您的 PayPal API 用户名。
PWD
必需
您的 PayPal API 密码。
SIGNATURE
可选
您的 PayPal API 签名字符串。如
果您
使用 API 证书,请勿包括该参数。
重要信息:您必须在实施过程中保护 USER、PWD 和 SIGNATURE 的值。可考虑将这些值存储
在安全的位置(而不是存储在 Web 服务器的文档根目录),并设置文件权限,以便只有执行
您的电子商务应用程序的系统用户才能够访问。
要访问 PayPal API,您需要可标明您身份的 API 凭证(API 签名或 API 证书)。获取 API 的
方法请参照文档。
在运行于 PayPal Sandbox 测试环境的示例程序中使用以下示例 API 签名和密码。
注意:如果使用示例代码,则该签名已存在于代码中的配置文件中(文件名类似 Constants.*)。
本节描述 PayPal NVP API 所用技术的细节。
响应格式
成功响应字段
ACK=Success&TIMESTAMP=date/timeOfResponse&CORRELATIONID=debug
gingToken&VERSION=84.0&BUILD=buildNumber
[successResponseFields]
API 响应字段
&NAME1=value1&NAME2=value2&NAME3=value3
4
PayPal 快速结账 NVP API 开发指南
每个响应都包含 ACK 字段。如果 ACK 字段的值是 Success 或 SuccessWithWarning,您就应处
理 API 响应字段。对于成功的响应,您可忽略 BUILD 字段之前的所有字段(包括 BUILD 字段)。
重要字段在 BUILD 字段之后开始。
有关每种方法可能的成功响应字段,请参阅附录 A“NVP API 方法和字段参考”。如何处理这
些字段取决于您调用的特定 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=severityC
ode
可能返回多
个错误。每
组错误都具
有不同的数
字后缀,以 0
开始,每个
错误增加 1。
对于可能的出错原因以及如何纠正,请参阅附录 B“错误消息参考”中关于特定错误代码、
短消息及长消息的说明。
ACK 参数值
下表列出了 ACK 参数的值。
ACK 参数值
响应类型
值
成功响应
Success
SuccessWithWarning
错误响应
Failure
FailureWithWarning
Warning
5
PayPal 快速结账 NVP API 开发指南
URL 编码
请求和响应已经过 URL 编码。URL 编码确保您可传输特殊字符、URL 中不允许的字符以及在
URL 中具有特殊含义的字符,例如等号和与号。例如,以下 NVP 字符串:NAME=Robert
Moore&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)
Classic ASP
编码
Server.URLEncode
解码
无内置函数。Internet 上有若干实施示例
Java
编码
java.net.URLEncoder.encode
解码
java.net.URLDecoder.decode
PHP
编码
urlencode()
解码
urldecode()
ColdFusion
编码
URLEncodedFormatstring [, charset ]
解码
URLDecodeurlEncodedString[, charset])
- 1
- 2
- 3
前往页