本文へスキップ
JA
ログイン 会員登録
ドキュメント

公式資料

zittme Pay モジュール

zittme Pay は Zittme の決済ゲートウェイモジュールです。コマース・予約など他のモジュールの決済を一か所で処理し、決済履歴・キャンセル・ログの管理を提供します。サードパーティモジュールも、決められた規約に従うだけで zittme Pay による決済を組み込めます。

インストール

  1. ストアから zittme Pay モジュールをインストールします。
  2. 管理者 > zittme Pay で、設定・ゲートウェイ・決済履歴・ログの各タブを使います。

    3. 設定タブの全項目

    項目説明
    使用決済機能全体の on/off
    テストモード実際の承認なしで決済の流れを確認します。ゲートウェイのキーもテストキーを使ってください
    通貨初期値 KRW
    注文番号の接頭辞PG の管理画面で自サイトの注文を見分けるための表示（英数字8文字以内）
    部分キャンセルを許可決済金額の一部だけをキャンセルできるかどうか。オフにすると全額キャンセルのみ可能です
    キャンセル理由一覧キャンセル時に選ぶ理由。1行に1つずつ入力します
    PG 自動キャンセル期限（日）決済後この期間を過ぎると PG キャンセルを試みず、手動返金に回します。精算済みのカード決済は PG キャンセルができなくなるためです。0なら制限なし
    確定済み決済の強制キャンセルを許可購入確定済みの決済も管理者がキャンセルできるようにします。オフにすると、確定後はどの経路からもキャンセルされません
    管理者通知メール通知の受信アドレス
    通知イベント決済完了時 / キャンセル時それぞれの送信有無
    ログ保管日数決済ログの保管期間（0=無期限）
    Webhook IP 許可リストゲートウェイの Webhook を受け付ける IP を制限します。空欄なら制限なし
    決済画面の告知文通信販売業の届出番号など、決済画面の下部に表示する文面
    決済画面スキン決済・結果画面のスキン選択

    ゲートウェイタブ（決済手段）

    使用する決済手段をオンにし、手段ごとの情報を入力します。

    Toss Payments(カードなど)

    項目説明
    クライアントキーToss Payments 開発者センターで発行
    シークレットキー同上。絶対に外部に公開しないでください

    テストキー + テストモードで流れを確認してから、ライブキーに切り替える順序をおすすめします。キーの種類（テスト/ライブ）とモードが合っていないと、承認に失敗します。

    KG イニシス

    項目説明
    加盟店 ID(MID)イニシスの加盟店管理画面で発行
    Sign Key決済画面の署名に使用
    INIAPI Keyキャンセル・返金専用のキー。加盟店管理画面で別途発行

    テストモードでは、公開テスト加盟店(mid INIpayTest)のキーを使って、契約前でも決済画面まで確認できます。承認通信が途切れたり金額が合わなかったりした場合は自動的にネットキャンセルされ、二重決済が防止されます。

    NHN KCP

    項目説明
    サイトコード（site_cd）KCP で発行。テストは T0000
    サービス証明書KCP 管理画面の認証センターで受け取った PEM ファイルの内容をそのまま貼り付けます
    加盟店秘密鍵・パスワードキャンセル・返金リクエストの電子署名にのみ使用されます

    NICEPAY

    項目説明
    Client IDNICEPAY 開発者センター（developers.nicepay.co.kr）で発行
    Secret Key同上

    開発者センターに登録するだけでサンドボックスキーを取得できるため、契約前でも決済・キャンセルの流れをテストできます。テストモードがオンの場合は、サンドボックスサーバーに自動で接続されます。

    PortOne(V2)

    項目説明
    Store IDPortOne コンソール（portone.io）で発行
    チャネルキーどの PG で決済するかは、PortOne コンソールのチャネル設定で決めます
    V2 API Secretサーバーでの承認・キャンセルに使用

    1つのドライバーで、PortOne に接続された複数の PG を使えます。テストはテストチャネルのキーを入力すれば行えます。

    PayPal(海外決済)

    項目説明
    Client ID · SecretPayPal 開発者コンソール（developer.paypal.com）のアプリで発行。テストモードではサンドボックスアプリのキーを使用
    決済通貨PayPal は KRW に対応していません。ウォン建ての注文をこの通貨に換算して決済します（初期値 USD）

    換算には下記の共通為替レートが使われ、返金は決済時点のレートで処理されます。外貨建ての注文（コマースの多通貨）は、換算せずにその通貨で直接決済されます。

    Conekta(メキシコ・中南米)

    メキシコの決済会社 Conekta のホスト型決済ページで、カード、現金（OXXO コンビニ）、口座振込（SPEI）を受け付けます。「決済する」を押すと Conekta の決済ページに移動し、決済が終わるとサイトに戻ります。現金と口座振込は参照番号または口座が発行されただけの「入金待ち」状態で戻り、実際の入金は Webhook で確定されます。

    項目説明
    Conekta 秘密鍵Conekta パネル > Desarrolladores > API Keys で作成した秘密鍵(key_ で始まる)。公開鍵は使いません
    Webhook URL画面に表示された URL を Conekta パネル > Desarrolladores > Webhooks に登録します。現金・口座振込の入金確定に必須です
    決済手段決済ページで提供する手段を選びます。カード / 現金（OXXO） / 口座振込（SPEI）。空欄ならすべて
    決済通貨ウォン建ての注文を換算する通貨。初期値 MXN。OXXO と SPEI は MXN のみ対応し、USD のカード決済は Conekta のアカウント種別によって利用できます
    ウォン建て注文を許可オンにすると、ウォン建ての注文を共通為替レートで換算して決済します。為替レート表に決済通貨（MXN）の行が必要です

    テストキーの取得

    1. panel.conekta.com に登録し、「Explorar panel」（パネルを見てみる）から入ると、事業者審査なしでテスト会社が作成されます。
    2. 左下の「Modo pruebas」（テストモード）をオンにし、Desarrolladores > 「Consultar API Keys de prueba」で「Crear nueva llave privada」から秘密鍵を作成します。秘密鍵は作成した瞬間に一度しか表示されないため、すぐにコピーしてください。
    3. ゲートウェイタブに秘密鍵を入力して「接続テスト」を押すと、モード（サンドボックス / 本番）が表示されます。テストキーには専用の接頭辞がないため、モードは Conekta の応答で判定します。注文を一度作成するまでは「要確認」と表示されることがあります。
    4. Desarrolladores > Webhooks > 「Crear Webhook」に上記の Webhook URL を入力し、イベントをすべてオンにします。どのイベントが届いても zittme Pay は注文を Conekta API で再照会してから確定するため、偽造された通知で決済が確定することはありません。

      5. テスト決済

      • 承認カード: 4242 4242 4242 4242（Visa）、5555 5555 5555 4444（Mastercard）。名前と CVC は任意の値、有効期限は未来の日付。
      • 拒否カード: 4000 0000 0000 0002、残高不足: 4000 0000 0000 0127。
      • 口座振込（SPEI）は、発行された CLABE で Conekta のサンドボックス入金通知 API(/sandbox/spei/payment_notifications)を呼び出すと入金処理されます。現金（OXXO）はサンドボックスでしばらくすると自動的に入金処理されます。

      本番キー

      Conekta の規約上、本番アカウントにはメキシコ法に基づいて設立された事業者（RFC 保有）とメキシコの精算口座が必要です。審査が終われば、パネルの本番キーを同じ欄に入力するだけです。返金はカード決済のみ API で処理され、現金・口座振込の決済は手動返金に回されます。

      銀行振込

      項目説明
      振込先口座銀行・口座番号・口座名義を複数登録。購入者が注文時に口座を選びます
      振込期限（日）1〜30日。期限を過ぎた未入金の注文は自動キャンセルの対象になります

      入金確認は決済履歴で管理者が行い、確認すると連携モジュールの注文が決済完了に移ります。

      共通為替レート

      ゲートウェイタブで通貨別の為替レート（1通貨あたりの KRW）を管理します。zittme Pay の決済換算とコマースモジュールの多通貨価格が共にこの値を参照する、単一の基準です。

      項目説明
      為替レート表通貨コード（USD など）とレートを登録します
      手動固定チェックした通貨は自動更新で上書きされません
      自動更新1日1回更新。取得元は open.er-api.com（キー不要）または韓国輸出入銀行（API キーが必要）から選択

      自動更新に失敗しても最後に成功した値が維持され、注文には決済時点のレートが保存されるため、その後のレート変動の影響を受けません。

      外貨決済

      コマースなどの連携モジュールが外貨建ての注文を渡すと、その通貨で決済します。注文通貨に対応していない決済手段は決済画面に表示されません（国内 PG は KRW 専用、PayPal は主要24通貨に対応）。金額表記は通貨記号と桁数に合わせて自動で処理されます。

      決済の流れ

      1. 連携モジュール（コマースなど）の注文フォームで決済手段を選び、「決済する」を押します。
      2. カード: Toss Payments の決済画面で承認 → 結果画面。/ 銀行振込: 口座案内と振込期限が表示された結果画面 → 管理者の入金確認で決済完了。
      3. 決済状態の変更は連携モジュールに即時反映され、ゲートウェイの Webhook でも二重に確認します。

        4. 注文番号と決済番号

        購入者に番号が2つ表示されると混乱するため、次の原則で表記します。

        番号発行元表記
        注文番号決済をリクエストしたモジュール（コマース・予約など）決済画面・結果画面・履歴でメインとして大きく
        決済番号zittme Pay補助として小さく。決済の問い合わせ・キャンセル処理の基準

        決済履歴とキャンセル

        • 決済履歴：すべての決済を状態・期間・決済手段で検索し、1件ごとに承認情報・連携モジュールの注文番号・処理履歴を確認します。
        • キャンセル：各決済から全額または部分キャンセル（許可時）を実行します。カード決済はゲートウェイにキャンセルが伝えられ、銀行振込は返金処理として記録します。キャンセル理由は設定の理由一覧から選びます。
        • PG 自動キャンセル期限を過ぎた決済：PG キャンセルの代わりに手動返金で処理するよう案内されます。
        • ログ：ゲートウェイのリクエスト/レスポンスと Webhook の受信が記録され、保管期間を過ぎると整理されます。決済の問題を調査するときに確認します。

        ログの読み方

        ログタブには、決済代行会社とやり取りした内容が時系列で蓄積されます。決済が失敗したときや入金が確認されないときは、まずここを確認してください。

        レスポンス欄には、原文の代わりに一行の要約が表示されます。

        • 代行会社が失敗理由を返した場合は、その文言をそのまま表示します。카드 한도 초과、유효하지 않은 카드번호 のような形です。
        • 銀行振込の決済は、発行された口座・振込名義・振込期限を整理して表示します。
        • 要約できる内容がない場合は、原文の先頭部分を切り出して表示します。

        原文全体が必要な場合は、要約文にマウスを重ねてください。代行会社から届いたレスポンスがそのまま表示されます。問い合わせる際は、この原文を添付してください。

        レスポンスが空の場合は、リクエストが代行会社に届かなかったケースです。ゲートウェイタブの認証情報と、サーバーの外部接続がブロックされていないかを確認してください。

        サードパーティモジュールとの連携（開発者向け）

        他のモジュールから zittme Pay で決済を組み込む規約はシンプルです。

        1. 決済作成（createOrder）の呼び出し時に、source_code パラメーターに自モジュールの注文番号を渡します。
        2. すると決済画面・結果画面・管理履歴でその番号が「注文番号」としてメイン表示され、zittme Pay のコードは「決済番号」として表記されます。
        3. 決済完了・キャンセルのコールバックで、自モジュールの注文状態を更新します。

          4. コマースと予約モジュールが、この規約の参照実装です。モジュール開発の一般的な規約は、開発者ガイドの「モジュール制作」ドキュメントもあわせてご覧ください。

          よくある質問

          • テスト決済ができません：テストモードかどうかと、Toss Payments のキーがテストキーかどうかを確認してください。
          • 銀行振込の注文がずっと決済待ちのままです：銀行振込は、管理者が入金確認を押すと決済完了になります。振込期限を設定しておくと、放置された未入金の注文が自動で整理されます。
          • 部分キャンセルのボタンが表示されません：設定で部分キャンセルの許可がオフになっていると、全額キャンセルのみ可能です。
          • 古いカード決済のキャンセルに失敗します：PG の精算が終わった決済はカードキャンセルができなくなります。PG 自動キャンセル期限の設定に従い、手動返金で処理してください。
          • Webhook が届きません：Webhook IP 許可リストにゲートウェイの IP が漏れていないか確認してください。空欄にすると制限なしで受け付けます。
          • 新しい決済手段が決済画面に表示されません：ゲートウェイタブでその手段をオンにし、キーまで入力すると表示されます。キーが空欄だと一覧に表示されません。
          • PayPal が無効になっています：Client ID · Secret に加えて、共通為替レートに決済通貨（初期値 USD）のレートが登録されている必要があります。
          • 決済画面のスキンを変更しても元に戻ってしまいます：0.2.0 で修正されました。モジュールをアップデートしてください。
          • 決済を終えて戻ると「このリクエストでは使用できない HTTP メソッドです」と表示されます：0.2.9 以下で、Conekta・PortOne のように決済画面が別サイトに移動してから GET で戻ってくる PG を使う場合に起きる問題です。0.2.10 からはコールバックが GET・POST の両方を受け付けるので、管理者 > 資料室で zittme Pay をアップデートしてください。決済自体は PG で正常に処理されているため、エラーになった注文は決済履歴で再照会すると承認状態に揃います。