信用額度授權

「信用額度授權」物件用於向您的客戶發放信用額度，這些信用額度可以應用於未來的發票，特別是在基於用量或基於信用額度的計費模型中。每次授權都會追蹤總金額、剩餘餘額、狀態以及任何特定的適用性規則。

若想更全面地了解如何實作一個完整的信用額度系統，請參閱我們的指南基於信用額度的計費。

信用額度授權物件

CreditGrant 物件包含向客戶發放特定信用額度的所有詳細資訊。

信用額度授權物件

{
  "id": "crdg_1B2c3D4e5F6g7H8i9J0k1L2m",
  "object": "credit_grant",
  "amount": "5000",
  "currency_id": "curr_usd",
  "customer_id": "cus_a1b2c3d4e5f6g7h8",
  "name": "促銷性新手信用額度",
  "category": "promotional",
  "priority": 50,
  "status": "granted",
  "effective_at": 1672531200,
  "expires_at": 1704067199,
  "granted_at": 1672531200,
  "remaining_amount": "3500",
  "applicability_config": {
    "scope": {
      "price_type": "metered"
    }
  },
  "metadata": {
    "campaign_id": "promo_q1_2024"
  },
  "livemode": true,
  "created_at": "2023-01-01T00:00:00.000Z",
  "updated_at": "2023-01-15T10:30:00.000Z",
  "customer": {
    "id": "cus_a1b2c3d4e5f6g7h8",
    "did": "did:abt:z1...",
    "name": "John Doe",
    "email": "john.doe@example.com"
  },
  "paymentCurrency": {
    "id": "curr_usd",
    "name": "美元",
    "symbol": "$",
    "decimal": 2
  }
}

建立信用額度授權

向客戶發放新的信用額度授權。如果指定的客戶不存在，將根據提供的 customer_id (DID) 自動建立新客戶。

建立信用額度授權

import payment from '@blocklet/payment-js';

async function createCreditGrant() {
  try {
    const creditGrant = await payment.creditGrants.create({
      amount: '100.00',
      currency_id: 'curr_usd', // 替換為有效的貨幣 ID
      customer_id: 'cus_a1b2c3d4e5f6g7h8', // 或使用者 DID
      name: 'Initial sign-up bonus',
      category: 'promotional',
      priority: 50,
      expires_at: Math.floor(new Date('2024-12-31').getTime() / 1000),
      metadata: {
        source: 'marketing_campaign_fall_2024'
      }
    });
    console.log('信用額度授權已建立:', creditGrant);
  } catch (error) {
    console.error('建立信用額度授權時發生錯誤:', error.message);
  }
}

createCreditGrant();

參數

Name	Type	Description
`amount`	string	必填。要授權的信用額度金額，以數字的字串表示。
`currency_id`	string	必填。此授權的貨幣 ID。
`customer_id`	string	必填。接收信用額度的客戶 ID 或 DID。
`name`	string	供內部參考的信用額度授權選用名稱。
`category`	'paid' \| 'promotional'	必填。授權的類別。`paid` 授權通常由客戶購買，而 `promotional` 授權則是贈送的。
`priority`	number	選用。一個介於 0 到 100 之間的數字，用於決定套用順序。數字較小者會優先套用。預設為 `50`。
`effective_at`	number	選用。一個 Unix 時間戳，表示授權生效的時間。如果未提供，則立即生效。
`expires_at`	number	選用。一個 Unix 時間戳，表示授權到期的時間。
`applicability_config`	object	選用。定義此信用額度可應用的規則。詳情請見下方。如果未設定，則預設適用於所有計量價格。
`metadata`	object	選用。一組您可以附加到物件上的鍵值對。可用於儲存額外資訊。

applicability_config 物件屬性

Name	Type	Description
`scope`	object	定義信用額度授權適用的價格範圍。

scope 物件屬性

Name	Type	Description
`prices`	string[]	價格 ID 的陣列。如果指定，信用額度授權將僅適用於這些價格。
`price_type`	string	可設定為 `'metered'`。如果指定，信用額度授權將適用於此類型的所有價格。

傳回值

如果呼叫成功，則傳回一個 TCreditGrantExpanded 物件。

擷取信用額度授權

透過其唯一識別碼擷取現有信用額度授權的詳細資訊。

擷取信用額度授權

import payment from '@blocklet/payment-js';

async function getCreditGrant(grantId) {
  try {
    const creditGrant = await payment.creditGrants.retrieve(grantId);
    console.log('已擷取信用額度授權:', creditGrant);
  } catch (error) {
    console.error(`擷取信用額度授權 ${grantId} 時發生錯誤:`, error.message);
  }
}

