Logo
Section 1 / 2

创建和更新卡片

了解什么是 Marqeta 卡，以及如何创建和更新它。

导入

创建和更新卡片

了解什么是 Marqeta 卡，以及如何创建和更新它。

一张**卡**是用户拥有的支付卡，可以是实体卡或虚拟卡。卡片的行为和属性由与其关联的卡片产品对象定义。我们也可以在卡片对象中定义卡片的属性，此时卡片对象中的定义将优先于卡片产品对象中的定义。

在本课程中，我们将学习如何创建和更新 Marqeta 支付卡。

Course Image

创建一张卡

我们可以通过向 {BASE_URL}/cards 端点发送 POST 请求来创建一张 Marqeta 支付卡。可以在请求体中提供卡片的基本信息，包括邮寄信息。同时，还需要指定卡片所有者的 user_token 以及控制该卡片的卡片产品 card_product_token。因此，在创建新的 Marqeta 卡片之前，我们需要先创建一个用户和一个卡片产品。

请求参数

参数类型分类描述
show_cvv_numberboolean可选设置为 True 时，响应中会显示 CVV2 号码；否则为 False。注意：这是一个查询参数。
show_panboolean可选设置为 True 时，响应中会显示卡片的 PAN（主账户号码）；否则为 False。注意：这是一个查询参数。
card_product_tokenstring必需卡片产品的令牌
expediteboolean可选当需要请求履约提供商加快卡片处理速度时设为 True，否则为 False。默认值：False
metadataobject可选将客户提供的元数据添加到卡片中。允许最多 20 对键值对。格式示例："my_name_1": "my_value_1"
expiration_offsetobject可选定义卡片发行后有效的持续时间
tokenstring可选卡片的唯一令牌，长度为 1–36 个字符。注意：若未指定，系统将自动生成。一旦设置，此值不可更改。
user_tokenstring必需卡片用户的唯一令牌
fulfillmentobject可选包含邮寄信息和卡片的物理特征
reissue_pan_from_card_tokenstring可选重新发行指定的卡片，并为其分配相同的 PAN 和 PIN（个人识别号码），但更换新的到期日期和 CVV2 号码。最大长度：36 个字符
translate_pin_from_card_tokenstring可选将新创建的卡片的 PIN 设置为与指定卡片相同。最大长度：36 个字符。注意：两张卡片必须属于同一用户，且不能同时设置 reissue_pan_from_card_token
activation_actionsobject可选包含卡片激活时要执行的操作。注意：此对象中的字段互斥。
bulk_issuance_tokenstring可选用于将卡片链接到批量发卡订单的令牌。注意：该字段一旦设置便无法更新。最大长度：36 个字符

注意：有关 expiration_offset、fulfillment 和 activation_actions 对象的详细信息，请参阅本课程的附录。

在下面的代码中，我们传递了两个查询参数 show_cvv_number 和 show_pan，以及一些可选的请求体参数，再加上必需的参数。

第 1–2 行：我们将 show_cvv_number 和 show_pan 两个可选查询参数都设为 True。

第 8–9 行：我们已在前面的课程中保存了必需参数 user_token 和 card_product_token 的值。

第 14 行：我们输入 name_line_1.value 的值。

第 20–24 行：我们输入 address1、city、state、postal_code 和 country 的值。详情请参考 Marqeta 官方文档。

注意：您可以根据需要修改表格中列出的其他可选参数的值。

输入完所有值后，点击下方代码框中的“运行”按钮查看输出结果。

1show_cvv_number = True
2show_pan = True
3
4url =     "https://sandbox-api.marqeta.com/v3/cards?show_cvv_number=" \
5          + str(show_cvv_number) + "&show_pan="+ str(show_pan)
6
7data = json.dumps({
8     "user_token": "{{USER_TOKEN}}", 
9     "card_product_token": "{{CARD_PRODUCT_TOKEN}}",
10     "fulfillment": {
11          "card_personalization": {
12               "text": {
13                    "name_line_1": {
14                         "value": ""
15                    }
16               }
17          },
18          "shipping": {
19               "recipient_address": {
20                    "address1": "",
21                    "city": "",
22                    "state": "",
23                    "postal_code": "",
24                    "country": "",
25               }
26          },   
27     },
28})
29
30response = requests.post(url, headers=headers, data=data)
31
32printResponse(response)

