保存卡详情

概述

Codapay 支持保存回头客的银行卡信息，以简化和加快结账流程。符合条件的商户和已启用此功能的卡组织可在托管支付页面上使用此功能。

启用此功能后，用户可以在结账时安全地存储银行卡，并在以后的交易中重复使用。

⚠️注意：此功能目前在印度和印度尼西亚不可用

资格和激活

只有已明确启用此功能的商户才能使用已保存的卡片功能。

要启用已保存卡片功能，请联系您的 Codapay 客户经理或支持团队。

如果商家未启用此功能，付款将正常处理，但不会保存银行卡信息。/v2.0/Payment/Component/init.json在这种情况下，响应中会返回警告信息。

用户识别与购物者地图

用户必须先登录您的平台，才能发起涉及保存或使用已保存银行卡的付款。

您需要partner_shopper_id在/v2.0/Payment/Component/init.json请求中传递一个字段。此字段代表您系统中的唯一用户 ID。它必须：

• 唯一标识单个用户

• 在所有会话和设备上保持一致

• 包含在所有已保存的卡片相关请求中

当添加第一张已保存的银行卡时，Codapay 会创建一个关联对象shopper_id，并将其链接到提供的关联对象partner_shopper_id。之后，所有已保存的银行卡都会与此关联对象关联shopper_id。

Codapay 利用此链接实现以下功能：

• 在下次结账时检索已保存的银行卡

• 将新保存的卡片附加到正确的用户

• 无需用户额外输入即可处理定期付款或商家发起的付款

集成概述

/v2.0/Payment/Component/init.json要在托管支付页面上启用已保存卡片功能，请在您的请求中包含以下字段：

enableSavePaymentMethod	Boolean	允许用户保存他们的银行卡。
displaySavedPaymentMethodList	Boolean	向用户显示之前保存的卡片
userInitiated	Boolean	指示用户是否参与支付流程
shopper	Object	识别用户并传递用于创建令牌的账单详细信息

购物者对象

shopper请求中的字段是/v2.0/Payment/Component/init.json一个键值对列表shopper.entry[]。

每个密钥对应于购物者身份或账单信息，用于检索或创建购物者个人资料并支持已保存的卡片功能。

partnerShopperId	Yes*	您系统的唯一用户 ID（区分大小写）
id	No	Codapay 签发shopper_id用于找回已知购物者
email	No	购物者电子邮件地址（创建新购物者时必需）
phoneNumber	No	购物者的电话号码
billingFirstName	No	购物者名字（用于计费和创建购物者信息）
billingLastName	No	购物者姓氏（账单处理和创建购物者信息时必需）
billingDocumentType	有条件的	某些市场要求提供的国家身份证件类型（例如，CPF）。
billingDocumentId	有条件的	国民身份证件的值，和documentType匹配
billingAddress	No	街道地址
billingCity	No	城市名称
billingRegion	No	州或省
billingCountry	No	ISO alpha-2 国家代码（例如，US）
billingZipCode	No	邮政编码

* 首次保存卡片时需要填写。

• 如果id存在，Codapay 会尝试检索与该关联的现有购物者shopper_id。

• 如果id未提供，则会创建一个新的购物者并将其与提供的购物者关联partnerShopperId。

• 除了此处记录的标准字段外，此处列出的字段也是必填项。

有关使用此结构的请求有效负载，请参阅下面的“场景和示例”部分。

场景和示例

本节概述了集成卡片保存功能时最常见的几种用例。每种用例都包含所需的参数和示例请求格式。

1. 首次用户 - 保存卡片选项

2. 老用户 – 显示已保存的卡片

3. 老用户 - 无需用户界面即可使用已保存的银行卡付款

4. 商户发起的付款 - 用户不在场

1. 首次用户 – 保存卡片选项

允许用户在结账时保存他们的银行卡信息。

要求

