Cashier 連携 - カスタマイズオプション

Waffoチェックアウトはさまざまなカスタマイズオプションをサポートしています。加盟店は3つの方法で外観と動作を設定できます。

カスタマイズ機能の概要

機能	APIパラメータ	Merchant Portal	SDK初期化
プライマリカラー	対応	対応	対応
背景色	対応	対応	対応
テキストカラー	対応	対応	対応
角丸半径	対応	対応	対応
加盟店ロゴ	対応	対応	-
言語	対応	-	対応

優先順位: APIパラメータ > Merchant Portal > SDK初期化同一機能が複数の方法で設定されている場合、優先度の高い設定が有効になります。

決済手段フィルタリング

payMethodType と payMethodName を使用して、Cashier に表示する決済手段を制御します。決済手段ごとの特例や App WebView / iframe の制限については、Payment method integration notes を参照してください。

推奨パラメータの組み合わせ

シナリオ	payMethodType	payMethodName	payMethodCountry	備考
Cashier 内でユーザーが選択（推奨）	省略	省略	省略	ユーザーは Waffo Cashier の決済手段選択ページに入り、利用可能な決済手段から選択します
カード決済	`"CREDITCARD,DEBITCARD"`	省略	省略	クレジット/デビットカード両対応。Waffo が BIN からカードブランド（Visa/Mastercard）を自動判別し、ユーザーの手間を軽減
クレジットカードのみ	`"CREDITCARD"`	省略	省略	クレジットカードのみ表示
VA（仮想口座）	`"VA"`	省略	必要に応じて渡す	Cashier 内でユーザーが具体的な銀行を選択
特定のウォレット	対応する種別	対応する名前	必要に応じて渡す	例：`"EWALLET"` + `"DANA"`

例

// Best practice: card payments (credit + debit, Visa + Mastercard)
{
  "paymentInfo": {
    "productName": "ONE_TIME_PAYMENT",
    "payMethodType": "CREDITCARD,DEBITCARD"
  }
}

// VA payment (user selects bank in cashier)
{
  "paymentInfo": {
    "productName": "ONE_TIME_PAYMENT",
    "payMethodType": "VA"
  }
}

// Specify a particular wallet
{
  "paymentInfo": {
    "productName": "ONE_TIME_PAYMENT",
    "payMethodType": "EWALLET",
    "payMethodName": "DANA"
  }
}

// Omit all: user sees every available payment method
{
  "paymentInfo": {
    "productName": "ONE_TIME_PAYMENT"
  }
}

payMethodCountry を渡すタイミング

Cashier で特定の国の決済手段のみを表示したい場合に、このフィールドを渡します。

省略：加盟店契約に基づく、すべての国で利用可能な決済手段を表示します。
指定：指定した国の決済手段のみ表示します。

// Show Indonesian payment methods only
{
  "paymentInfo": {
    "productName": "ONE_TIME_PAYMENT",
    "payMethodCountry": "IDN"
  }
}

グローバルカード（CREDITCARD/DEBITCARD）には payMethodCountry を渡さないでください。グローバルカードは特定の国に属しません。

多通貨対応

加盟店の価格通貨とユーザーの決済通貨が異なる場合（クロスカレンシー注文）：

{
  "orderCurrency": "USD",
  "orderAmount": "10.00"
}

userCurrency は省略可能です。Waffo が自動的に為替変換を処理し、ユーザーには Cashier 上で現地通貨の金額が表示されます。

言語設定

paymentInfo.cashierLanguage を使用して Cashier の表示言語を設定します（IETF BCP 47 形式）：

{
  "paymentInfo": {
    "productName": "ONE_TIME_PAYMENT",
    "cashierLanguage": "id-ID"
  }
}

対応言語および適用通貨/国：

