curl -s -X PATCH "https://api.privacy.com/v1/cards/{card_token}" \
  -H "Authorization: api-key $PRIVACY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"spend_limit": 10000, "spend_limit_duration": "MONTHLY"}' | jq

隐私卡

通过Privacy.com API管理虚拟卡。

设置

获取API访问权限

1. 1. 注册Privacy.com账户
2. 发送邮件至support@privacy.com申请API访问权限
3. 获批后，您将收到API密钥

配置

bash
export PRIVACYAPIKEY=your-api-key

环境：

• - 生产环境：https://api.privacy.com/v1
• 沙箱环境：https://sandbox.privacy.com/v1

所有请求：Authorization: api-key $PRIVACYAPIKEY

---

创建卡片

bash
curl -s -X POST https://api.privacy.com/v1/cards \
-H Authorization: api-key $PRIVACYAPIKEY \
-H Content-Type: application/json \
-d {
type: SINGLE_USE,
memo: 一次性购买,
spend_limit: 5000,
spendlimitduration: TRANSACTION
} | jq

卡片类型

类型	行为
SINGLEUSE	首次交易后关闭
MERCHANTLOCKED

锁定至首个商户，可重复使用 |

| UNLOCKED | 任意场景可用（需授权发行） |

创建参数

参数	必填	描述
type	是	SINGLEUSE、MERCHANTLOCKED、UNLOCKED
memo

否 | 标签/描述 |

| spend_limit | 否 | 限额（单位：分） | | spendlimitduration | 否 | TRANSACTION、MONTHLY、ANNUALLY、FOREVER | | state | 否 | OPEN（默认）或PAUSED | | funding_token | 否 | 指定资金来源UUID |

响应

json { token: card-uuid, type: SINGLE_USE, state: OPEN, memo: 一次性购买, last_four: 1234, pan: 4111111111111234, cvv: 123, exp_month: 12, exp_year: 2027, spend_limit: 5000, spendlimitduration: TRANSACTION, created: 2024-01-15T10:30:00Z }

注意： 生产环境中pan、cvv、expmonth、expyear需企业级访问权限。沙箱环境始终可用。

---

查询交易

查询卡片所有交易

bash curl -s https://api.privacy.com/v1/transactions?cardtoken={cardtoken} \ -H Authorization: api-key $PRIVACYAPIKEY | jq

按日期范围筛选

bash curl -s https://api.privacy.com/v1/transactions?cardtoken={cardtoken}&begin=2024-01-01&end=2024-01-31 \ -H Authorization: api-key $PRIVACYAPIKEY | jq

按结果筛选

bash

仅已批准

curl -s https://api.privacy.com/v1/transactions?result=APPROVED \ -H Authorization: api-key $PRIVACYAPIKEY | jq

仅已拒绝

curl -s https://api.privacy.com/v1/transactions?result=DECLINED \ -H Authorization: api-key $PRIVACYAPIKEY | jq

查询参数

参数	描述
card_token	按卡片UUID筛选
result

APPROVED或DECLINED |

| begin | 指定日期及之后（YYYY-MM-DD） | | end | 指定日期之前（YYYY-MM-DD） | | page | 页码（默认：1） | | page_size | 每页结果数（1-1000，默认：50） |

交易响应

json { token: txn-uuid, card_token: card-uuid, amount: -2500, status: SETTLED, result: APPROVED, merchant: { descriptor: NETFLIX.COM, mcc: 4899, city: LOS GATOS, state: CA, country: USA }, created: 2024-01-15T14:22:00Z }

交易状态

PENDING → SETTLING → SETTLED

此外：VOIDED、BOUNCED、DECLINED

---

快速参考

列出所有卡片

bash curl -s https://api.privacy.com/v1/cards \ -H Authorization: api-key $PRIVACYAPIKEY | jq

获取单张卡片

bash curl -s https://api.privacy.com/v1/cards/{card_token} \ -H Authorization: api-key $PRIVACYAPIKEY | jq

暂停卡片

bash curl -s -X PATCH https://api.privacy.com/v1/cards/{card_token} \ -H Authorization: api-key $PRIVACYAPIKEY \ -H Content-Type: application/json \ -d {state: PAUSED} | jq

关闭卡片（永久）

bash curl -s -X PATCH https://api.privacy.com/v1/cards/{card_token} \ -H Authorization: api-key $PRIVACYAPIKEY \ -H Content-Type: application/json \ -d {state: CLOSED} | jq

更新消费限额

bash curl -s -X PATCH https://api.privacy.com/v1/cards/{card_token} \ -H Authorization: api-key $PRIVACYAPIKEY \ -H Content-Type: application/json \ -d {spendlimit: 10000, spendlimit_duration: MONTHLY} | jq

---

常见拒绝原因

代码	含义
CARDPAUSED	卡片已暂停
CARDCLOSED

卡片已关闭 | | SINGLEUSERECHARGED | 一次性卡片已被使用 | | UNAUTHORIZED_MERCHANT | 锁定卡片的商户不匹配 | | USERTRANSACTIONLIMIT | 超出消费限额 | | INSUFFICIENT_FUNDS | 资金来源问题 |

完整字段文档请参见references/api.md。