PayKKa Docs for Payments
v1.2 🇨🇳 (Current Release)
  • v1.2 🇨🇳 (Current Release)
  • v1.0 🇨🇳 (Release)
  1. 支付方式
PayKKa Docs for Payments
v1.2 🇨🇳 (Current Release)
  • v1.2 🇨🇳 (Current Release)
  • v1.0 🇨🇳 (Release)
  • 接入流程
  • 变更记录
  • 支付产品
    • 支付方式
    • API 支付
    • 收银台
  • 支付方式
    • Google Pay™
    • Apple Pay
  • API 参考
    • 开始
    • API认证
    • 系统响应码
    • 交易错误码
    • 交易
      • 发起交易
      • 交易查询
      • 交易请款
      • 交易撤销
      • token查询
      • token删除
      • 循环交易协议取消
      • 获取ApplePay会话
    • 收银台
      • 收银台创建
      • 收银台查询
    • 退款
      • 退款
      • 退款查询
    • 通知Webhook
      • 交易结果通知
      • 退款结果通知
  • 前端接入
    • PayKKa Checkout UI Component 使用文档
    • Fraud Detection SDK 使用文档
    • Encrypted Card 使用
  • 数据模型
    • Schemas
      • 响应
      • QueryPayResultReqDto
      • CardEncryptRespDto
      • WebAuthRequest
      • QueryOpenidRequest
      • OrderPayQrcodeRequest
      • EntryPayQrcodeRequest
      • CheckoutIdDto
      • BillRespDto
      • PaymentInfoRespDto
      • PaymentMethodRespDto
      • PaymentMethodsRespDto
      • TokenRespDto
      • BillReqDto
      • BrowserReqDto
      • CheckoutPaymentsReqDto
      • PaymentInfoReqDto
      • CheckoutPaymentQueryDto
      • PaymentMethodsReqDto
      • TokenAuthenticationDto
      • BalanceRespInPaymentsQuery
      • BalanceRespInPayments
      • PaymentLinkSessionReqDto
      • PaymentLinkPaymentsReqDto
      • PaymentLinkPaymentQueryDto
      • PaymentLinkIdDto
      • PaymentLinkQueryRespDto
      • SessionAppleApyReqDto
      • TokenRemoveReqDto
      • QueryTokenReqDto
      • PaymentCardInfoDto
      • QueryTokenRespDto
      • GoodsReqDto
      • SessionCreateReqDto
      • SessionPaymentInfoReqDto
      • ShippingReqDto
      • SessionRespDto
      • SessionQueryReqDto
      • RefundReqDto
      • RefundRespDto
      • RecurringCancelReqDto
      • CardInfoRespDto
      • QueryAddressStyleRespDto
      • CheckoutBillReqDto
      • CheckoutPaymentInfoReqDto
      • PaymentLinkPaymentInfoReqDto
      • SessionAuthenticationReqDto
      • SessionBillReqDto
      • SessionGoodsReqDto
      • SessionShippingReqDto
      • QueryRefundReqDto
      • AuthenticationRecordRespDto
      • QueryPaymentsReqDto
      • CheckoutQueryRespDto
      • CheckoutPaymentsRespDto
      • PaymentLinkPaymentsRespDto
      • PaymentsReqDto
      • AuthenticationRecordDto
      • PaymentsRespDto
      • AuthenticationReqDto
      • RefundNotifyReqDto
      • PaymentsNotifyReqDto
      • PaymentsVoidReqDto
      • PaymentsCaptureReqDto
      • CheckoutBrowserReqDto
      • SessionQueryRespDto
      • PaymentsQueryRespDto
      • BalanceResp
      • QueryPayResultRespDto
      • QueryMerchRequest
      • QueryMerchResponse
      • WebAuthResponse
      • QueryOpenidResponse
      • EntryPayQrcodeResponse
      • CardOrgEnum
      • ChannelConfig
      • SessionField
      • CheckoutThemeRespDto
      • CountryEnum
      • GoodsRespDto
      • Money
      • PaymentMethodEnum
      • PaymentTypeEnum
      • SessionModeEnum
      • SessionStatusEnum
      • CheckoutAuthenticationRecordDto
      • SessionApplePayReqDto
      • FramesLoadReqDto
      • FramesLoadRespDto
      • SuperPaymentMethodsRespDto
      • CardEncryptReqDto
      • CardInfoRespInCard
      • AuthenticationRecordRespInPaymentsQuery
      • CardInfoRespInPaymentsQuery
      • PaymentInfoRespInPaymentsQuery
      • DeviceOsEnum
      • PaymentDeviceTypeEnum
      • AuthenticationRecordRespInPayments
      • CardInfoRespInPayments
      • PaymentInfoRespInPayments
      • TerminalTypeEnum
      • AuthenticationRecordInNotify
      • BalanceRespInNotify
      • CardInfoRespInNotify
      • SessionAuthenticationRecordDto
      • PaymentInfoRespInNotify
      • SessionOrderStatusEnum
      • PaymentModeEnum
      • ApplePaySessionRespDto
      • BatchQueryDictReqDto
      • BatchQueryDictRespDto
      • DataDictResp
      • DataDictValueItem
      • OldPlaceOrderQrcodeRequestV2
      • OldPlaceOrderQrcodeResponseV2
      • OldPosQueryOrderRequestV2
      • OldPosQueryOrderResponseV2
      • OldCollectPayQrcodeRequestV2
      • OldCollectPayQrcodeResponseV2
      • OldPlaceOrderQrcodeRequest
      • OldPlaceOrderQrcodeResponse
      • OldPosQueryOrderRequest
      • OldPosQueryOrderResponse
      • OldCollectPayQrcodeRequest
      • OldCollectPayQrcodeResponse
      • PlaceOrderQrcodeRequest
      • PlaceOrderQrcodeResponse
      • DeviceActivateRequestV2
      • DeviceActivateResponseV2
      • DeviceActivateRequest
      • DeviceActivateResponse
      • CollectPayQrcodeRequest
      • CollectPayQrcodeResponse
      • CurrencyEnum
      • RefundQueryReqDto
      • WechatCallbackRespDto
      • AlipayCallbackRespDto
      • Result
      • CardTokenUsageEnum
      • ChallengeIndicatorEnum
      • ApiPaymentMethodEnum
      • CustomerReqDto
      • ThreedSecureExemptionEnum
      • GatewayOrderStatusEnum
      • SessionCustomerReqDto
      • PaymentsQueryReqDto
      • GatewayRefundOrderStatusEnum
      • QueryRefundResultReqDto
      • QueryRefundResultRespDto
      • QueryTransResultReqDto
      • AddressStyleDto
      • ThreedSecureModeEnum
      • DataDictRespDto
      • PagedDataDictValueItem
      • DeviceSignInReqDto
      • DeviceSignInRespDto
      • PosCurrency
      • DeviceSignInRequestV2
      • DeviceSignInResponseV2
      • DeviceSignInRequest
      • DeviceSignInResponse
  1. 支付方式

