指南
状态页面Dashboard预约演示
开始键入搜索...

存储的证书

根据处理payment 的方式和时间，payment 可以来自客户发起的交易 (CIT) 或商家发起的交易 (MIT)。

为确保负责任地存储和使用持卡人信息，威士公司和万事达公司制定了有关存储凭证的指导原则和规定。

我们简化了您遵守这些计划规则的流程，使您能够在 Yuno 中安全地存储银行卡详细信息，以备将来使用，同时保持合规性。

⚠️

重要： 这与订阅不同

想想谁能控制复发：

  • 存储凭证：您可以控制递归，并负责按照自己的计划和递归逻辑发送每笔交易。
  • 订阅 API：由 Yuno 控制。您只需提供一次说明，Yuno 就会自动代表您发送交易。请参阅订阅。
  • 分类
  • 一般考虑因素
  • 创建payment
  • 订阅协议 ID
  • 网络交易 ID

分类

类别客户发起的交易 (CIT)商家发起的交易（MIT）
定义客户发起的交易，如在线和店内购物或 ATM 取款。由商家或服务提供商发起的交易，客户不主动参与。
实例包括网上购物、店内购物和 ATM 取款。包括定期付款、自动续订和定期账单。
认证通常需要持卡人验证，以确保安全。设置时需要初始客户身份验证，后续交易可能需要根据安全法规和发卡机构政策进行额外身份验证。

确定交易是由商家发起还是由客户发起，对安全性、用户体验、欺诈防范和监管合规性都有重大影响。这可确保为所有相关方提供高效、安全的payment 流程。

一般考虑因素

  • 责任：在欧盟 PSD2 法规下的强客户身份验证（SCA）背景下，CIT 通常比 MIT 要求更高的身份验证。
  • 频率：MIT 交易通常是经常性和周期性的，而 CIT 则更多是基于客户行为的临时事件。

创建处理类型付款

要指定 payment 处理类型时，使用 stored_credentials 结构内的 payment_method.detail.card 创建payment时。

参数类型说明
reason枚举表示存储交易凭证的原因。
CARD_ON_FILE
SUBSCRIPTION
UNSCHEDULED_CARD_ON_FILE
usage枚举信用卡可以在有或没有初始payment的情况下存储。该字段表示金库令牌/网络令牌是否首次使用或重复使用。
FIRST
USED
subscription_agreement_id字符串与客户签订协议的 ID，某些市场（如墨西哥）必须使用。
network_transaction_id字符串Visa/Mastercard 在初始payment响应中提供的 ID，强烈建议今后在商家发起的交易 (MIT) 中使用。
❗️

关键：填写所有必填字段

  • 在处理 CIT 和 MIT 交易时，必须正确填写 usage, reason和 network_transaction_id 字段。未正确填写这些字段可能导致 批准率下降 和 退款纠纷损失.
  • 有些提供商（如 Adyen）要求 reason 字段在整个交易生命周期内保持一致。如果您的第一个交易（usage=FIRST) 的使用 reason=SUBSCRIPTION，所有后续交易 (usage=USED) 也必须使用 reason=SUBSCRIPTION.

存储凭证的原因

原因说明
CARD_ON_FILE在持卡人在场的情况下，客户使用之前注册的信用卡发起payment 。允许客户一键payment ，实现无摩擦payment 体验。
SUBSCRIPTION用于商家主动付款，作为订阅的一部分。这并不会创建新的订购--请使用订购应用程序接口（Subscription API）进行自动循环计费。
UNSCHEDULED_CARD_ON_FILE商家使用存储的信用卡详细信息发起的payment ，与订购计划或金额无关。Payment 可在任何时间进行。

Request 示例

curl --request POST \
     --url https://api-sandbox.y.uno/v1/payments \
     --header 'X-Idempotency-Key: <Your idempotency-key>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'private-secret-key: <Your private-secret-key>' \
     --header 'public-api-key: <Your public-api-key>' \
     --data '
{
    "description": "Test",
    "account_id": "{{account-code}}",
    "merchant_order_id": "0000023",
    "country": "DE",
    "merchant_reference" : "reference-{{$randomUUID}}",
    "amount": {
        "currency": "EUR",
        "value": 5000
    },
    "customer_payer": {
        "id":"967ecd18-d898-4b88-9400-dd5b01b18edc"
    },
    "workflow": "DIRECT",
    "payment_method": {
        "type":"CARD",
        "vaulted_token": "eb8caa17-6407-457b-960e-125d8d7a90c1",
        "detail": {
           "card": {
               "stored_credentials":{
                  "reason":"CARD_ON_FILE",
                  "usage": "USED",
                  "network_transaction_id":"583103536844189"
              }
           }
        }
    }
}
'

认购协议

对于某些市场（例如 MX）和支付处理程序，在进行与订阅相关的支付时，需要在支付请求中指定与客户签订的协议的 ID，以确保正确处理。为此，我们启用了 subscription_agreement_id 字段内的 stored_credentials 结构，允许您与客户共享所达成的协议。

📘

备注

"(《世界人权宣言》) subscription_agreement_id 和 network_transaction_id 是独立的字段。包括一个 subscription_agreement_id 并不能取代 network_transaction_id.在适用情况下，应同时提供这两种信息，以确保最佳审批率和退款保护。

"payment_method": {
        "type":"CARD",
        "vaulted_token": "eb8caa17-6407-457b-960e-125d8d7a90c1",
        "detail": {
           "card": {
               "stored_credentials":{
                  "reason":"CARD_ON_FILE",
                  "usage": "USED",
                  "subscription_agreement_id":"AA0001",
                  "network_transaction_id":"583103536844189"
              }
           }
        }
    }

网络交易 ID

网络交易 ID 是银行卡网络分配给交易的唯一标识符。它用于跟踪和参考特定交易，特别是在经常性payment 情况下，确保整个payment 周期的一致性和可追溯性。

如果交易是客户发起的 (CIT)，网络交易参考将在 card.stored_credentials.network_transaction_id 字段。该字段代表威士卡的交易 ID 和万事达卡的跟踪 ID，建议用于今后的订购付款。

"payment_method": {
        "type":"CARD",
        "vaulted_token": "eb8caa17-6407-457b-960e-125d8d7a90c1",
        "detail": {
           "card": {
               "stored_credentials":{
                  "reason":"CARD_ON_FILE",
                  "usage": "USED",
                  "network_transaction_id":"583103536844189"
              }
           }
        }
    }

使用方法

我们将 network_transaction_id 与 vaulted_token 因此，您不必为每种情况管理逻辑。我们将在创建payment 时执行关联：

  • Payment 方式:
    • 一张卡片 vaulted_token或
    • 卡数据与 vault_on_success 设为 true
  • 存储的凭证:
    • usage 设为 FIRST
⚠️

使用时 vault_on_success = true 在直接集成中，您必须先创建客户并传递其 customer_payer.id 在付款请求中。直接发送客户信息不会在Yuno系统中创建客户，因此无法存储卡片信息，也无法 vaulted_token 将被退回。

如果您已经拥有 network_transaction_id 则可在相应字段中将其包含在payment 中。如果没有，对于 MIT 付款（使用 stored_credentials.usage=USED)，我们将发送 network_transaction_id 与 vaulted_token 给供应商。

❗️

记住在 stored_credentials 部分，因为我们会触发 network_transaction_id 基于这些字段的逻辑。

约 2 个月前已更新