跳到主要內容

客戶

客戶物件可讓您建立和管理您的業務所服務的客戶。它們儲存了聯絡方式、地址和帳單歷史等基本資訊，這些資訊是建立訂閱和處理付款的基礎。

客戶物件

一個客戶物件代表您系統中的一個獨立客戶。

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地址第一行 (例如：街道、郵政信箱或公司名稱)。
line2string地址第二行 (例如：公寓、套房、單元或大樓)。
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一個包含要更新欄位的物件。詳情請見下方。

資料物件屬性

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 物件 list 和分頁詳細資訊的分頁物件。

範例

列出客戶

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 物件 list 的分頁物件。

範例

搜尋客戶

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": {
        // ... 付款方式詳細資訊
      }
    }
  }
}