Apple Pay

介绍#

Apple Pay 具有以下特点:
支持国家地区支持币种常规支付循环支付授权捕获部分捕获撤销部分撤销退款部分退款拒付
全球绝大多数币种✅✅✅✅✅✅✅✅✅✅

一. 使用你自己的Apple证书#

如果商家的开发能力非常强,PayKKa允许您使用自己的证书来解密来自Apple Pay的payment token。
在开始之前,您应该准备进行以下步骤:
1.
创建一个Apple Pay的开发者账号,如果您在不同的地区进行展业,同一个账号不能在多个不同地区同时使用,需要在不同的地区分别创建账号。
2.
您登录到开发者账号后,创建一个商户标志符(merchant identifier),该标志符要求唯一识别。
3.
创建一个用于加密从Apple返回的payment token的支付处理证书(payment processing certificate),这个证书与第二步中商户标志符进行关联。
4.
准备一个域名,在Apple中进行验证, 该域名必须以https开头。登录到开发者账号后,进入商户域名部分,输入域名名称,保存后。可以下载一个Apple的域名关联文件,将这个文件上传到域名所在服务器指定目录下,具体路径可参考 https://yourdomain.com/.well-known/apple-developer-merchantid-domain-association。 当上传到该目录后,再进行Verify操作。如果提示OK,说明域名绑定成功。
5.
创建一个用于拉起Apple Pay会话到认证证书。打开终端,输入以下命令,
然后进入商家证书部分,上传uploadMe.csr文件,然后可以下载到一个merchant_id.cer证书文件,然后将该证书文件进行转换为.pem。输入以下命令,
6.
测试验证你的Apple Pay会话证书是否正确,可输入以下命令,
如果返回完整的会话信息,说明商家证书创建成功,可进行后续集成Apple Pay的操作。

二. 使用PayKKa的Apple证书#

如果您想快速地集成Apple Pay功能,可以选择使用PayKKa的Apple证书。PayKKa已经申请成为Apple Pay的PSP身份,允许接入不同的商家来集成Apple Pay。
在开始之前,您应该准备以下步骤:
1.
在PayKKa商家后台注册账号,并开通Apple Pay的支付方式,通过提交资料,审核,KYC等认证流程。
2.
如果您选择在自己的付款页面集成Apple Pay, 需要提供该页面所在的域名,并进行认证。在商家后台下载PayKKa的域名关联文件 apple-developer-merchantid-domain-association。商家需要将该文件上传到你的域名服务器指定目录下,具体路径可参考 https://yourdomain.com/.well-known/apple-developer-merchantid-domain-association。然后PayKKa会向Apple 发起请求,添加你的域名。接着会向你的服务器发送请求进行验证。在验证OK后,则表明域名绑定成功。如果商家选择使用PayKKa的收银台,就可以跳过上述操作步骤。
3.
如果商家选择自己的页面集成Apple Pay,则需要集成Apple Pay的SDK,可参考以下代码:
具体使用步骤,可参考PayKKa Checkout UI Component 使用文档 - PayKKa Docs for Payments