言語コード	言語	適用通貨	適用国
`en`	英語	すべての通貨	すべての国（既定のフォールバック）
`id-ID`	インドネシア語	`IDR`	インドネシア
`vi-VN`	ベトナム語	`VND`	ベトナム
`pt-BR`	ポルトガル語（ブラジル）	`BRL`	ブラジル
`es-MX`	スペイン語（メキシコ）	`MXN`	メキシコ
`es-PE`	スペイン語（ペルー）	`PEN`	ペルー
`es-CO`	スペイン語（コロンビア）	`COP`	コロンビア
`es-CL`	スペイン語（チリ）	`CLP`	チリ
`ru-RU`	ロシア語	`RUB`	ロシア
`en-KE`	英語（ケニア）	`KES`	ケニア
`zh-Hant-TW`	繁体字中国語（台湾）	`TWD`	台湾
`zh-Hant-HK`	繁体字中国語（香港）	`HKD`	香港

自動選択ロジック

cashierLanguage を指定しない場合、Waffo は以下の優先順位で自動的に言語を選択します：

ユーザーの国でマッチング（例：ユーザーの国が IDN → id-ID）
注文通貨でマッチング（例：通貨が BRL → pt-BR）
マッチしない場合 → en にフォールバック

注意事項

言語は通貨/国と一致する必要があります。例えば IDR 通貨の注文では id-ID または en のみ使用可能で、pt-BR を指定するとエラーコード A0026 が返されます。
en は汎用言語であり、すべての通貨と国で使用できます。
上記の表に記載されていない通貨（例：USD、EUR、SGD）は en のみサポートされます。

サポート外の言語はエラーコード A0026 を返します。

テーマカスタマイズ

Cashier のカラー、フォント、スタイルをブランドに合わせてカスタマイズできます。

3 つの設定方法

方法	優先度	説明
API パラメータ（トランザクション単位）	最高	`paymentInfo.cashierAppearance` 経由で渡す。トランザクションごとに変更可能
Merchant Portal（グローバル）	中	Merchant Portal でグローバルな既定テーマを設定
SDK 初期化（クライアント側）	最低	フロントエンド SDK の初期化時にテーマ設定を渡す

優先順位：API パラメータ > Merchant Portal > SDK 初期化。API 経由で cashierAppearance が渡された場合、他のすべての設定を上書きします。

テーマ変数

変数	説明	値の例
`colorPrimary`	プライマリーカラー（ボタン、リンク、選択状態）	`#0570de`
`colorBackground`	ページ背景色	`#ffffff`
`colorText`	メインテキストの色	`#30313d`
`borderRadius`	角の丸み	`8px`

これらの変数は Cashier UI のレンダリング層に注入され、既定のテーマを上書きします。決済手段選択ページ、カードフォームページ、遷移ページ、決済結果ページに影響します。

API パラメータ方式

対応エンドポイント：

POST /api/v1/order/create
POST /api/v1/subscription/create

cashierAppearance フィールドは JSON 文字列（JSON オブジェクトではなく）である必要があり、構造は {"variables": { ... }} です。内部のクォートはエスケープしてください。

{
  "paymentInfo": {
    "productName": "ONE_TIME_PAYMENT",
    "cashierAppearance": "{\"variables\":{\"colorPrimary\":\"#0570de\",\"colorBackground\":\"#ffffff\",\"colorText\":\"#30313d\",\"borderRadius\":\"8px\"}}"
  }
}

Merchant Portal での設定

Merchant Portal → Checkout → Cashier Customization に移動し、Cashier のグローバルな既定スタイルを設定します。すべての取引で統一されたブランドスタイルを使いたい場合に適しています。 Portal では、加盟店ロゴ、プリセットテーマ、テーマカラー、基本フォントサイズ、角丸を設定できます。ページ右側で Cashier のプレビューを確認できます。Save & Publish をクリックすると、その後に新規作成される注文に設定が適用されます。

アカウントにサブ加盟店（SubMID）がある場合、すべての SubMID にメイン加盟店設定を継承させることも、SubMID ごとに個別スタイルを設定することもできます。詳しい手順は Merchant Portal Cashier カスタマイズを参照してください。