getCreditGrant('crdg_1B2c3D4e5F6g7H8i9J0k1L2m'); // 替換為有效的信用額度授權 ID

參數

Name	Type	Description
`id`	string	必填。要擷取的信用額度授權的唯一識別碼。

傳回值

如果設定了 applicability_config.scope.prices，則傳回一個 TCreditGrantExpanded 物件，其中包含一個額外的 items 屬性，該屬性包含一個擴充後的 Price 物件陣列。

更新信用額度授權

透過設定或取消設定 metadata 屬性來更新指定的信用額度授權。其他屬性無法更新。

更新信用額度授權

import payment from '@blocklet/payment-js';

async function updateCreditGrantMetadata(grantId) {
  try {
    const result = await payment.creditGrants.update(grantId, {
      metadata: {
        source: 'marketing_campaign_fall_2024',
        updated_by: 'admin_user_xyz'
      }
    });
    console.log('更新成功:', result.success);
  } catch (error) {
    console.error(`更新信用額度授權 ${grantId} 時發生錯誤:`, error.message);
  }
}

updateCreditGrantMetadata('crdg_1B2c3D4e5F6g7H8i9J0k1L2m'); // 替換為有效的信用額度授權 ID

參數

Name	Type	Description
`id`	string	必填。要更新的信用額度授權 ID。
`metadata`	object	一組儲存在物件上的鍵值對。若要移除某個鍵，請將其值設定為 `null`。

傳回值

傳回一個包含 success 布林值的物件。

回應

{
  "success": true
}

列出信用額度授權

傳回信用額度授權的分頁列表。您可以根據各種參數篩選列表。

列出信用額度授權

import payment from '@blocklet/payment-js';

async function listCustomerCreditGrants() {
  try {
    const grants = await payment.creditGrants.list({
      customer_id: 'cus_a1b2c3d4e5f6g7h8', // 替換為有效的客戶 ID
      status: 'granted,pending',
      pageSize: 10
    });
    console.log(`找到 ${grants.count} 個授權。`);
    grants.list.forEach(grant => {
      console.log(`- ${grant.id} (${grant.status})`);
    });
  } catch (error) {
    console.error('列出信用額度授權時發生錯誤:', error.message);
  }
}

listCustomerCreditGrants();

參數

Name	Type	Description
`customer_id`	string	選用。按特定客戶 ID 或 DID 篩選授權。
`currency_id`	string	選用。按貨幣 ID 篩選授權。
`status`	string	選用。以逗號分隔的狀態字串，用於篩選（例如：`'granted,pending,depleted'`）。
`livemode`	boolean	選用。按正式模式篩選。
`q`	string	選用。一般搜尋查詢字串。
`page`	number	選用。分頁的頁碼。預設為 `1`。
`pageSize`	number	選用。每頁的項目數。預設為 `20`。

傳回值

一個分頁物件，包含一個 TCreditGrantExpanded 物件的 list 和記錄總數的 count。

取得信用額度摘要

擷取客戶的有效信用額度餘額摘要，按貨幣分組。這對於顯示客戶的總可用信用額度很有用。

取得信用額度摘要

import payment from '@blocklet/payment-js';

async function getCustomerCreditSummary(customerId) {
  try {
    const summary = await payment.creditGrants.summary({ customer_id: customerId });
    console.log('客戶信用額度摘要:', summary);
  } catch (error) {
    console.error(`擷取客戶 ${customerId} 的信用額度摘要時發生錯誤:`, error.message);
  }
}

getCustomerCreditSummary('cus_a1b2c3d4e5f6g7h8'); // 替換為有效的客戶 ID

參數

Name	Type	Description
`customer_id`	string	必填。您想要擷取其信用額度摘要的客戶 ID 或 DID。
`subscription_id`	string	選用。如果提供，摘要將僅包含適用於此特定訂閱中價格的信用額度。

傳回值

傳回一個 CreditSummary 物件。這是一個映射，其中每個鍵都是一個貨幣 ID。其值是一個物件，包含該貨幣的總信用額度和剩餘信用額度金額，以及有效授權的計數。

回應

{
  "curr_usd": {
    "paymentCurrency": {
      "id": "curr_usd",
      "name": "美元",
      "symbol": "$",
      "decimal": 2
    },
    "totalAmount": "15000",
    "remainingAmount": "8500",
    "grantCount": 2
  },
  "curr_eur": {
    "paymentCurrency": {
      "id": "curr_eur",
      "name": "歐元",
      "symbol": "€",
      "decimal": 2
    },
    "totalAmount": "2000",
    "remainingAmount": "2000",
    "grantCount": 1
  }
}

接下來，您可以透過檢視信用額度交易 API 來探索信用額度消費是如何記錄的。