Java 海外支付设计海外支付工具

转载

温柔一刀 2024-05-27 15:15:26

文章标签 Java 海外支付设计支付测试 API 参数说明 Express 文章分类 Java 后端开发

前言

概述

Paypal为商家提供了多种支付对接方式，其中Paypal Express Checkout最为常见、方便、以及自定义扩展性最强。下图是Paypal Express Checkout支付的一个标准时序图，注意这是一个纯技术层面的API调用流程，在此基础上，我们可以组合出三种Paypal通用的用户支付体验：

快捷支付，直接去Paypal付款并使用Paypal上存储的地址发货。很明显，Paypal希望把自己打造成一个用户中心，也花了血本来推广这种方式，具我所知，该方式也是海外用户使用占比最高的。

标准支付，就像我们国内的天猫淘宝一样，填好了收件地址，完了再去支付。

游客支付，或称之为信用卡支付。当然信用卡不是Paypal强项，Paypal跟支付宝一样充当的是银行与用户之间的中间人角色。在信用卡领域，VISA是老大，同时信用卡涉及到相当高的安全层面风险，具体请参考我的另一篇文章海外支付：抵御信用卡欺诈的CyberSource 。

这三种支付方式都是基于下图中相同API，只是组合序顺或传递的参数稍有差异而以。

Java 海外支付设计海外支付工具_API

<图1.Paypal Express Checkout API接口>

吴剑

SetExpressCheckout

这是一个同步的API接口，将交易相关的所有数据首先通过SetExpressCheckout传递给Paypal，然后Paypal响应一个Token用于后续支付步骤，Token有效时间为3小时。

从接口前缀Set可以看出该接口是一个预交易步骤，好比我们去银行提大额现金，需要提前一天给银行通知，一来有助于银行备齐现金，二来也有助于交易安全，银行有充分时间评估交易的可靠性。后来在架构多平台的支付中心时，我也参考和使用了Paypal的这个结构。

SetExpressCheckout的参数很多，具体可参见Paypal官方文档：https://developer.paypal.com/docs/classic/api/merchant/SetExpressCheckout_API_Operation_NVP/ ，下面列出一些常用参数：

参数名称	参数说明
VERSION	接口版本号
METHOD	API名称，使用“SetExpressCheckout”即可
REQCONFIRMSHIPPING	商家是否需要买家在PayPal账户中的邮寄地址是已经被确认的地址
PAYMENTREQUEST_{m}_PAYMENTACTION	希望获取付款的方式
ALLOWNOTE	允许买方在PayPal结账页面上输入了一条文本信息给商家
LOCALECODE	PayPal付款页面显示语言的设置
RETURNURL	客户选择通过PayPal付款后其浏览器将返回的URL
CANCELURL	客户取消使用PayPal付款时返回的URL
EMAIL	结账时输入的买家电子邮件。 PayPal使用该值预填PayPal登录页面的PayPal会员注册部分
PAYMENTREQUEST_{m}_CURRENCYCODE	PayPal支持的交易币种中所列币种之一的三字符币种代码
PAYMENTREQUEST_{m}_AMT	交易总费用
PAYMENTREQUEST_{m}_ITEMAMT	订单所有物品的价格
PAYMENTREQUEST_{m}_SHIPPINGAMT	邮费总额
NOSHIPPING	是否不在PayPal付款页面展示邮寄地址
LANDINGPAGE	付款页面展示类型
SOLUTIONTYPE	结账流程的类型
HDRIMG	付款页面左上角显示的图片的URL
HDRBACKCOLOR	付款页面标题的背景色
PAYFLOWCOLOR	付款页面设置背景色
HDRBORDERCOLOR	付款页面标题边框颜色
L_PAYMENTREQUEST_{m}_NUMBER{n}	商品编号
L_PAYMENTREQUEST_{m}_NAME{n}	商品名称
L_PAYMENTREQUEST_{m}_QTY{n}	商品数量
L_PAYMENTREQUEST_{m}_AMT{n}	商品单价
PAYMENTREQUEST_{m}_INVNUM	商家订单编号

