メインコンテンツへスキップ

支払通貨

支払通貨APIを使用すると、支払いに使用できる通貨を管理できます。これには、標準的なブロックチェーンベースのトークン(ERC-20やArcBlockネイティブトークンなど)や、クレジットベースの請求システムを実装するために使用されるカスタムクレジット通貨が含まれます。

各支払通貨は、特定の支払方法にリンクされており、これにより基盤となるネットワークやシステム(例:イーサリアム、ArcBlock)が定義されます。

支払通貨オブジェクト

PaymentCurrencyオブジェクトには、取引に利用可能な通貨に関するすべての詳細が含まれています。

AttributeTypeDescription
idstring支払通貨オブジェクトの一意の識別子。
namestring通貨のフルネーム(例:「Ethereum Tether」)。
descriptionstring通貨の簡単な説明。
logostring通貨を表す画像のURL。
symbolstring通貨の短く認識しやすいシンボル(例:「USDT」)。
decimalnumber通貨が持つ小数点以下の桁数。
contractstringトークンベース通貨のコントラクトアドレス。
typestring通貨のタイプ。通常のトークンはstandard、カスタムクレジットシステムはcreditになります。
activebooleanこの通貨が現在利用可能かどうか。
livemodeboolean通貨がライブモードの場合はtrue、テストモードの場合はfalse
is_base_currencybooleanこれがネイティブチェーンのトークンであるかどうかを示します。
payment_method_idstring関連付けられたPaymentMethodのID。
recharge_configobjectクレジット通貨の場合、このオブジェクトにはクレジット残高をチャージするための設定が含まれています。詳細はgetRechargeConfigメソッドを参照してください。
metadataobjectオブジェクトに添付できるキーと値のペアのセット。

支払通貨の作成

新しい支払通貨を作成します。これは通常、サポートされているブロックチェーン上で新しいERC-20トークンや類似の資産のサポートを追加するために使用されます。

パラメータ

NameTypeDescription
namestring必須。 通貨の名前。最大32文字。
descriptionstring必須。 通貨の説明。最大255文字。
payment_method_idstring必須。 この通貨が属する支払方法のID(例:イーサリアム支払方法)。
contractstring必須。 トークンのコントラクトアドレス。システムは対応するネットワーク上でこのコントラクトを検証します。
logostring任意。 通貨のロゴのURL。指定しない場合、支払方法のロゴが使用されます。

戻り値

新しく作成されたPaymentCurrencyオブジェクトを返します。

新しい支払通貨を作成する

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

async function createCurrency() {
  try {
    const newCurrency = await payment.paymentCurrencies.create({
      name: 'My Custom Token',
      description: 'An ERC-20 token for our platform',
      payment_method_id: 'pm_xxxxxxxxxxxxxx', // EVMベースの支払方法のID
      contract: '0x..._token_contract_address',
      logo: 'https://example.com/token_logo.png',
    });
    console.log('支払通貨が作成されました:', newCurrency);
  } catch (error) {
    console.error('支払通貨の作成中にエラーが発生しました:', error.message);
  }
}

createCurrency();

レスポンス例

json
{
  "id": "curr_xxxxxxxxxxxxxx",
  "livemode": false,
  "active": true,
  "locked": false,
  "is_base_currency": false,
  "payment_method_id": "pm_xxxxxxxxxxxxxx",
  "name": "My Custom Token",
  "description": "An ERC-20 token for our platform",
  "contract": "0x..._token_contract_address",
  "logo": "https://example.com/token_logo.png",
  "symbol": "MCT",
  "decimal": 18,
  "type": "standard",
  "metadata": {},
  "created_at": "2023-10-27T10:00:00.000Z",
  "updated_at": "2023-10-27T10:00:00.000Z"
}

支払通貨の取得

既存の支払通貨の詳細を、その一意のIDまたはシンボルで取得します。

パラメータ

NameTypeDescription
idstring必須。 取得する支払通貨の一意の識別子(curr_...)またはシンボル(例:USDT)。

戻り値

対応するPaymentCurrencyオブジェクトが見つかった場合はそれを返し、見つからない場合は404エラーを返します。

支払通貨を取得する

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

