创建和更新卡片

创建卡片

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

请求参数

注意： 有关 expiration_offset、fulfillment 和 activation_actions 对象的详细信息，请参阅 “附加参数和响应字段” 课程。

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

1// 导入库
2import fetch from "node-fetch"
3
4// 定义端点 URL
5const endpointUrl = new URL('{{BASE_URL}}cards');
6
7const tokens = '{{APPLICATION_TOKEN}}:{{ADMIN_ACCESS_TOKEN}}'
8const encoded = Buffer.from(tokens, 'ascii').toString('base64')
9
10const headerParameters = {
11    'Content-Type': 'application/json',
12    'Authorization': `Basic ${encoded}`
13};
14
15// 定义查询参数
16const queryParameters = new URLSearchParams({
17    "show_cvv_number": true,
18    "show_pan": true
19})
20
21// 定义请求体参数
22const bodyParameters = JSON.stringify({
23    "user_token": "{{USER_TOKEN}}", 
24    "card_product_token": "{{CARD_PRODUCT_TOKEN}}",
25    "fulfillment": {
26        "card_personalization": {
27            "text": {
28                "name_line_1": {
29                    "value": ""
30                }
31            }
32        },
33        "shipping": {
34            "recipient_address": {
35                "address1": "9231 Pennsylvania Street Hopewell Junction",
36                "city": "New York City",
37                "state": "New York",
38                "postal_code": "12533",
39                "country": "US",
40            }
41        },   
42    },
43});
44
45// 设置 API 调用选项
46const options = {
47    method: "POST",
48    headers: headerParameters,
49    body: bodyParameters
50};
51
52// 执行 API 调用的函数
53async function createCard() {
54    try {
55        endpointUrl.search = queryParameters;
56        const response = await fetch(endpointUrl, options);
57        // 打印响应
58        printResponse(response);
59    } catch (error) {
60        // 打印错误信息
61        printError(error);
62    }
63}
64
65// 调用函数执行 API 调用
66createCard();

在上述代码框中：

• 第 5 行： 在 endpointURL 变量中定义了端点 URL。
• 第 16–19 行： 在 queryParameters 变量中将 show_cvv_number 和 show_pan 设置为 true。
• 第 22–43 行： 在 bodyParameters 变量中添加了 user_token、card_product_token 和 fulfillment。
• 第 47 行： 将请求方法设置为 POST，以创建新卡片。
• 第 56 行： 使用 fetch 函数发起 API 调用。

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

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

响应字段

创建卡片状态变更

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

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

请求参数

注意： 有关 validations 对象以及 channel 和 reason_code 值的详细说明，请参阅 “附加参数和响应字段” 课程。

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

1// 导入库
2import fetch from "node-fetch"
3
4// 定义端点 URL
5const endpointUrl = new URL('{{BASE_URL}}cardtransitions');
6
7const tokens = '{{APPLICATION_TOKEN}}:{{ADMIN_ACCESS_TOKEN}}'
8const encoded = Buffer.from(tokens, 'ascii').toString('base64')
9
10const headerParameters = {
11    'Content-Type': 'application/json',
12    'Authorization': `Basic ${encoded}`
13};
14
15// 定义请求体参数
16const bodyParameters = JSON.stringify({
17    "card_token": "{{CARD_TOKEN}}",
18    "state": "ACTIVE",
19    "channel": "API",
20});
21
22// 设置 API 调用选项
23const options = {
24    method: "POST",
25    headers: headerParameters,
26    body: bodyParameters
27};
28
29// 执行 API 调用的函数
30async function createCardTransition() {
31    try {
32        const response = await fetch(endpointUrl, options);
33        // 打印响应
34        printResponse(response);
35    } catch (error) {
36        // 打印错误信息
37        printError(error);
38    }
39}
40
41// 调用函数执行 API 调用
42createCardTransition();

在上述代码框中：

• 第 5 行： 在 endpointURL 变量中定义了端点 URL。
• 第 16–20 行： 在 bodyParameters 变量中指定 card_token，并将 state 设为 ACTIVE，channel 设为 API。
• 第 24 行： 将请求方法设置为 POST，以创建卡片状态变更。
• 第 32 行： 使用 fetch 函数发起 API 调用。

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

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

响应字段

更新卡片

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

请求参数

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

在以下代码中，我们更新卡片的 metadata。点击下方代码框中的“运行”按钮查看输出结果。

1// 导入库
2import fetch from "node-fetch"
3
4const tokens = '{{APPLICATION_TOKEN}}:{{ADMIN_ACCESS_TOKEN}}'
5const encoded = Buffer.from(tokens, 'ascii').toString('base64')
6
7const cardToken = '{{CARD_TOKEN}}'
8
9// 定义端点 URL
10const endpointUrl = new URL(`{{BASE_URL}}cards/${cardToken}`);
11
12const headerParameters = {
13    'Content-Type': 'application/json',
14    'Authorization': `Basic ${encoded}`
15};
16
17// 定义请求体参数
18const bodyParameters = JSON.stringify({
19    "metadata": { 
20        "card_purpose": "payment_card"
21    }
22});
23
24// 设置 API 调用选项
25const options = {
26    method: "PUT",
27    headers: headerParameters,
28    body: bodyParameters
29};
30
31// 执行 API 调用的函数
32async function updateCard() {
33    try {
34        const response = await fetch(endpointUrl, options);
35        // 打印响应
36        printResponse(response);
37    } catch (error) {
38        // 打印错误信息
39        printError(error);
40    }
41}
42
43// 调用函数执行 API 调用
44updateCard();

在上述代码框中：

• 第 10 行： 在 endpointURL 变量中定义了端点 URL 并将 cardToken 作为路径参数添加。
• 第 18–22 行： 在 bodyParameters 变量中输入 "card_purpose": "payment_card"，将该信息添加到卡片的 metadata 中。
• 第 26 行： 将请求方法设置为 PUT，以更新卡片。
• 第 34 行： 使用 fetch 函数发起 API 调用。

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

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

注意： 有关此 API 调用的响应字段，请参考创建卡片的响应字段表格。