{
  "initRequest": {
    "country": 360,
    "payType": 400,
    "apiKey": "",
    "projectId": "31",
    "orderId": "20250611113402",
    "currency": 360,
    "items": [
      {
        "code": "12ds",
        "price": 10000.00,
        "name": "Star Diamond"
      }
    ],
    "profile": {
      "entry": [
        {
          "key": "user_id",
          "value": "105"
        }
      ]
    },
    "enableSavePaymentMethod": true,
    "displaySavedPaymentMethodList": true,
    "userInitiated": true,
    "shopper": {
      "entry": [
        {
          "key": "partnerShopperId",
          "value": "test_partner_123_Id"
        },
        {
          "key": "email",
          "value": "[e-mail]"
        }
      ]
    }
  }
}

回复

{
  "initResult": {
    "resultCode": 0,
    "txnId": 7503012627171645973
  }
}

商户通知

{
  "eventType": "PAYMENT_METHOD_ADDED",
  "timestamp": "2025-06-19T02:48:39.568907Z",
  "shopper": {
    "id": "shp_sg197861636b40021",
    "partner_shopper_id": "test_partner_123_Id",
    "email": "[e-mail]"
  },
  "paymentMethod": {
    "id": "pmt_sg1978616a1900024",
    "type": "card",
    "card": {
      "lastFour": "7263",
      "expirationMonth": "04",
      "expirationYear": "2027"
    }
  }
}

2. 老用户 – 显示已保存的卡片

显示之前保存的卡片供用户选择。

要求

{
  "initRequest": {
    "country": 360,
    "payType": 400,
    "apiKey": "",
    "projectId": "31",
    "orderId": "20250611113402",
    "currency": 360,
    "items": [
      {
        "code": "12ds",
        "price": 10000.00,
        "name": "Star Diamond"
      }
    ],
    "profile": {
      "entry": [
        {
          "key": "user_id",
          "value": "105"
        }
      ]
    },
    "enableSavePaymentMethod": true,
    "displaySavedPaymentMethodList": true,
    "userInitiated": true,
    "shopper": {
      "entry": [
        {
          "key": "id",
          "value": "shp_sg197861636b40021"
        }
      ]
    }
  }
}

回复

{
  "initResult": {
    "resultCode": 0,
    "txnId": 7503016855911597963
  }
}

3.【即将推出】老用户 – 无需用户界面即可使用已保存的银行卡付款

要求

{
  "initRequest": {
    "country": 360,
    "payType": 400,
    "apiKey": "",
    "projectId": "31",
    "orderId": "20250611113402",
    "currency": 360,
    "items": [
      {
        "code": "12ds",
        "price": 10000.00,
        "name": "Star Diamond"
      }
    ],
    "profile": {
      "entry": [
        {
          "key": "user_id",
          "value": "105"
        }
      ]
    },
    "enableSavePaymentMethod": true,
    "displaySavedPaymentMethodList": false,
    "userInitiated": true,
    "shopper": {
      "entry": [
        {
          "key": "id",
          "value": "shp_sg197861636b40021"
        }
      ]
    }
  }
}

回复

{
  "initResult": {
    "resultCode": 0,
    "txnId": 7503016855911597963
  }
}

4. [即将推出] 商户发起支付 - 用户不在场

要求

{
  "initRequest": {
    "country": 360,
    "payType": 400,
    "apiKey": "",
    "projectId": "31",
    "orderId": "20250611113402",
    "currency": 360,
    "items": [
      {
        "code": "12ds",
        "price": 10000.00,
        "name": "Star Diamond"
      }
    ],
    "profile": {
      "entry": [
        {
          "key": "user_id",
          "value": "105"
        }
      ]
    },
    "enableSavePaymentMethod": true,
    "displaySavedPaymentMethodList": false,
    "userInitiated": false,
    "shopper": {
      "entry": [
        {
          "key": "id",
          "value": "shp_sg197861636b40021"
        }
      ]
    }
  }
}

回复

{
  "initResult": {
    "resultCode": 0,
    "txnId": 7503016855911597963
  }
}