跳到主要内容

客户

客户对象允许您创建和管理您的企业所服务的客户。它们存储了联系方式、地址和账单历史等基本信息，这些信息是创建订阅和处理付款的基础。

客户对象

客户对象代表您系统中的一个唯一客户。

AttributeTypeDescription
idstring客户对象的唯一标识符，以 cus_ 开头。
didstring客户的去中心化标识符（DID）。
livemodeboolean如果对象存在于生产模式，则为 true；如果存在于测试模式，则为 false。
namestring客户的全名。
emailstring客户的主要电子邮件地址。
phonestring客户的主要电话号码。
addressobject客户的账单地址。请参阅下方的地址对象属性。
balancestring客户当前的信用余额。
delinquentboolean客户是否有逾期付款。
metadataobject您可以附加到对象上的一组键值对。
created_atstring客户创建时的时间戳。
updated_atstring客户对象最后一次更新的时间戳。

地址对象属性

AttributeTypeDescription
countrystring两位字母的国家代码（ISO 3166-1 alpha-2）。
statestring州、省、县或地区。
citystring市、区、郊区、镇或村。
line1string地址行 1（例如，街道、邮政信箱或公司名称）。
line2string地址行 2（例如，公寓、套房、单元或建筑物）。
postal_codestring邮政编码或邮政代码。

检索客户

通过提供现有客户的唯一 ID 或 DID 来检索其详细信息。

参数

NameTypeDescription
idstring要检索的客户的标识符（cus_... 或 DID）。

返回

如果存在具有给定 ID 的客户，则返回一个 TCustomerExpanded 对象。

示例

检索客户

javascript
async function retrieveCustomer(customerId) {
  try {
    const customer = await payment.customers.retrieve(customerId);
    console.log('检索到的客户:', customer);
    return customer;
  } catch (error) {
    console.error('检索客户时出错:', error.message);
  }
}

// 使用客户 ID 的示例
retrieveCustomer('cus_xxxxxxxxxxxxxxxx');

响应示例

客户对象示例

json
{
  "id": "cus_xxxxxxxxxxxxxxxx",
  "did": "zNK...",
  "livemode": true,
  "name": "John Doe",
  "email": "john.doe@example.com",
  "phone": "+15551234567",
  "address": {
    "country": "US",
    "state": "CA",
    "city": "San Francisco",
    "line1": "123 Main Street",
    "line2": "Apt 4B",
    "postal_code": "94105"
  },
  "balance": "100.00",
  "delinquent": false,
  "metadata": {},
  "created_at": "2023-10-27T10:00:00.000Z",
  "updated_at": "2023-10-27T10:00:00.000Z"
}

更新客户

通过设置传入参数的值来更新指定的客户。任何未提供的参数将保持不变。

参数

NameTypeDescription
idstring要更新的客户的标识符。
dataobject包含要更新字段的对象。详见下文。

Data 对象属性

AttributeTypeDescription
namestring客户的全名。
emailstring客户的电子邮件地址。
phonestring客户的电话号码。
addressobject客户的账单地址。遵循地址对象结构。
metadataobject与客户一同存储的一组键值对。

返回

返回更新后的 TCustomer 对象。

示例

更新客户

javascript
async function updateCustomerDetails(customerId) {
  try {
    const updatedCustomer = await payment.customers.update(customerId, {
      email: 'john.new.doe@example.com',
      metadata: {
        internal_id: 'user-456'
      }
    });
    console.log('客户更新成功:', updatedCustomer);
    return updatedCustomer;
  } catch (error) {
    console.error('更新客户时出错:', error.message);
  }
}

updateCustomerDetails('cus_xxxxxxxxxxxxxxxx');

列出所有客户

返回客户的分页列表。

参数

NameTypeDescription
paramsobject包含分页和筛选参数的对象。

Params 对象属性

AttributeTypeDescription
didstring可选。将列表筛选为具有特定 DID 的客户。
pagenumber可选。要检索的页码。默认为 1。
pageSizenumber可选。每页要检索的客户数量。默认为 20。

返回

返回一个分页对象，其中包含一个 TCustomerExpanded 对象列表和分页详情。

示例

列出客户

javascript
async function listCustomers() {
  try {
    const response = await payment.customers.list({ pageSize: 5 });
    console.log(`客户总数: ${response.count}`);
    console.log('第一页客户:', response.list);
    return response;
  } catch (error) {
    console.error('列出客户时出错:', error.message);
  }
}

listCustomers();

响应示例

分页客户列表

json
{
  "count": 50,
  "list": [
    {
      "id": "cus_xxxxxxxxxxxxxxxx",
      "did": "zNK...",
      "name": "John Doe",
      "email": "john.doe@example.com",
      // ... 其他客户字段
    }
    // ... 更多客户对象
  ],
  "paging": {
    "page": 1,
    "pageSize": 5
  }
}

搜索客户

返回与搜索查询匹配的客户分页列表。搜索将在名称、电子邮件和 DID 等字段上执行。

参数

NameTypeDescription
paramsobject包含搜索和分页参数的对象。

Params 对象属性

AttributeTypeDescription
querystring搜索字符串。
pagenumber可选。要检索的页码。默认为 1。
pageSizenumber可选。每页要检索的客户数量。默认为 20。

返回

返回一个分页对象，其中包含与搜索查询匹配的 TCustomerExpanded 对象列表。

示例

搜索客户

javascript
async function searchForCustomer(query) {
  try {
    const results = await payment.customers.search({ query: query });
    console.log(`找到 ${results.count} 个匹配 '${query}' 的客户:`, results.list);
    return results;
  } catch (error) {
    console.error('搜索客户时出错:', error.message);
  }
}

searchForCustomer('john.doe');

检索逾期发票

检索特定客户的 uncollectible 发票列表，以及按货币分组的应付总额摘要。

参数

NameTypeDescription
idstring客户的标识符。

返回

一个包含客户信息、其逾期发票列表以及应付金额摘要的对象。

示例

获取逾期发票

javascript
async function getOverdueInvoices(customerId) {
  try {
    const overdueData = await payment.customers.overdueInvoices(customerId);
    console.log('逾期发票数据:', overdueData);
    return overdueData;
  } catch (error) {
    console.error('检索逾期发票时出错:', error.message);
  }
}

getOverdueInvoices('cus_xxxxxxxxxxxxxxxx');

响应示例

逾期发票响应

json
{
  "customer": {
    "id": "cus_xxxxxxxxxxxxxxxx",
    // ... 客户详情
  },
  "invoices": [
    {
      "id": "in_yyyyyyyyyyyyyyyy",
      "status": "uncollectible",
      "amount_remaining": "2500",
      "currency_id": "curr_zzzzzzzzzzzzzzzz",
      // ... 其他发票详情
    }
  ],
  "summary": {
    "curr_zzzzzzzzzzzzzzzz": {
      "amount": "2500",
      "currency": {
        // ... 支付货币详情
      },
      "method": {
        // ... 支付方式详情
      }
    }
  }
}