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`	インドネシア語
`vi-VN`	ベトナム語
`pt-BR`	ポルトガル語（ブラジル）
`es-MX`	スペイン語（メキシコ）
`es-PE`	スペイン語（ペルー）
`es-CO`	スペイン語（コロンビア）
`es-CL`	スペイン語（チリ）
`ru-RU`	ロシア語
`en-KE`	英語（ケニア）
`zh-Hant-TW`	繁体字中国語（台湾）
`zh-Hant-HK`	繁体字中国語（香港）
`th-TH`	タイ語
`ja-JP`	日本語
`en-NG`	英語（ナイジェリア）
`ko-KR`	韓国語
`en-HK`	英語（香港）
`zh-Hans-HK`	簡体字中国語（香港）
`pl-PL`	ポーランド語
`tr-TR`	トルコ語
`zh-Hans`	簡体字中国語
`ms-MY`	マレー語

cashierLanguage は注文通貨およびユーザーの国または地域とは独立しています。Waffo は有効な言語タグを標準の BCP 47 の大文字・小文字表記に正規化します。例えば、en-us は en-US に正規化されます。

自動選択ロジック

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

ブラウザの Accept-Language ヘッダーで優先度が最も高いサポート対象言語を使用する
ユーザーが GLB 以外の国または地域タブを選択した場合、その国または地域に対応する言語を使用する
それ以外の場合、ユーザーの IP アドレスに対応する国または地域の言語を使用する
言語を判定できない場合、en にフォールバックする

Waffo は Accept-Language で q 重みが最も高い言語項目だけを確認します。その言語がサポート対象外の場合、国または地域による選択に進みます。ブラウザ言語の照合は主言語サブタグで行います。en、es、id、ja、ko、ms、pl、pt、th、tr、vi はそのまま一致し、任意の zh-* タグは zh にマッピングされます。その他の主言語は、cashierLanguage で明示的に指定できる場合でも、ブラウザ言語では Cashier をロックしません。 cashierLanguage で指定した言語と Accept-Language から選択した言語は、Cashier セッション中に固定されます。国または地域から選択した言語は、ユーザーがタブを切り替えると変わります。GLB には対応言語がないため、Waffo は残りの条件を使用して言語を選択します。国または地域のフォールバックでは、次のマッピングを使用します：

国または地域	言語
`BRA`	`pt-BR`
`MEX`	`es-MX`
`IDN`	`id-ID`
`VNM`	`vi-VN`
`RUS`	`ru-RU`
`KEN`	`en-KE`
`PER`	`es-PE`
`COL`	`es-CO`
`CHL`	`es-CL`
`TWN`	`zh-Hant-TW`
`HKG`	`zh-Hant-HK`
`THA`	`th-TH`
`JPN`	`ja-JP`
`NGA`	`en-NG`
`KOR`	`ko-KR`
`POL`	`pl-PL`
`TUR`	`tr-TR`
`MYS`	`en`
`CHN`	`zh-Hans`

注意事項

注文通貨とユーザーの決済通貨は Cashier の言語選択に使用されません。
cashierLanguage は、言語プレフィックスと文字体系がサポート対象かどうかを検証します。地域は、有効な ISO 3166-1 alpha-2 の国または地域コードであれば受け付けます。
サポートされていない言語または文字体系を指定すると、エラーコード A0026 が返されます。
IETF BCP 47 形式に準拠しない言語タグを指定すると、エラーコード A0047 が返されます。

Cashier の言語を固定するには、paymentInfo.cashierLanguage を明示的に指定してください。

テーマカスタマイズ

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

ツールとリファレンス

ポイントチャージ API

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