三. 通过API方式接入Apple Pay#

您可以通过API的方式,接受Apple Pay支付,并构建自己的付款页面,以完全控制自己的结账流程。目前暂不支持Union Pay的借记卡或者贷记卡。PayKKa接受您自行解密和由我们解密Apple Pay的Payment token两种方式。这两种方式在集成上有所差异,具体可参考以下:

商家解密#

如果您的开发能力很强,自行完成了Apple Pay的payment token的解密。那么只需要发起PayKKa的支付API请求,传递解密后的交易卡信息,即可完成交易。
1.
调用[发起交易]接口
{
  "payment": {
		"payment_method": "APPLE_PAY",
		"exp_year": "2027",
		"exp_month": "08",
		"holder_name": "Ocie Vititoe",
		"card_no": "5204240493889658",
		"token_authentication": {
			"cryptogram": "ALbOGff2RLbTADtP3BuIAoABFA==",
			"token_format": "cryptogram_3ds",
                        "eci": "07"
		}
	}
}
解密的明文信息中 exp_year , exp_month, card_no, cryptogram , token_format 必传,其中token_format 固定cryptogram_3ds ,其他字段如果有返回,请一同传入。

PayKKa解密#

如果您选择由PayKKa来解密,那意味着使用PayKKa的Apple证书。在PayKKa内部会进行自动解密,发起支付过程,您只需要传递加密的payment token。您需要对接PayKKa的Apple Pay的会话接口,用于开启当前Apple Pay的支付操作。然后当您收到Apple Pay返回的payment token后,再是向PayKKa发起支付操作,完成付款。
1.
调用[获取ApplePay会话]接口
{
  "merchant_id": "商户号" # 必填
  "display_name": "YOUR_DOMAIN_NAME" # 展示给顾客的商户名称, 空则默认由PayKKa设置
}
{
  "ret_code": "",
  "ret_msg": "",
  "data": "BASE_64_ENCODED_DATA"
}
data 返回的是发起Apple Pay的会话信息,经过了Base64编码
2.
调用[发起交易]接口
{
  "payment": {
		"payment_method": "APPLE_PAY",
		"store_payment_method": true,
		"token_usage": "CARD_ON_FILE",
		"shopper_reference": "HDJSVXDKRO",
		"token_data": "QWIwMmI0YzAhQlFBQkFnQjMv..."
	}
}

四. 通过Hosted Payment Page方式接入Apple Pay#

如果您使用PayKKa的托管结账页面来接入Apple Pay, 只需要在开通商户过程中支持Apple Pay并接受Apple Pay支付, PayKKa将在幕后处理与Apple Pay的所有交易。这种集成方案,您不需要添加域名,最为便捷。您需要调用发起收银台请求,获取PayKKa的收银台的跳转地址。
1.
调用[收银台创建]接口
{
    "version": "v1.0",
    "merchant_id": "18000000000000",
    "payment_type": "PURCHASE",
    "trans_id": "t202311081113",
    "timestamp": 1700805506000,
    "currency": "USD",
    "amount": 1250,
    "session_mode": "HOST",
    "display_merchant_name": "PayKKa Merchant",
    "display_locale": "zh-CN",
    "allowed_payment_methods": [
        "APPLE_PAY"
    ]
}
其中指定session_mode 字段值为HOST, allowed_payment_methods允许支持APPLE_PAY。

五. 通过Embedded Element方式接入Apple Pay#

您可以在自己的付款页面集成Apple Pay 付款元素, 这种解决方案让您的客户不需要跳转到第三方付款页面,就可以在您的当前页面完成支付,体验更丝滑。但是这种方式,您需要提供您的付款页面所在的域名,在PayKKa上进行绑定验证。操作步骤参考使用PayKKa的Apple证书。
1.
引入PayKKa Checkout UI Component组件库
具体使用步骤可参考PayKKa Checkout UI Component 使用文档 - PayKKa Docs for Payments
2.
调用[收银台创建]接口
{
    "version": "v1.0",
    "merchant_id": "18000000000000",
    "payment_type": "PURCHASE",
    "trans_id": "t202311081113",
    "timestamp": 1700805506000,
    "currency": "USD",
    "amount": 1250,
    "session_mode": "EMBEDDED",
    "display_merchant_name": "PayKKa Merchant",
    "display_locale": "zh-CN",
    "allowed_payment_methods": [
        "APPLE_PAY"
    ]
}
其中指定session_mode 字段值为EMBEDDED, allowed_payment_methods允许支持APPLE_PAY。

六. 测试#

Apple Pay 提供了sandbox 环境(Sandbox Testing - Apple Pay),您可以在自己钱包中添加测试卡来模拟交易。
您需要准备一台兼容的Apple 设备(Devices compatible with Apple Pay - Apple Support)进行测试。
修改于 2025-03-17 10:16:18
上一页
Google Pay™
下一页
开始
Built with