当代码成功执行后，输出将显示包含所有数据字段的完整卡片对象。我们提取其中的 token 字段并保存为 CARD_TOKEN。该值将在本课程后续操作中使用。

如果失败，则会显示相应的错误信息。

创建卡片状态变更

卡片状态变更 指的是我们设置现有卡片的 state。所有卡片在创建时均为非激活状态，需要手动激活。我们可以通过向 {BASE_URL}/cardtransitions 端点发送 POST 请求来设置现有卡片的状态。

注意：卡片激活后，可能无法再将其从一个用户转移到另一个用户。

请求参数

参数类型分类描述
card_tokenstring必需要更改状态的卡片令牌
channelstring必需状态变更所使用的机制。允许值：ADMIN、API、FRAUD、IVR、SYSTEM
statestring必需要设置的新状态。允许值：ACTIVE、SUSPENDED、TERMINATED
tokenstring可选卡片状态变更的唯一令牌，长度为 1–36 个字符。注意：若未指定，系统将自动生成。一旦设置，此值不可更改。
reasonstring可选状态变更的附加说明，最大长度 255 个字符
reason_codestring可选两位数字代码，描述变更原因。允许值：00–31
validationsobject可选包含用户相关信息

注意：有关 validations 对象以及 channel 和 reason_code 值的详细说明，请参阅本课程的附录。

第 4 行：我们使用前一段代码中提取的 CARD_TOKEN 作为 card_token 的值。

第 5 行：我们将必需参数 state 设置为 ACTIVE。

第 6 行：我们将必需参数 channel 设置为 API，因为我们通过 API 处理此请求。

注意：您可以根据需要填写表格中列出的其他可选参数。

点击下方代码框中的“运行”按钮查看输出结果。

1url = '{{BASE_URL}}cardtransitions'
2
3data = json.dumps({
4    "card_token": "{{CARD_TOKEN}}",
5    "state": "ACTIVE",
6    "channel": "API",
7})
8
9response = requests.post(url, headers=headers, data=data)
10
11printResponse(response)

当代码成功执行后，输出将显示完整的卡片状态变更对象，包含所有数据字段，其中包括更新后的 state。

如果失败，则会显示相应的错误信息。

更新一张卡

我们可以通过向 {BASE_URL}/cards/{token} 端点发送 PUT 请求来更新一张卡片。路径参数 ({token}) 指的是要更新的卡片的令牌。我们还需在请求体中指定希望更新的字段。

请求参数

参数类型分类描述
tokenstring必需要更新的卡片的令牌。注意：这是路径参数。
user_tokenstring可选要关联到该卡片的用户令牌
expediteboolean可选当请求履约提供商加快卡片处理时设为 True，否则为 False。默认值：False
fulfillmentobject可选包含邮寄信息和卡片的物理特征
metadataobject可选将客户提供的元数据添加到卡片中。允许最多 20 对键值对。格式示例："my_name_1": "my_value_1"

注意：我们只能更新 user_token、expedite 参数，以及 fulfillment 和 metadata 对象的值。有关这些参数的详细信息，请参阅前面卡片创建请求参数表。

在下面的代码中，我们更新卡片的 metadata。

注意：您可以选择修改表格中列出的任意属性。

第 1 行：我们使用之前保存的 CARD_TOKEN 作为 token 的值。

第 7 行：我们添加 "card_purpose": "payment_card" 到卡片的 metadata 中。

点击下方代码框中的“运行”按钮查看输出结果。

1token = '{{CARD_TOKEN}}'
2
3url = '{{BASE_URL}}cards/' + token
4
5data = json.dumps({
6    "metadata": { 
7        "card_purpose": "payment_card"
8    }
9})
10
11response = requests.put(url, headers=headers, data=data)
12
13printResponse(response)

当代码成功执行后，输出将显示与给定 token 对应的完整卡片对象，包含所有数据字段，包括已更新的内容。

如果失败，则会显示相应的错误信息。

卡类产品

列表卡片