async function getCurrency(currencyId) {
  try {
    const currency = await payment.paymentCurrencies.retrieve(currencyId);
    console.log('取得した通貨:', currency);
  } catch (error) {
    console.error('通貨の取得中にエラーが発生しました:', error.message);
  }
}

// IDで取得
getCurrency('curr_xxxxxxxxxxxxxx');

// または、シンボルで取得
// getCurrency('USDT');

レスポンス例

json
{
  "id": "curr_xxxxxxxxxxxxxx",
  "livemode": false,
  "active": true,
  "name": "My Custom Token",
  "symbol": "MCT",
  "decimal": 18,
  "type": "standard",
  "created_at": "2023-10-27T10:00:00.000Z",
  "updated_at": "2023-10-27T10:00:00.000Z"
}

支払通貨の更新

渡されたパラメータの値を設定して、指定された支払通貨を更新します。指定されなかったパラメータは変更されません。

パラメータ

NameTypeDescription
idstring必須。 更新する支払通貨のID。
updateDataobject必須。 更新するフィールドを含むオブジェクト。
updateData.namestring任意。 通貨の新しい名前。
updateData.descriptionstring任意。 通貨の新しい説明。
updateData.logostring任意。 通貨の新しいロゴURL。
updateData.metadataobject任意。 オブジェクトと一緒に保存するキーと値のペアのセット。
updateData.symbolstring任意。 creditタイプの通貨のみ、シンボルを更新します。

戻り値

更新されたPaymentCurrencyオブジェクトを返します。

支払通貨を更新する

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

async function updateCurrency(currencyId) {
  try {
    const updatedCurrency = await payment.paymentCurrencies.update(currencyId, {
      description: 'An updated description for my token.'
    });
    console.log('通貨が更新されました:', updatedCurrency);
  } catch (error) {
    console.error('通貨の更新中にエラーが発生しました:', error.message);
  }
}

updateCurrency('curr_xxxxxxxxxxxxxx');

レスポンス例

json
{
  "id": "curr_xxxxxxxxxxxxxx",
  "name": "My Custom Token",
  "description": "An updated description for my token.",
  "symbol": "MCT",
  "decimal": 18,
  "updated_at": "2023-10-27T11:30:00.000Z"
}

支払通貨の一覧表示

支払通貨のリストを返します。通貨は作成日順にソートされ、最も新しく作成された通貨が最初に表示されます。

パラメータ

NameTypeDescription
filtersobject任意。 フィルタ条件を含むオブジェクト。
filters.activeboolean任意。 アクティブまたは非アクティブな通貨のみを含むようにリストをフィルタリングします。
filters.livemodeboolean任意。 環境(ライブまたはテスト)に基づいてリストをフィルタリングします。
filters.creditboolean任意。 trueの場合、リストにはstandard通貨に加えてcreditタイプの通貨も含まれます。

戻り値

PaymentCurrencyオブジェクトの配列を返します。

すべてのアクティブな通貨を一覧表示する

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

async function listCurrencies() {
  try {
    const currencies = await payment.paymentCurrencies.list({ active: true });
    console.log(`${currencies.length}個のアクティブな通貨が見つかりました。`);
    currencies.forEach(c => console.log(`- ${c.name} (${c.symbol})`));
  } catch (error) {
    console.error('通貨の一覧表示中にエラーが発生しました:', error.message);
  }
}

listCurrencies();

レスポンス例

json
[
  {
    "id": "curr_xxxxxxxxxxxxxx",
    "name": "My Custom Token",
    "symbol": "MCT",
    "active": true
  },
  {
    "id": "curr_yyyyyyyyyyyyyy",
    "name": "Another Token",
    "symbol": "ATK",
    "active": true
  }
]

チャージ設定の取得

creditタイプの通貨のチャージ設定を取得します。この設定は、ユーザーがそのクレジットを購入またはチャージする方法を定義します。

パラメータ

NameTypeDescription
idstring必須。 クレジット通貨のID(curr_...)。

戻り値

指定されたクレジット通貨をチャージする方法に関する詳細を含む設定オブジェクトを返します。

