客户

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

客户对象#

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

Attribute

Type

Description

id

string

客户对象的唯一标识符，以 cus_ 开头。

did

string

客户的去中心化标识符（DID）。

livemode

boolean

如果对象存在于生产模式，则为 true；如果存在于测试模式，则为 false。

name

string

客户的全名。

email

string

客户的主要电子邮件地址。

phone

string

客户的主要电话号码。

address

object

客户的账单地址。请参阅下方的地址对象属性。

balance

string

客户当前的信用余额。

delinquent

boolean

客户是否有逾期付款。

metadata

object

您可以附加到对象上的一组键值对。

created_at

string

客户创建时的时间戳。

updated_at

string

客户对象最后一次更新的时间戳。

地址对象属性

Attribute

Type

Description

country

string

两位字母的国家代码（ISO 3166-1 alpha-2）。

state

string

州、省、县或地区。

city

string

市、区、郊区、镇或村。

line1

string

地址行 1（例如，街道、邮政信箱或公司名称）。

line2

string

地址行 2（例如，公寓、套房、单元或建筑物）。

postal_code

string

邮政编码或邮政代码。

检索客户#

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

参数#

Name

Type

Description

id

string

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

返回#

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

示例#

检索客户

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');

响应示例#

客户对象示例

{
  "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"
}

更新客户#

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

参数#

Name

Type

Description

id

string

要更新的客户的标识符。

data

object

包含要更新字段的对象。详见下文。

Data 对象属性

Attribute

Type

Description

name

string

客户的全名。

email

string

客户的电子邮件地址。

phone

string

客户的电话号码。

address

object

客户的账单地址。遵循地址对象结构。

metadata

object

与客户一同存储的一组键值对。

返回#

返回更新后的 TCustomer 对象。

示例#

更新客户

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');

列出所有客户#

返回客户的分页列表。

参数#

Name

Type

Description

params

object

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

Params 对象属性

Attribute

Type

Description

did

string

可选。将列表筛选为具有特定 DID 的客户。

page

number

可选。要检索的页码。默认为 1。

pageSize

number

可选。每页要检索的客户数量。默认为 20。

返回#

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

示例#

列出客户

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();

响应示例#

分页客户列表

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

搜索客户#

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

参数#

Name

Type

Description

params

object

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

Params 对象属性

Attribute

Type

Description

query

string

搜索字符串。

page

number

可选。要检索的页码。默认为 1。

pageSize

number

可选。每页要检索的客户数量。默认为 20。

返回#

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

示例#

搜索客户

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 发票列表，以及按货币分组的应付总额摘要。

参数#

Name

Type

Description

id

string

客户的标识符。

返回#

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

示例#

获取逾期发票

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');

响应示例#

逾期发票响应

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

See all 1 lines

信用交易
发票