对接苹果支付退款退单接口
前言
一般而言，我们其实很少对接退款接口，因为退款基本都是商家自己决定后进行操作的，但是苹果比较特殊，用户可以直接向苹果发起退款请求，苹果觉得合理会退给用户，但是目前公司业务还是需要对接这个接口，可能是以后为了对账之类使用的吧
本来对接api也没啥好说的，但是由于苹果官方是英文的，考虑到大部分人可能还是懒得找英文文档，所以进行了整理归档(我自己也是百度整理的...)
以下为参考的一些地址，2023-11-22记录，目前是有限的，以后不确定..请知悉
参考对接地址： 苹果（apple）支付退款通知、api_苹果支付api_Arhhhhhhh的博客-CSDN博客
官网地址：
官网对接地址
主动通知地址：Get Refund History | Apple Developer Documentation
被动通知地址：Handling refund notifications | Apple Developer Documentation
必知
这里主要介绍被动接收的(连接需要支持https)，因为这种不是很好性能，主要是由于主动查询没有条件可以终止，所以选择用被动的，但是也会把相应工具类放上来，方便使用
对接步骤
配置通知URL
在 App Store Connect 进行配置，地址为：https://appstoreconnect.apple.com/login，由于我没有账号，所以是别人帮忙配的，如果不知道在哪配置可以参考这篇文章
苹果iOS内购三步曲：App内退款、历史订单查询、绑定用户防掉单！--- WWDC21 - 掘金
我这里使用的是V2版本的，V1是明文的，不太安全，所以我这里采用了V2版本
引入依赖
加解密需要引入工具包进行处理，以下是maven的坐标
com.auth0 java-jwt 3.8.1
编写工具类
这一步最重要，这里直接放代码，到时你们可以直接复制使用
主动调用工具类
public class AppStoreReturnUtil {
//退款api正式环境
private static final String APP_STORE_RETURN = "https://api.storekit.itunes.apple.com/inApps/v2/refund/lookup/{originalTransactionId}";
//退款api沙箱环境
private static final String APP_STORE_SANDBOX_RETURN = "https://api.storekit-sandbox.itunes.apple.com/inApps/v2/refund/lookup/{originalTransactionId}";
/**
* 生成token
* @return
* @throws Exception
*/
private static String generateJwtToken() throws Exception {
Map headers = new HashMap<>();
// apple指定ES256算法
headers.put("alg", "ES256");
// 密钥ID
headers.put("kid", "你的kid");
// jwt格式
headers.put("typ", "JWT");
return JWT.create()
.withHeader(headers)
// issId：见apple connect后台右上角
.withIssuer("你的issId")
// 签名日期
.withIssuedAt(new Date())
// 失效日期：最晚一个小时，否则报错401
.withExpiresAt(DateUtils.addHours(new Date(), 1))
// 目标接收者，固定值
.withAudience("appstoreconnect-v1")
// 包名，bundleId
.withClaim("bid", "你的bundleId")
// 签名密钥，需要用到apple connect下载p8文件
.sign(Algorithm.ECDSA256(null, (ECPrivateKey) getPrivateKey("p8文件路径")));
}
/**
* 获取私钥
* @param fileName apple connect下载的p8文件路径
* @return
* @throws Exception
*/
private static PrivateKey getPrivateKey(String fileName) throws Exception {
String content = new String(Files.readAllBytes(Paths.get(fileName)), StandardCharsets.UTF_8);
try {
String privateKey = content.replace("-----BEGIN PRIVATE KEY-----", "")
.replace("-----END PRIVATE KEY-----", "")
.replaceAll("\\s+", "");
KeyFactory kf = KeyFactory.getInstance("EC");
return kf.generatePrivate(new PKCS8EncodedKeySpec(Base64.getDecoder().decode(privateKey)));
} catch (InvalidKeySpecException e) {
throw new RuntimeException("Invalid key format");
}
}
//任何http请求工具类都可以
private static RefundHistResponseVO getRefundHist() throws Exception {
String token = generateToken();
HttpHeaders header = new HttpHeaders();
header.set("Authorization", "Bearer "+ token);
RequestEntity> requestEntity = new RequestEntity<>(header, HttpMethod.GET, URI.create("https://api.storekit-sandbox.itunes.apple.com/inApps/v2/refund/lookup/2000000308586738"));
ResponseEntity exchange = restTemplate.exchange(requestEntity, RefundHistResponseVO.class);
return exchange.getBody();
} 这里有几个注意的点，如下
1. getRefundHist 需要基于http工具去发送请求，你可以自己找你们项目中的，或者自己写一个
2. kid、issId、bundleId、p8文件都是你自己账号的，如果你不知道可以问ios或者产品经理要
3. originalTransactionId就是你之前下单时苹果返回的，所以这个数据你们之前必须要有
到此为止，剩下的就是你自己写代码去请求就行了
被动接收
苹果返回数据格式
格式如下(真实的很长，这里是为了你能看懂才故意弄短)
{"signedPayload":"BaR1VnUkdWMlpXeHZjR1Z5SUZKbGJHRjBh"}如果你是用Java SpringBoot开发的话，可以直接这样接收（也就是用@RequestBody即可）
@RestController
@RequestMapping("app/store")
@Slf4j
public class AppStoreMsgController {
@PostMapping("/notify")
public String appStoreMsgNotify(@RequestBody AppStoreNotifyPayLoadDto appStoreNotifyPayLoadDto) {
log.info("appStoreNotifyPayLoadDto{}", JsonUtils.Object2Json(appStoreNotifyPayLoadDto));
return MSG.SUCCESS(result);
}
}@Data
public class AppStoreNotifyPayLoadDto implements Serializable {
private static final long serialVersionUID = 1L;
private String signedPayload;
}被动接收工具类
@Slf4j
public class AppStoreReturnUtil {
/**
* 验证签名并返回解析数据
* @param jws
* @return
* @throws CertificateException
*/
public static AppStoreNotifyDto verifyAndGet(String jws) throws CertificateException {
DecodedJWT decodedJWT = JWT.decode(jws);
// 拿到 header 中 x5c 数组中第一个
String header = new String(java.util.Base64.getDecoder().decode(decodedJWT.getHeader()));
String x5c = JSONObject.parseObject(header).getJSONArray("x5c").getString(0);
// 获取公钥
PublicKey publicKey = getPublicKeyByX5c(x5c);
// 验证 token
Algorithm algorithm = Algorithm.ECDSA256((ECPublicKey) publicKey, null);
try {
algorithm.verify(decodedJWT);
} catch (SignatureVerificationException e) {
log.error("解密苹果数据失败", e);
throw new AppException("解密苹果数据失败");
}
// 解析数据
String decodeString = new String(java.util.Base64.getDecoder().decode(decodedJWT.getPayload()));
return JSON.parseObject(decodeString, AppStoreNotifyDto.class);
}
/**
* 解析事务数据
* @param appStoreNotifyDto
* @return
*/
public static AppStoreDecodedPayloadDto parseTransactionInfo(AppStoreNotifyDto appStoreNotifyDto) {
DecodedJWT decode = JWT.decode(appStoreNotifyDto.getData().getSignedTransactionInfo());
String decodeString = new String(Base64.getDecoder().decode(decode.getPayload()));
return JSON.parseObject(decodeString, AppStoreDecodedPayloadDto.class);
}
/**
* 获取公钥
* @param x5c
* @return
* @throws CertificateException
*/
private static PublicKey getPublicKeyByX5c(String x5c) throws CertificateException {
byte[] x5c0Bytes = java.util.Base64.getDecoder().decode(x5c);
CertificateFactory fact = CertificateFactory.getInstance("X.509");
X509Certificate cer = (X509Certificate) fact.generateCertificate(new ByteArrayInputStream(x5c0Bytes));
return cer.getPublicKey();
}
}
这些都是固定写法，放上去就行了，没啥好说的，相关的java Bean也贴出来吧，放在下面
/**
* zxc_user
* time: 2023-11-17 15:34:47
* @description: 解密核心数据
*
* 参考地址: https://developer.apple.com/documentation/appstoreservernotifications/jwstransactiondecodedpayload?language=objc
*/
@Data
public class AppStoreDecodedPayloadDto implements Serializable {
private static final long serialVersionUID = 1L;
///退款订单必存的字段
/**
* 应用的bundle标识符
*/
private String bundleId;
/**
* 与price参数相关联的三个字母的ISO 4217货币代码。此值仅在存在price时才存在
*/
private String currency;
/**
* 服务器环境，沙箱或生产环境。 sandbox or production
*/
private String environment;
/**
* 包含优惠代码或促销优惠标识符的标识符。
*/
private String offerIdentifier;
/**
* 表示促销优惠类型的值
*/
private String offerType;
/**
* UNIX时间，以毫秒为单位，表示原始事务标识符的购买日期。
*/
private String originalPurchaseDate;
/**
* 原始购买的交易标识符。
*/
private String originalTransactionId;
/**
* 一个整数值，表示您在App Store Connect中配置的应用内购买或订阅报价的价格乘以1000，并在购买时系统记录。有关更多信息，请参阅价格。currency参数表示此价格的货币。
*/
private String price;
/**
* 应用内购买的产品标识符。
*/
private String productId;
/**
* 用户购买的消耗品数量。
*/
private String quantity;
/**
* UNIX时间，以毫秒为单位，App Store在过期后向用户帐户收取购买、恢复产品、订阅或续订费用。
*/
private String purchaseDate;
/**
* UNIX时间，以毫秒为单位，应用商店将交易退款或从家庭共享中撤销交易
*/
private String revocationDate;
/**
* App Store退还交易或从家庭共享中撤销交易的原因。
*/
private String revocationReason;
/**
* 事务的唯一标识符。
*/
private String transactionId;
/**
* 购买事务的原因，这表明它是客户购买还是系统启动的自动续订订阅的续订。
*/
private String transactionReason;
/**
* 应用内购买的类型。
*/
private String type;
///跟订阅相关/
/**
* 订阅到期或更新的UNIX时间，以毫秒为单位。 跟订阅相关
*/
private String expiresDate;
/**
* 一个布尔值，指示客户是否升级到另一个订阅。 跟订阅相关
*/
private boolean isUpgraded;
/**
* 订阅服务使用的付费模式，如免费试用、按需付费或预先付费 ，跟订阅相关
*/
private String offerDiscountType;
/**
* 订阅所属的订阅组的标识符。 跟订阅相关
*/
private String subscriptionGroupIdentifier;
///其他相关/
/**
* 您在购买时创建的UUID，它将交易与您自己服务上的客户关联起来。如果你的应用没有提供appAccountToken，这个字符串是空的。更多信息请参见appAccountToken(_:)。
*/
private String appAccountToken;
/**
* 一个字符串，描述该事务是由客户购买的，还是通过家庭共享提供给客户
*/
private String inAppOwnershipType;
/**
* UNIX时间，以毫秒为单位，应用商店签署JSON Web签名(JWS)数据的时间。
*/
private String signedDate;
/**
* 三个字母的代码，表示与购买的App Store店面相关的国家或地区。
*/
private String storefront;
/**
* 一个apple定义的值，唯一标识与购买相关的App Store店面。
*/
private String storefrontId;
/**
* 跨设备订阅购买事件的唯一标识符，包括订阅续订。
*/
private String webOrderLineItemId;
}/**
* zxc_user
* time: 2023-11-17 15:22:08
* @description: 苹果V2版本回调通知返回数据
*
*
* 参考官方地址: https://developer.apple.com/documentation/appstoreservernotifications/responsebodyv2decodedpayload?language=objc
*/
@Data
public class AppStoreNotifyDto implements Serializable {
private static final long serialVersionUID = 1L;
/**
* 回调类型, 最主要的,等于REFUND是眼用户退款事件
*
* 参考地址:https://developer.apple.com/documentation/appstoreservernotifications/notificationtype?language=objc
*/
private String notificationType;
/**
* 通知的唯一标识符。使用此值来标识重复的通知。
*/
private String notificationUUID;
/**
* 标识通知事件的其他信息。子类型字段仅用于特定的版本2通知。
*/
private String subtype;
/**
* 核心数据,退款信息之类的都在里面
*/
private AppStoreNotifyDataDto data;
private String summary;
/**
* 通知版本号,V2
*/
private String version;
/**
* UNIX时间，以毫秒为单位
*/
private String signedDate;
}操作步骤：
就是把AppStoreNotifyPayLoadDto对象里面的signedPayload传到AppStoreReturnUtil工具类的verifyAndGet即可，便可以获得基础数据
如果获取退款数据再调用一下AppStoreReturnUtil的parseTransactionInfo即可，
记得如果只是处理退款的需要注意一下AppStoreNotifyDto对象的notificationType类型当等于REFUND才是退款，其他的业务请参考官方文档，notificationType | Apple Developer Documentation
到这里就行了，剩下的就是你要处理的业务逻辑，每个人的可能不太一样，这里就不赘述了
两者对比
主动查询需要消耗你的性能，而且你不知道终止条件是啥，因为用户是随时可以向苹果发起退款申请的，虽然网上有人说下单后90天就不能，但是是不是也不确定....
其次主动查询需要那些kid，k8文件等数据记录(这里可以理解为私钥)，所以还是比较麻烦的
被动接收相对就非常方便了，只需要配置url，然后提供控制器接收数据即可，这里是不需要kid，k8文件那些的(这里我理解是公钥在jar包里面提供的）而且可以节省你服务器性能
所以我目前是选择了被动接收处理
设计模式使用
这里我是用了command进行设计的，目前还没整理文档，后续整理了可以放出来大家讨论讨论
有兴趣的可以参考我的另一篇文章 : 基于命令行模式设计退款请求处理-CSDN博客
结语
这里再次感谢开头放置的那些文章地址，说的挺详细了，因为我英文也不是很好，如果没有这些文章可能还挺麻烦
整个流程其实并不难，就是以前没接过苹果的，所以刚开始有点懵逼，不过真正搞懂了其实也就那样