NameTypeDescription
currency_idstringクレジット通貨のID。
currency_infoobjectクレジット通貨の基本情報(idnamesymboldecimaltype)。
recharge_configobjectチャージメカニズムを詳述するオブジェクト。
recharge_config.base_price_idstringクレジット購入の基準となるPriceオブジェクトのID。
recharge_config.payment_urlstringクレジットを購入するためのチェックアウトページへの直接URL。
recharge_config.basePriceobjectbase_price_idに関連付けられた完全なPriceオブジェクト(製品詳細を含む)。
recharge_config.settingsobjectチャージに関する追加設定。
recharge_config.settings.min_recharge_amountnumber1回の取引でチャージできるクレジットの最小額。
recharge_config.settings.max_recharge_amountnumber1回の取引でチャージできるクレジットの最大額。

クレジットチャージ設定を取得する

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

async function getRechargeConfig(creditCurrencyId) {
  try {
    const config = await payment.paymentCurrencies.getRechargeConfig(creditCurrencyId);
    console.log('チャージ設定:', config);
    if (config.recharge_config) {
      console.log(`支払URL: ${config.recharge_config.payment_url}`);
    }
  } catch (error) {
    console.error('チャージ設定の取得中にエラーが発生しました:', error.message);
  }
}

getRechargeConfig('curr_zzzzzzzzzzzzzz'); // クレジット通貨のID

レスポンス例

json
{
  "currency_id": "curr_zzzzzzzzzzzzzz",
  "currency_info": {
    "id": "curr_zzzzzzzzzzzzzz",
    "name": "Platform Credits",
    "symbol": "PCC",
    "decimal": 2,
    "type": "credit"
  },
  "recharge_config": {
    "base_price_id": "price_xxxxxxxxxxxxxx",
    "payment_url": "https://your-app.arcblock.io/checkout/pay/pl_xxxxxxxxxxxxxx",
    "basePrice": {
      "id": "price_xxxxxxxxxxxxxx",
      "unit_amount": "1.00",
      // ... その他の価格詳細
      "product": {
        "id": "prod_xxxxxxxxxxxxxx",
        "name": "Credit Top-up"
      }
    },
    "settings": {
      "min_recharge_amount": 10,
      "max_recharge_amount": 1000
    }
  }
}

チャージ設定の更新

creditタイプの通貨のチャージ設定を更新します。これはプログラムで行うこともできますが、より良いユーザーエクスペリエンスのためにPaymentKitダッシュボードを通じてこれらの設定を管理することをお勧めします。

パラメータ

NameTypeDescription
idstring必須。 更新するクレジット通貨のID。
configobject必須。 新しい設定オブジェクト。
config.base_price_idstring必須。 クレジットあたりのコストを定義するPriceオブジェクトのID。価格はアクティブである必要があります。
config.payment_link_idstring任意。 チャージに使用する事前設定済みのPaymentLinkのID。
config.checkout_urlstring任意。 チェックアウトページのカスタムURL。
config.settingsobject任意。 チャージ制限のためのオブジェクト。
config.settings.min_recharge_amountnumber任意。 ユーザーが一度に購入できるクレジットの最小額。
config.settings.max_recharge_amountnumber任意。 ユーザーが一度に購入できるクレジットの最大額。

戻り値

チャージ設定が正常に更新されたことを確認するオブジェクトを返します。

クレジットチャージ設定を更新する

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

async function updateRechargeConfig(creditCurrencyId) {
  try {
    const result = await payment.paymentCurrencies.updateRechargeConfig(creditCurrencyId, {
      base_price_id: 'price_yyyyyyyyyyyyyy', // 新しい価格ID
      settings: {
        min_recharge_amount: 5
      }
    });
    console.log(result.message);
  } catch (error) {
    console.error('チャージ設定の更新中にエラーが発生しました:', error.message);
  }
}

updateRechargeConfig('curr_zzzzzzzzzzzzzz');

レスポンス例

json
{
  "currency_id": "curr_zzzzzzzzzzzzzz",
  "recharge_config": {
    "base_price_id": "price_yyyyyyyyyyyyyy",
    "settings": {
      "min_recharge_amount": 5
    }
  },
  "message": "Recharge config updated successfully"
}