吴剑

GetExpressCheckoutDetails

如图1所示，在通过SetExpressCheckout接口获取到Token后，就需要跳转页面去Paypal了。用户在Paypal站点登录，确认支付信息，完成支付，最后Paypal将URL重定向回商家页面。

此时，我们可以获取用户在Paypal的相关信息。接口的详细参数可参见Paypal官方文档：https://developer.paypal.com/docs/classic/api/merchant/GetExpressCheckoutDetails_API_Operation_NVP/ ，下面列出常用的响应参数：

参数名称	参数说明
TOKEN	Token
PAYERID	Paypal用户ID
EMAIL	Paypal账号(Email)
PAYMENTREQUEST_{n}_SHIPTONAME	货运地址姓名
PHONENUM	货运地址电话
PAYMENTREQUEST_{n}_SHIPTOCOUNTRYCODE	货运地址国家ID
PAYMENTREQUEST_{n}_SHIPTOSTATE	货运地址省份
PAYMENTREQUEST_{n}_SHIPTOCITY	货运地址城市
PAYMENTREQUEST_{n}_SHIPTOZIP	货运地址邮编
PAYMENTREQUEST_{n}_SHIPTOSTREET	货运地址街道1
PAYMENTREQUEST_{n}_SHIPTOSTREET2	货运地址街道2

在此需要提一下的是，Paypal的接口非常灵活，它最大限度让商家可以使用相同的API来组合不同的支付逻辑以提高用户体验。比如在标准支付时，用户在商家网站填写并存储了邮寄地址，因此邮寄地址不需要与Paypal交互；而在快捷支付时，则可以通过GetExpressCheckoutDetails接口获取用户存储在Paypal上的地址信息并且在商家页面上显示给用户确认。

吴剑

DoExpressCheckoutDetails

DoExpressCheckoutDetails是Paypal实时交易的最后一步，它告诉并向Paypal确认最终的支付信息，当完成对它的调用，就代表了Paypal实时支付的完成，也代表Money从用户账户到了商家账户。详细官方API文档请参考：https://developer.paypal.com/webapps/developer/docs/classic/api/merchant/DoExpressCheckoutPayment_API_Operation_NVP/ ，如下列出了接口响应结果：

参数名称	参数说明
PAYMENTINFO_{n}_PAYMENTSTATUS	付款结果状态
PAYMENTINFO_{n}_CURRENCYCODE	成功币种
PAYMENTINFO_{n}_AMT	成功金额
PAYMENTINFO_{n}_TRANSACTIONID	Paypal交易ID

在快捷支付时，因为用户的邮寄地址存放在Paypal中，因此在GetExpressCheckoutDetails前，我们无法知道用户是哪个国家，也就不能计算出运费金额。所以通常在快捷支付时，我们会在GetExpressCheckoutDetails中获取用户邮寄地址来计算运费，在DoExpressCheckoutDetails中更新运费并确认最终金额。

吴剑

异步IPN通知

IPN全称为 Instant Payment Notification，在每笔交易完成后，Paypal可提供通知服务，即商家提供一个URL，Paypal向这个URL发送交易结果。这个过程是异步的，比如因为网络繁忙或你的服务器故障，IPN会在连续4天内最大15次持续发送结果，直到你收到为止。Paypal不建议在实时的支付流程中使用IPN，但我们可以使用IPN作为交易安全辅助或交易提醒等用途。

IPN开发概要：https://developer.paypal.com/webapps/developer/docs/classic/ipn/integration-guide/IPNIntro/

IPN详细参数：https://developer.paypal.com/docs/classic/ipn/integration-guide/IPNandPDTVariables/

在Paypal商户后台中开启IPN：用户信息 -> 即时付款通知

Java 海外支付设计海外支付工具_参数说明_02