SDK 初期化

フロントエンド SDK（@waffo/payment-sdk）の初期化時にテーマ設定を渡します。優先度は最低で、API および Merchant Portal のいずれにもテーマ設定がない場合にのみ有効となります。

const waffo = new WaffoSDK({
  env: 'production',
  appearance: {
    variables: {
      colorPrimary: '#0570de',
      colorBackground: '#ffffff',
      colorText: '#30313d',
      borderRadius: '8px'
    }
  }
});

加盟店ロゴ

brandInfo.cashierLogoUrl を通じて加盟店ロゴを渡すことで、チェックアウトページにブランドアイデンティティを表示できます。 2つの形式がサポートされています:

形式	値	備考
外部URL	`https://` で始まる	加盟店がホスト。推奨サイズ: 40×40 px
Portal事前作成ID	`logo_` で始まる	加盟店Portalからアップロード後に取得

APIパラメータの例

外部URLを使用する場合:

{
  "brandInfo": {
    "cashierLogoUrl": "https://merchant.com/logo.png"
  }
}

Portalでアップロードしたロゴを使用する場合:

{
  "brandInfo": {
    "cashierLogoUrl": "logo_abc123"
  }
}

注文の有効期限

orderExpiredAt を使用して注文の有効期限を設定します（ISO 8601、UTC+0）。

{
  "orderExpiredAt": "2026-03-25T11:00:00.000Z"
}

このフィールドはユーザーが Cashier 内で注文を送信できる時間枠を制御します。注文が決済チャネルに送信された後は、有効期限は決済手段自体によって管理されます。一部の決済手段では加盟店からチャネル側の有効期限を渡すことをサポートしています。決済手段ごとの有効期限詳細は Portal の Payin ページで確認してください。

リダイレクト URL

パラメータ	説明
`successRedirectUrl`	決済成功後のリダイレクト
`failedRedirectUrl`	決済失敗後のリダイレクト
`cancelRedirectUrl`	ユーザーが能動的にキャンセルした後のリダイレクト

HTTPS URL およびディープリンク（アプリ内シナリオなど）の両方をサポートしています。

リダイレクト URL はユーザー体験を制御するのみで、決済結果を表すものではありません。決済結果の信頼できる情報源は常に Webhook または照会 API を使用してください。

はじめに

コアコンセプト

インテグレーション

Webhook

SDK

ツールとリファレンス

Cashier 連携 - カスタマイズオプション

カスタマイズ機能の概要

決済手段フィルタリング

推奨パラメータの組み合わせ

例

payMethodCountry を渡すタイミング

多通貨対応

言語設定

自動選択ロジック

注意事項

テーマカスタマイズ

3 つの設定方法

テーマ変数

API パラメータ方式

Merchant Portal での設定

SDK 初期化

加盟店ロゴ

APIパラメータの例

注文の有効期限

リダイレクト URL

​カスタマイズ機能の概要

​決済手段フィルタリング

​推奨パラメータの組み合わせ

​例

​payMethodCountry を渡すタイミング

​多通貨対応

​言語設定

​自動選択ロジック

​注意事項

​テーマカスタマイズ

​3 つの設定方法

​テーマ変数

​API パラメータ方式

​Merchant Portal での設定

​SDK 初期化

​加盟店ロゴ

​APIパラメータの例

​注文の有効期限

​リダイレクト URL

カスタマイズ機能の概要

決済手段フィルタリング

推奨パラメータの組み合わせ

例

payMethodCountry を渡すタイミング

多通貨対応

言語設定

自動選択ロジック

注意事項

テーマカスタマイズ

3 つの設定方法

テーマ変数

API パラメータ方式

Merchant Portal での設定

SDK 初期化

加盟店ロゴ

APIパラメータの例

注文の有効期限

リダイレクト URL