Docy Documentation

本ドキュメントについて

目的

本ドキュメントは、「国際ブランドが付帯したカードの決済」「PayPayオンライン決済」「Paidy決済」「銀行振込決済」「コンビニ決済」「Alipay Online決済」「Alipay + Online決済」「Wechat Online決済」を行うために、univapay.comドメインで展開する決済システム（以降「本サービス」という）の利用について記述したものす。

本ドキュメントは、加盟店さまやシステム連携先さまに、本サービスを利用開始するまでの設計・開発を可能とするためのものです。

本ドキュメントは、予告なく変更されることがあります。

使用言語

本ドキュメントは、日本語を使用して作成しています。
他言語で閲覧したい場合は、ブラウザの翻訳機能を利用してください。

問い合わせは、日本語・英語にて受け付けています。

パラメータの表記ルール

本ドキュメントでは、各プログラミング言語の仕様に準じ、以下の通り表記しています。

メタ構文変数

本ドキュメントでは、上記表のように「メタ構文変数」を、foo bar baz qux quux … と表記します。これらを「実際には様々変化し得る部分」と解釈してください。

クレジットカード情報の送信を伴う処理について

消費者のクレジットカード情報を加盟店サイト内に入力（通過か保持）させ、本サービスの APIに送信する場合は、カード情報の「通過」にあたるため、加盟店サイトがPCI DSSに準拠することが必要です。

システムの定期アップデートについて

本サービスは利便性や品質向上のため、隔週月曜日（※）の15時より小規模なシステムアップデートのリリースを行っています。

大幅な変更を伴うリリースはシステム連携先さまや加盟店さまへ事前通知しますが、軽微な更新は通知なく行いますので、ご承知おきください。

※定期リリース日時は改修内容よって、多少前後することがあります

動作確認しているブラウザ

以下以上のバージョンで、本サービスの動作を確認しています。

本サービスには、大きく分けて2通りの利用方法があります。
いずれの方法でも初期設定が必要です。

①本サービスと商用サイトとを連携せずに利用する

本サービスの管理画面を用いて、決済金額を加盟店さまにて設定し、作成したフォームのURLを消費者に提供することが可能です。
上記の運用方法の場合は、こちらをご覧ください。

②本サービスと商用サイトとを連携する

本サービスは、プログラムを記述することでオンライン上にある加盟店さまの商用サイトと連携することが可能です。
予め、システム連携先さまによって、簡易な設定のみで利用可能となっている場合もあります。

具体的には、以下のよう「初回決済（トークン化）のリクエスト方法」と「決済結果の取得方法」を設計・開発することを本サービスでは「連携」と定義しています。

初回決済（またはトークン化）のリクエスト方法

• ウィジェット
• インラインフォーム
• リンクフォーム

の3通りのインターフェイスを用意しています。詳しくはリンク先を参照してください。

PCI-DSSに準拠している加盟店さまの場合、APIに対して直接カード情報を送信して決済することも可能です。

決済結果の取得方法

決済の完了後には、ウェブフックやAPIへのリクエストで結果を取得できます。

ただし、ウェブフックによる結果取得はあくまで簡易的なもので、到達を保証するものではありません。エラーの種類によってはリトライを実行します。詳細はこちらをご覧下さい。
何かしらの原因で取得できなかった場合は、APIにリクエストすることで能動的に取得することを推奨します。

本サービスを利用するためには、いくつかの設定を管理画面で行う必要があります。
このページでは、利用開始までの大まかな流れを説明します。

1. アプリトークンの作成

アプリトークンとは、どの店舗で決済を行うかの判別のためのキーとして機能します。
全ての決済でアプリトークンは必須です。

管理画面＞アプリトークンの「新規作成」を押下し「店舗」のアプリトークンを作成してください。
利用方法によってアプリトークン作成時の行動および次に読むページが異なるため、以下を参照ください。

2. ウェブフックの作成（任意）

ウェブフックを作成すると、本サービスでの処理結果を、加盟店さまが指定したURLにHTTP POSTリクエストで通知するようになります。
消費者の遷移とは近いタイミングで実行しますが、必ずしも同期するとは限りません。

加盟店さま側のシステム（カートや受注管理のシステム）と連携したい場合は作成してください。

ただし、ウェブフックはあくまでも即時性を担保するための簡易的な仕組みで、到達を保証するものではないため、決済結果の判定をウェブフックのみに依存することは非推奨です。
精度の高い判定を求める場合は、APIへ決済結果取得をリクエストする仕組みを設計、実装してください。

画面遷移のコントロールがしたい場合は、ウィジェットやインラインフォームからのコールバック、リンクフォームからのリダイレクト設定でも可能です。

ウェブフックを受信する仕組みの作成には、SDKを利用できます。

メールや管理画面で処理結果を確認するので十分なら、この設定は必要ありません。

※詳細はこちら

3. 決済フォームと課金方式の種類を選ぶ

アプリトークンとウェブフックを作成した後は、サイト構成やサービス内容に沿った、当社の決済フォームと課金方式を選びます。

①決済フォームの種類を選ぶ

• ウィジェット（全ての支払い方法が利用可能）
• インラインフォーム（クレジットカードのみ利用可能）
• リンクフォーム（全ての支払い方法が利用可能）
  
  ※各決済フォームの詳細、選び方についてはこちら

②課金方式を選ぶ

• 都度課金（全ての支払い方法で可能）
• 定期課金（クレジットカード/Paidy で可能）
• リカーリング課金（クレジットカード／銀行振込／コンビニ決済／Paidy で可能）
  
  ※各課金方式の詳細、選び方についてはこちら

4. 各種フォームの設置

実際に消費者が利用するフォームを作成、設置します。
詳細は、各決済フォームのセットアップページをご覧ください。

• ウィジェットの設置（HTML、Javascript）
• インラインフォームの設置（HTML、Javascript）
• リンクフォームの設置

それぞれのセットアップにはSDKが利用できます。

5. 決済フォームを公開する

公開前には、必ずテストモードでフォームが意図した通りに動作しているかを確認してください。（テストモードのアプリトークンを作成することでテスト決済が可能です）
※クレジット決済の場合は管理画面の「テスト課金」にあるカード番号でテストができます。　

行われた決済は管理画面で確認・操作が可能です。

管理画面の使い方はこちらをご覧ください。

本サービスは、現段階ではオンラインでの決済にのみ対応しています。
各銘柄のロゴを利用したい場合は、ロゴの下にあるボタンをクリックしてダウンロードしてください。

クレジットカード

消費者が決済フォームにカード番号などの必要情報を入力し、決済します。

非対面の取引※に限り、利用可能です。
※磁気テープやICチップのスキャンを行わない

利用できるのは、国際ブランド（VISA / Mastercard / JCB  / American Express / Diners Club / DISCOVER）のマークが券面に記載されたクレジットカードです。

Paidy

購入代金を自由な形で翌月にまとめて支払うことができるサービスです。
決済フォームでメールアドレスと電話番号を入力し、SMS認証を行って決済します。

ブランドガイドライン

銀行振込

決済ごとに専用の口座が消費者へ発行され、振込確認を自動で行います。
発行する口座は「GMOあおぞらネット銀行」のものです。

コンビニ決済

株式会社電算システムの提供する、前払い式のコンビニ決済です。

決済フォームから消費者情報を入力することで、各種コンビニエンスストアで支払うための情報が発行され、消費者が入金をすることで決済が完了します。

オンラインモバイル

消費者が決済フォームからモバイルペイメントアプリで認証することで、オンラインでの決済を行います。
詳細はこちらを参照ください。

管理画面ガイド

本ガイドでは、当社が提供している管理画面の構成や利用方法を説明しています。

下記の画像付き資料をご確認ください。

管理画面ガイド（PDFファイル）

もっとも簡単な利用方法

本サービスで最も簡単なご利用方法は「リンクフォーム決済」です。

決済金額を加盟店にて設定し、作成したフォームのURLを消費者に提供する単純な決済方法です。

下記の画像付き資料をご確認ください。

リンクフォーム決済の設定方法（PDFファイル）

決済フォームとは、決済や申込のために消費者が情報を入力する画面のことです。
本サービスでは3種のフォームを選択可能です。加盟店さまの利用イメージに沿ったフォームを選択してください。

フォームのセキュリティ

本サービスの全てのフォームは、加盟店さまのwebサイトにカード情報が通過することがなく、保存することも処理することもありません。
これにより、カード情報の漏洩リスクを最小限に抑えながら、柔軟な課金方式で商用サイトを運用できます。

決済フォームの選択基準

消費者の支払いフロー

当社決済フォームを利用した場合の、決済手段ごとの支払いフローは、下記の画像付き資料を参照してください。

消費者の支払いフロー（PDFファイル）

ジェネレータでタグをかんたん出力

プログラミングの難しい加盟店さま向けに、指定されたパラメータでの各種決済フォーム用のタグを出力するジェネレータを管理画面内に用意しています。　※利用方法はこちら

もちろん、各種パラメータを変数として、動的にタグ出力するプログラムを作成いただくことも問題ありません。
そのためのSDKもこちらに用意しています。

トークンとは、カード情報（カード番号と有効期限）を復号できないよう、ランダムな文字列に暗号化したもののことです。

本サービスの決済フォームでは、消費者が入力したカード情報を自動的にトークンへ置き換える処理を行います。
これを「トークン化」といいます。

トークンには複数の種類があります。
どの種類のトークンを作成するか、トークンを用いてどのような処理を行うかは、加盟店さまが自由に指定できます。
行える処理については、ページ下部「チェックアウトタイプとトークンタイプの見取り図」を参照してください。

トークンの種別

当社サービスで発行できるトークンの種別（token-type）には以下の3つがあります。

one_time（ワンタイムトークン）

ワンタイムトークンは1回だけ課金を作ることができ、有効期間は作成から5分間です。
大量の課金を処理するために、並行して複数のワンタイムトークンを作ることができますが、一定期間内に同一のカードで課金できる回数には制限があります。

subscription（定期課金トークン）

一定のスケジュールで消費者に請求をする必要がある場合、定期課金トークンの利用を推奨します。
このトークンは定期課金を作成することができ、定期課金では課金の間隔、初回金額、定期課金金額、開始日を指定することができます。
このトークンの有効期間は作成から5分間です。定期課金はキャンセルされるまで期限なしで継続されますが、課金回数を指定した定期課金の作成も可能です。

※当システムでは同一カード番号で定期課金トークンを作成できるのは1つまでのため、5分以内に同一カード番号を入力して送信するとエラーが発生します。
定期課金トークンに対して課金されると再度作成が可能になります。

recurring（リカーリングトークン）

一度決済したクレジットカードで、任意のタイミングで再び決済を行いたい場合はリカーリングトークンの作成を推奨します。
トークンが作成されると、その個人情報は UnivaPay のプラットフォーム上に安全に保管されます。

初回の処理で課金を行わずカード情報の登録のみ行う運用の場合は、セキュリティコード認証を行うように実装する必要があります。
上記運用でセキュリティコード認証を行わない場合、作成後5分以内にトークンが使用されないとCVVは自動的に期限切れになり、それ以降の課金は失敗します。
※詳細はこちら

トークン作成時のチェックアウト種別

トークン作成時のチェックアウト（checkout-type）の種類は、以下2通りです。
表内で動作を説明します。

トークン種別とチェックアウト種別の見取り図

「処理」の種類

本サービスには、4つの処理があります。
決済フォームのタグやコードを設置したり、書き出す際には以下を参照してください。

「課金」の種類

本サービスには3つの課金種類があります。
決済フォームのタグやコードを設置したり、書き出す際には以下を参照してください。

本サービスとシステム連携して、注文や消費者のデータベースへ、支払い状態を反映する必要がある場合は、ウェブフックを受信してデータベースへの書き込みを行うプログラムを作成・設置してください。

ウェブフックの実行はベストエフォートであるため、対象のサーバや回線の状況によっては受信に失敗することがあります。

したがって、処理結果の判定をウェブフックで行うことは問題ありませんが、本来、処理結果を受信しているべきだが未受信ステータスの注文情報を、加盟店さまのデータベース上で検知した場合には、本サービスのAPIへ能動的に

• GET（条件を指定し、単数の処理情報取得）
• LIST（条件を指定し、複数の処理情報取得）

へのリクエストを行い、補完することを推奨します。

コールバックを結果判定に用いる場合

ウィジェットまたはインラインフォームを利用する場合、ウェブフックだけでなく、処理の完了後に行われるJavaScriptのコールバックも結果判定に利用できます。
ただし、

• 処理中の消費者に回線の不調や断絶が起きた場合
• 処理中に加盟店さまのサーバや回線の不調やダウンがあった場合

には、受け取れない場合がありますので、ウェブフックと同様にGET/LISTによる補完をしてください。

また、以下についても注意してください。

【重要】アクワイアラやセンター毎に異なる挙動

一部のアクワイアラ（カード会社）やセンター（カード会社と紐づくオンライン処理用のセンター）では、リクエストが行われた場合、処理がラグをもって段階的に行われることがあります。
特に、海外クレジットカード会社に接続している場合は、一般的に数分ほどのラグをもって処理が行われます。

当システムの仕様

当社からアクワイアラへリクエストを行った後、GETリクエストを定期的に行うことで結果を取得し、ステータスを反映する仕様です。
そのため、capture、refund、cancelのリクエストを行った場合、ステータスが段階的に変化します。
返却されるステータスは、リクエストによって異なります。

※アクワイアラやセンターのメンテナンスや障害、通信状況などによってauthorizedの状態が続くことがあります。

また、決済フォーム（リンクフォーム / ウィジェット / インラインフォーム）より消費者が課金を行う場合、当社からアクワイアラへ課金リクエストが成功した時点で完了画面へ遷移する仕様です。

海外クレジットカード会社に接続している加盟店さまの実装方法

課金のGETリクエストやコールバックで課金が作成されたことを確認し、authorizedの確認をもって次の処理を実行する等、数分ほどのラグを考慮した実装を推奨します。
サービスや商品の提供は、継続的な課金のGETリクエスト（ポーリング機能の活用等）によってステータスが successful に更新されたことを必ず確認してから行ってください。

トークンタイプにrecurringを指定する場合は、繰り返し課金を目的としたトークンの保存を行うことについて、消費者に対して必ず事前の同意承諾を得るか、加盟店サイト内で十分な告知※を行ってください。

万が一、同意の取得や告知が十分でなかった場合は、消費者から加盟店さまに対して、支払いに対する異議や抗弁の申し立てがされる場合があります。

また、そのような事態が連続した場合は、カード会社から加盟店さまに対して加盟契約解除を言い渡されることがありますが、当社ではその責任を一切負いかねます。予めご了承ください。

「十分な告知」とは

告知内容例

ウィジェットボタンの直下など、消費者が確認しやすい場所にに注意書きを設置してください。
なお、インラインフォームをご利用の場合は、インラインフォームが含まれる前のページか、インラインフォームの付近に、注意書きを設置してください。

本サービスにはいくつかの制限があります。

IPアドレス制限（連続失敗回数、IP拒否）

同一のグローバルIPアドレスから決済を連続で失敗した場合、そのIPアドレスに対して12時間の制限をかけます。
1つの加盟店で制限されたIPアドレスは他加盟店でも制限され、制限のかかったIPアドレスから管理画面にアクセスすると、
管理画面＞店舗＞リンクフォーム設定上にエラーが表示されます。

• 制限の対象となる決済
  モード：本番モード
  決済手段：すべて
  決済経路：課金フォームからの決済（リカーリング課金含む）
  　　　　　※CSV課金は対象外
• 制限がかかった場合の挙動
  エラーになり履歴に残らない
  エラーコード：「SERVICE_RESTRICTED」
  HTTPレスポンスコード：「429」
  決済完了画面：メッセージ「失敗回数が上限に達したため、一定時間サービスを利用できません。時間をおいて再度お試しください。」と表示

返金制限

1か月間の課金額より返金額が上回る場合は返金不可の制限をかけます。

海外カード拒否

海外で発行されたカードでの決済を拒否します。
決済フォームでカード入力時に「許可されていない国のカードです。」とエラーが表示されます。

管理画面から制限の有無が設定可能です。

短時間での大量のリクエストの制限

短時間で大量のリクエストをした場合に制限をかけます。
詳細はAPI制限のページを確認してください。

このページでは、本ドキュメントで使用している用語の意味を説明します。
※あくまで本ドキュメント内における用語の意味です。

あ行

か行

さ行

た行

な行

は行

ま行

や行

ら行

英数字・記号

開発が完了したら、必ず公開前にデモ環境などで各動作の検証を行ってください。
検証が完了したら、本番モードのアプリトークンの作成・適用後に決済機能を公開してください。

テスト決済用のカード番号

テストモードの決済で利用できるカード番号は、管理画面＞テスト課金 から取得できます。
カード番号によって確認できる挙動が異なるため、加盟店さまの目的に沿った番号を利用してください。

テスト決済用のカード番号のため、本番モードでは利用できません。

また、計算ルールに基づいたカード番号であれば、その他のカード番号も利用可能です。
カード番号を生成できるサイト等を活用すると、簡単に作成できます。
例：https://www.getcreditcardnumbers.com/
※その他のカード番号を利用する場合は、決済成功 / 返金成功の挙動になります。

失敗・エラーの挙動の確認

テストモードの場合、消費者情報として決済時に入力するメールアドレスの「@」の前に +charge-failure-●●●（発生させたいエラーコード）を追加することで、エラーコード毎の挙動を確認できます。
※4、6から始まるエラーコードは利用できません。

例： test+charge-failure-309@univapay.com

エラーコード一覧は『エラーコード – 概要』のページを参照してください。

テストモードの特性

テストモードの決済は30日後に自動的に削除されます。
紐づくトークンや課金、返金などの情報もすべて削除されます。

ウィジェットは、消費者がカード情報を入力するためのインターフェイスで、ポップアップウインドウとして表示されるタイプのフォームです。

ウィジェットの役割

ウィジェットは、以下の役割を果たします。

支払い方法の選択

消費者に、希望の支払い方法をクリック（またはタップ）で選択させます。

この選択画面で表示される選択肢は、ウィジェットのタグまたはコードの記述内容に依存します。なお、支払い方法を単一に指定した場合、この選択画面は省略されます。

必須情報の入力

選択された「支払い方法」毎に予め設定されている必須情報を、消費者に入力させます。

入力欄はウィジェットのタグまたはコードの記述内容によって、追加することも可能です。
詳しくはこちら

ウィジェットで行われる処理

選択された「支払い方法」毎に、各種処理を行います。

一部、赤字※印の項目は申込完了後、消費者が支払いを行うのを待機します。
誤って「決済完了」とみなさないよう、くれぐれも注意してください。

ウィジェット内の表示項目

ウィジェット内の表示項目は、設置時のパラメータによって以下を制御可能です。

• ヘッダーテキスト
• ヘッダー説明文
• 支払いボタンのテキスト
• QRコードの色（オンラインモバイルでのみ有効）
• QRコード内のロゴ
• 任意のフィールド（入力欄）追加

詳しくはこちら

ウィジェットのデザイン

管理画面から、ウィジェットのデザインを編集可能です。

店舗＞一般＞全体設定＞ブランディング　から、PNGまたはJPGで店舗アイコンを編集できます。
未編集の場合は標準（デフォルト）の画像が表示されます。

店舗＞決済フォーム＞ウィジェット＞テーマ　から、タイトル背景とメイン（タイトルバーとボタンに使用）のカラーが編集可能です。

消費者の支払いフロー

ウィジェットを利用した場合の決済手段ごとの支払いフローは、下記の画像付き資料を参照してください。

消費者の支払いフロー（PDFファイル）

このページは初期設定が完了し、ウィジェットの概要が通読されていることを前提に作成しています。

「ウィジェットの概要」で説明の通り、支払い方法の選択次第で「決済」でなく「申込」がなされる可能性があるため、このページでは、ウィジェットで行われる「決済または申込」を「処理」と表現します。

HTMLで設置する

ウィジェットをHTMLで設置するには、1行の<script>タグと、1つの<form>タグを用います。

<form>タグの中には<span>要素でパラメータ（各種フィールドとその値）を記述します。

アプリトークンは非常に長く規則性のない文字列なので、事前に管理画面でアプリトークンを控えるか、ジェネレータからのコピーを推奨します。

サンプルコード

以下は、「支払う」と表示されたボタンでの、1000円を決済するためのウィジェットの設置例です。

<script src="https://widget.univapay.com/client/checkout.js"></script>
<form action="<任意のURL>">
 <span data-app-id="<アプリトークンID>"
      data-txt="支払う"
      data-checkout="payment"
      data-amount="1000"
      data-currency="jpy"
      data-auto-submit="true"
 ></span>
</form>

処理完了後の動作

処理の完了後、form action= で指定した”<任意のURL>”に対し、以下をsubmitします。

• トランザクショントークン（data-checkout-type=“token”指定時には univapayTokenId）
• 決済番号（data-checkout-type=“payment” 指定時には univapayChargeId 、data-token-type=“subscription” 指定時には univapaySubscriptionId）

処理結果によって、消費者の画面遷移をコントロールしたい場合は、これらを取得するプログラムを作成してください。

パラメータ（基本動作）で解説の通り、data-auto-submitを利用することにより、完了ボタンを押してウィジェットを閉じた時、ウィジェットが含まれるフォームを自動でsubmitする設定も可能です。

上記を利用して、spanタグの外側に設置したformタグのaction属性に指定したURLに遷移するようにすることも可能です。

JavaScriptで設置する

Javascriptでウィジェットを設定する際は、<script>タグを利用することで、HTMLファイル内にJacaScriptのコードを埋め込んでウィジェットを設置することもできます。

サンプルコード

以下は、「支払う」と表示されたボタンでの、1000円を決済するためのウィジェットの設置例です。

<script src="https://widget.univapay.com/client/checkout.js"></script>

<form id="payment-form" action="https://docs.univapay.com/docs/guide/implement/widget">
  <button id="univapay-payment-checkout">
   支払う
  </button>
</form>

<script>
  var checkout = UnivapayCheckout.create({
    appId: "<TOKEN>",
    checkout: "payment",
    amount: 100,
    currency: "jpy",
    cvvAuthorize: true,

    onSuccess: function () {
      var form = document.querySelector("#payment-form");
      form.submit();
    }
  });

  var button = document.querySelector("#univapay-payment-checkout");
  button.onclick = function () {
    checkout.open();
  };

</script>

まず、ウィジェットを含むページに次の行をHTMLでの設置と同様に含める必要があります。

<script src="https://widget.univapay.com/client/checkout.js"></script>

HTMLでの設置とは異なり、自動的にページ上にボタンは作成されませんので、<form>タグと<button>タグで送信するための記述をします。
submitイベントが発火に反応して、actionで指定されたURLに遷移します。

<form id="payment-form" action="https://docs.univapay.com/docs/guide/implement/widget">
  <button id="univapay-payment-checkout">
   支払う
  </button>
</form>

<script>
<!--
タグ内にJavaScriptの記述をします
内容は以下で説明
-->
</script>

次に、UnivapayCheckout.createを呼び出す記述をします。
例えば、1000円の支払いを処理するウィジェット・オブジェクトを作成するには、以下を記述する必要があります。

var checkout = UnivapayCheckout.create({
  appId: "<TOKEN>",
  checkout: "payment",
  amount: 1000,
  currency: "jpy",

次に、actionで指定したURLに遷移させるためのsubmitの処理を記述します。
今回はonSuccessを利用し、処理が成功したことでformをsubmitさせるような記述をします。

    onSuccess: function () {
      var form = document.querySelector("#payment-form");
      form.submit();
    }    
  });  

最後に、<button>タグのonclick関数の処理を記述します。UnivapayCheckout.createによって返されたオブジェクトでopen関数を呼び出すことにより、ウィジェットを開きます。

  var button = document.querySelector("#univapay-payment-checkout");
  button.onclick = function () {
    checkout.open();
  };

ウィジェットのデザインを制御するパラメータ

以下パラメータにより、ウィジェットのデザインが変更可能です。
その他、どんな処理をさせるか等の動作詳細は、左メニューから各種パラメータを参照のうえ、実装してください。

各フィールド名について

• data-で始まる、ケバブケース（kebab-case）で記載のフィールド名はHTML用
• 2行目にローワーキャメルケース（lowerCamelCase）で記載のフィールド名はJavaScript用
• いずれかしか記載のないものは、いずれかのみで利用可能

ウェブフック

処理の結果は、JSONデータとして管理画面の「Webhook」セクションで指定されたURLにPOSTされます。

「リファレンス > ウェブフック」を参照して、POSTされたデータを取得して注文状況などを更新するスクリプトを作成してください。

コールバック

ウィジェットタグ内のソースコードに下記の関数を定義しておくことで、各イベントが発生した時にその内容を含めた通知を実行します。
処理結果に応じて元のページの表示内容や、遷移先をコントロールしたい場合は、こちらか、フォームタグからsubmitされる値を利用してください。

コールバックのサンプル

<script>
    window.addEventListener("univapay:success", (e) => { console.info("Success event", e) }, false);
    window.addEventListener("univapay:token-created", (e) => { console.info("Token event", e) }, false);
    window.addEventListener("univapay:charge-created", (e) => { console.info("Charge event", e) }, false);
    window.addEventListener("univapay:subscription-created", (e) => { console.info("Subscription event", e) }, false);
    window.addEventListener("univapay:validation-error", (e) => { console.error("Validation error event", e) }, false);
</script>

ウィジェットの基本動作を制御するパラメータです。

定期課金、分割払い、デザインについては別途パラメータ解説ページがあり、左メニューから閲覧可能です。（デザイン用パラメータは、「ウィジェットの設置」ページに記載）

フィールド名について

• data-で始まる、ケバブケース（kebab-case）で記載のフィールド名はHTML用
• 2行目にローワーキャメルケース（lowerCamelCase）で記載のフィールド名はJavaScript用
• いずれかしか記載のないものは、いずれかのみで利用可能

ウィジェットで定期課金登録をする際に、定期課金の挙動を指定するパラメータです。

基本動作、分割払い、デザインについては別途パラメータ解説ページがあり、左メニューから閲覧可能です。（デザイン用パラメータは、「ウィジェットの設置」ページに記載）

フィールド名について

• data-で始まる、ケバブケース（kebab-case）で記載のフィールド名はHTML用
• 2行目にローワーキャメルケース（lowerCamelCase）で記載のフィールド名はJavaScript用
• いずれかしか記載のないものは、いずれかのみで利用可能

ウィジェットで、消費者に分割払いを選択させたい場合に、指定するパラメータです。
基本動作に加え、以下を指定してください。

フィールド名について

• data-で始まる、ケバブケース（kebab-case）で記載のフィールド名はHTML用
• 2行目にローワーキャメルケース（lowerCamelCase）で記載のフィールド名はJavaScript用
• いずれかしか記載のないものは、いずれかのみで利用可能

このページは「初期設定」が完了していることを前提に作成しています。

リンクフォームは、APIに対してHTTP GETメソッドで決済の詳細を送信することで、決済フォームのリソースを生成し、そこ消費者を遷移させ、決済後にリダイレクトすることができます。

加盟店さまの多くは、管理画面から店舗内にリンクフォームの設定をし、短縮URLをメール送信するか、サイト内に<a>タグとして設置する運用をすると想定しています。

そのため、原則的に不要と認識していますが、ここでは、APIの挙動を解説します。

プログラムの記述ができる方にとっては、リンクフォームを選択して動的にタグを書き出すことは、タグが長くなるだけで何のメリットもありません。
また、iframeタグを使用してウェブページへリンクフォームを埋め込む実装はできません。
そのため、動的にタグ出力をするのであれば、メリットの多いウィジェットを採用することを強く推奨します。

リンクフォームは、技術や予算の都合上、動的なタグ出力を行えない方を対象する機能とご認識ください。

リンクフォームの役割

リンクフォームは、以下の役割を果たします。

支払い方法の選択

消費者に、希望の支払い方法をクリック（またはタップ）で選択させます。

この選択画面で表示される選択肢は、リンクフォームのタグの記述内容に依存します。なお、支払い方法を単一に指定した場合、この選択画面は省略されます。

必須情報の入力

選択された「支払い方法」毎に予め設定されいる必須情報を、消費者に入力させます。

入力欄はタグの記述内容によって、追加することも可能です。
詳しくはこちら

APIのURL

https://checkout.univapay.com/forms/<各店舗のフォームID>

各店舗のフォームIDは、管理画面の店舗＞店舗名をクリック＞決済フォームタブ＞リンクフォーム設定＞URLコード
から確認してください。
forms/から?appIDの間に記載されています。

　例）https://checkout.univapay.com/forms/0a000ebb-caa0-00bf-ad0e-0de0e000fbe0?appId=xxx…

各種パラメータを?hoo=111&bar=222&baz=333…のように続けて記述したものを表示し、消費者の遷移を促してください。

タグのジェネレータ

管理画面の店舗＞店舗名をクリック＞決済フォームタブ＞リンクフォーム設定＞URLコード
で、各種設定を反映した、タグの生成が可能です。

管理画面から行える設定

管理画面の店舗＞店舗名をクリック＞決済フォームタブ＞リンクフォーム設定＞設定
で、リンクフォームの各種設定が可能です。

以下は、事前に管理画面から動作を設定できる内容です。

決済方法（ON／OFF）

以下は、タグで値を指定すれば、そちらを優先し、元の設定を無視します。

• クレジットカード
• コンビニ
• 銀行振込
• 他、オンラインモバイルの各銘柄

お客様情報（ON／OFF）

以下は、タグ設置時にの指定に関わらず、設定が優先されます。

• 名前を必須にする
• カナを必須にする
• メールアドレスを必須にする
• 電話番号を必須にする
• 住所を必須にする

言語（ドロップダウンメニュー）

言語は、タグで値を指定すれば、そちらを優先し、元の設定を無視します。

カスタムの入力欄

カスタムの入力欄は、タグで何かしらの値を指定すれば、そちらを優先し、元の設定を無視します。

リダイレクトURL

リダイレクトURLは、タグで何かしらの値を指定すれば、そちらを優先し、元の設定を無視します。
以下の処理ステータス毎に、別のURLを指定できます。

• 成功
• 処理待ち
• 失敗

テーマ

テーマの設定は、タグでの指定で変更することはできません。全てのフォームで統一されます。

• タイトル（ON／OFF）
  • 店舗名の表示
  • ロゴの表示
• テーマ（ラジオボタン）
  • ライト
  • ダーク
• カスタマイズ（カラーコード）
  • ヘッダー
  • ボタン
  • 背景
  • 内容の背景（カラム内側の色）

完了後の処理

処理の完了後は、パラメータによる指定通りに、消費者をリダイレクトします。

ウィジェットのようにリダイレクト時に結果をHTTP GETやSubmitで送信したり、JavaScriptのコールバックはできません。

一方で成功時と失敗時、それぞれのリダイレクト先は指定でき、追加したメタデータをHTTP GETメソッドで送信（消費者の遷移と同時に）できます。

したがって、処理後の画面遷移を制御することは可能ではありますが、送信先のURLは消費者からも可視であるため、処理結果の判定や、サービスを受ける権利の付与は行わない事を推奨します。
また、誤ってサービスを履行したり、物品を発送した場合でも、当社では一切の責任を負いかねます。

結果判定には、消費者から不可視の「GETによる取得」か、「ウェブフック」を用いることを推奨します。

消費者の支払いフロー

リンクフォームを利用した場合の決済手段ごとの支払いフローは、下記の画像付き資料を参照してください。

消費者の支払いフロー（PDFファイル）

フィールド名はローワーキャメルケースで記載する必要があります。
HTTP GETメソッドであるため、値を"（ダブルクォーテーション）で囲む必要はありません。

基本動作については別途パラメータ解説ページがあり、左メニューから閲覧可能です。

フィールド名はローワーキャメルケースで記載する必要があります。
HTTP GETメソッドであるため、値を"（ダブルクォーテーション）で囲む必要はありません。

定期課金

リンクフォームで定期課金登録をする際に、定期課金の挙動を指定するパラメータです。

分割払い

リンクフォームで消費者に分割払いを選択させたい場合に、指定するパラメータです。

このページは初期設定が完了していることを前提に作成しています。

インラインフォームは、インラインフレームに本サービスの決済フォームのリソースを表示し、消費者に直接カード情報を入力させて処理することを目的としたものです。

インラインフォームはクレジットカード決済のみを行うことができ、他の決済は利用できません。

インラインフォームの役割

インラインフォームは、以下の役割を果たします。

必須情報の入力

クレジットカード決済の際の必須情報を、消費者に入力させます。

入力欄はインラインフォームのタグ記述内容によって、追加することも可能です。
詳しくはこちら

インラインフォームで行われる処理

インラインフォームのデザイン

インラインフォームのデザインは、パラメータによって指定可能です。
設置先のサイトに、ある程度違和感なく溶け込むデザインを施すことができます。

詳しくはこちら

インラインフォーム設置用のタグ

インラインフォームのタグは、3部で構成されます。

1.本サービスの.jsファイルを読み込むための<script>タグ

<script src="https://widget.univapay.com/client/checkout.js"></script>

2.処理の内容を定義する<form>タグ

<form>タグ内の、空の<span>要素内の各属性で、処理の内容を定義します。

<form id="payment-form" action="<任意のURL>">
    <div id="checkout">
        <span
            data-app-id="{アプリトークンID}"
            data-checkout="payment"
            data-amount="1000"
            data-currency="jpy"
            data-inline="true"
        ></span>
    </div>

    <button id="pay-button" type="submit">Pay</button>
</form>

3.インラインフレーム内から処理後のデータを引き出すJavaScript

ここでは、インラインフレーム内からunivapayTokenIdを取り出して、<form>タグのaction属性の値として定義した「任意のURL」へsubmitする動作を記述しています。

この動作は、不要であれば省略できます。

<script>
    (function () {
        var form = document.getElementById("payment-form");
        var paymentButton = document.getElementById("pay-button");

        function getPaymentInfo() {
            event.preventDefault();

            var iFrame = document.querySelector("#checkout iframe");
            UnivapayCheckout.submit(iFrame)
                .then((data) => {
                    console.log(data);
                    // The `univapayTokenId` hidden input
                    // has been added with the token id
                    form.submit();
                })
                .catch((errors) => {
                    console.error(errors);
                    paymentButton.disabled = false;
                });
        }

        form.addEventListener("submit", getPaymentInfo);
    })();
</script>

インラインフォームのデザインを制御するパラメータ

全て、インラインでのstyle記述と同じルールで記述してください。
備考欄に記載の要素に、インラインでstyleの値が記述されます。

インラインフォーム設置用のタグ

以下は、「支払う」と表示されたボタンでの、1000円を決済するためのインラインフォームの設置例です。

<script src="https://widget.univapay.com/client/checkout.js"></script>
<style>
  #univapay-payment-checkout {
    position: absolute;
    top: 360px;
  }
</style>

<form id="payment-form" onSubmit="handleSubmit()">
  <button id="univapay-payment-checkout">
   支払う
  </button>
</form>

<script>
  var checkout = UnivapayCheckout.create({
    appId: "<アプリトークンID>",
    checkout: "payment",
    amount: 1000,
    currency: "jpy",
    cvvAuthorize: true,
    inline: true,
  });
  window.onload = function () {
    checkout.open();
  }
  function handleSubmit() {
    event.preventDefault();
    var form = document.getElementById("payment-form");
    var iFrame = document.querySelector("iframe");
    UnivapayCheckout.submit(iFrame)
      .then(function (data) {
        form.submit();
        }).catch(function (errors) {
          console.error(errors);
      });
  };
</script>

まず、インラインフォームを含むページに次の行をHTMLでの設置と同様に含める必要があります

<script src="https://widget.univapay.com/client/checkout.js"></script>

支払うボタンについてのCSS styleの記述です。説明の都合上styleタグに記述しています。

<style>
  #univapay-payment-checkout {
    position: absolute;
    top: 360px;
  }
</style>

HTMLでの設置とは異なり、自動的にページ上にボタンは作成されませんので、タグとタグで送信するための記述をします。
submitイベントが発火に反応して、onSubmitに指定された関数”handleSubmit()”を呼び出します。

<form id="payment-form" onSubmit="handleSubmit()">
  <button id="univapay-payment-checkout">
   支払う
  </button>
</form>

<script>
<!--
タグ内にJavaScriptの記述をします
内容は以下で説明
-->
</script>

次に、UnivapayCheckout.createを呼び出す記述をします。
例えば、1000円の支払いを処理するインラインフォーム・オブジェクトを作成するには、以下を記述する必要があります。

  var checkout = UnivapayCheckout.create({
    appId: "<アプリトークンID>",
    checkout: "payment",
    amount: 100,
    currency: "jpy",
    cvvAuthorize: true,
    inline: true,
    inlineItemLabelstyle:,
  });

本サンプルではページの読み込みをした時にインラインフォームを表示させるため、onload関数の記述をしています。
event.preventDefault();で、form.submit();の動作させるタイミングを制御するために、一度formのデフォルト処理を防ぐ記述をします。
最後にUnivapayCheckout.submitを呼び出す記述をします。ボタンをクリックした時実際に支払いを行う処理を記述し、送信時エラーが発生した場合はその内容を返します。

  window.onload = function () {
    checkout.open();
  }
  function handleSubmit() {
    event.preventDefault();
    var form = document.getElementById("payment-form");
    var iFrame = document.querySelector("iframe");
    UnivapayCheckout.submit(iFrame)
      .then(function (data) {
        form.submit();
        }).catch(function (errors) {
          console.error(errors);
      });
  };

処理実行時にパラメータの値を上書きする関数

UnivapayCheckout.updateを利用することで、トークン作成前に任意の項目の値を更新することが出来ます。
この関数を利用することで、例えばパラメータでダミーの電話番号やメールアドレスを事前にして項目を非表示にしている場合、決済フォーム以外で入力されている正しい消費者の情報を更新しながらトークンを作成することが出来ます。
更新することが出来る項目は以下です。

UnivapayCheckout.update(
  parameters: {
    metadata?: Record<string, string | number | boolean | null>;
    name?: string;
    nameKana?: string;
    email?: string;
    phoneNumber?: {
        countryCode?: string;
        localNumber?: string;
    };
    address?: {
        line1?: string;
        line2?: string;
        city?: string;
        state?: string;
        zip?: string;
        countryCode?: string;
    }
  },
  options?: {
    forceUpdate?: boolean; //消費者が決済フォームに情報を入力していたとしても強制的に更新するかどうか
  }
)

サンプル

UnivapayCheckout.update(
            iFrame,
            { email: "updated-dummy-email@univapay.com",
              phoneNumber: {
               countryCode: "+81",
               localNumber: "08000000000"
              }
             },
        );

インラインフォームのデザインを制御するパラメータ

全て、インラインでのstyle記述と同じルールで記述してください。
備考欄に記載の要素に、インラインでstyleの値が記述されます。

コールバック

ウィジェットのページに記載してある内容と同様です。

インラインフォームで扱えるパラメータは、ウィジェットで扱えるパラメータの一部です。
そのため、個別でページ作成をしていません。

以下より「インラインフォームで利用可」となっているもの（クレジットカードで処理できるもの）を選択し、記述してください。

• パラメータ（基本動作）
• パラメータ（定期課金）
• パラメータ（分割払い）

関数

任意でインラインフォームのパラメータで指定された情報を上書きするための関数があります。
メールアドレスや電話番号をダミーで指定し、項目を非表示にしている場合、実際のユーザー情報を更新させながら、トークンの作成処理を行うことが可能です。

UnivapayCheckout.update(
 parameters: { metadata?: Record<string, string | number | boolean | null>; 
  name?: string; 
  nameKana?: string; 
  email?: string; 
  phoneNumber?: {
   countryCode?: string;
   localNumber?: string;
   }; 
  address?: {
   line1?: string;
   line2?: string;
   city?: string;
   state?: string;
   zip?: string;
   countryCode?: string;
   }
  }, 
  options?: {
   forceUpdate?: boolean;
   }
  )

記述例

UnivapayCheckout.update(
            iFrame,
            { email: "updated-dummy-email@univapay.com" },
            // { forceUpdate: true } -> ユーザーが項目に値を入力していても強制的に上書き
        );

本サービスの銀行振込は、申込ごとに発行したユニークな口座番号への振込確認・消込を自動で行い、結果を反映する仕組みです。
利用する口座は「GMOあおぞらネット銀行」から発行されます。
これにより、手作業による振込確認と消込が必要なくなります。

銀行振込でサポートしている内容は、以下を参照してください。

課金方式

都度課金およびリカーリング課金を利用できます。
定期課金には利用できません。

実装方法

当社決済フォーム（リンクフォーム，ウィジェット）の設置と、APIでの連携が可能です。

処理

以下の処理は対応していないため、有効にしても無視されます。

消費者の支払いフロー

銀行振込の申込後、指定口座に振り込むと決済が完了される流れです。
当社決済フォームを利用した場合の消費者の支払いフローは、下記の画像付き資料を参照してください。

消費者の支払いフロー（PDFファイル）

課金ステータスと結果

管理画面＞決済　から申込や振込の履歴を確認できます。
また、「ステータス」と「結果」の2つの項目の組み合わせで、支払い状況を確認できます。
「ステータス」は決済履歴一覧および詳細画面の「課金詳細」から、「結果」は詳細画面の「支払い詳細」から確認できます。

課金ステータスの種類

処理待ち：口座を発行して未入金、または入金額に不足がある
成功：申込金額以上が入金されている　超過した場合も成功として扱う
失敗：申込金額の入金がなく、振込期限が切れた

発生し得る「ステータス」と「結果」の組み合わせ例

処理の基本フロー

以下フローは、管理画面＞一般設定＞決済サービス＞決済方法＞銀行振込＞振込の受付　が「すべて」の場合です。

テストモードの挙動

テストモードでは本番モードと挙動が異なります。
テストモードの挙動は下記のとおりです。

テストモードでリクエストすることで、メール通知とウェブフック（システム通知）を確認できます。
テストモードで確認できる処理は上記のみで、振込期限切れによる失敗や超過入金は確認できません。

口座の発行方法

口座の発行方法には「ワンタイム型」と「リカーリング型」の2種類があります。

ワンタイム型

1度限り使用可能なトークンを生成します。このトークンに対して課金リクエストを行うと、同じ消費者であっても1決済ごとに異なる口座番号を振込先として発行します。
そのため、毎回同じ口座番号を振込先として発行するリカーリング型と比べて、正確な入金管理を行うことができます。

リカーリング型（口座番号固定）

繰り返し使用可能なトークンを生成します。
このトークンに対して課金リクエストを行うと、消費者は毎回同じ振込先口座番号を利用できます。
リカーリングトークンは、何度でも繰り返し利用できます。

なお、1つのトークンで入金待ちの課金申込が複数存在する場合、古い課金申込が優先で消し込まれます。

消し込みの例

1つのトークンで入金待ちの課金申込が2つある場合

この状態で10,000円入金された場合

2022/1/1の課金申込に5000円分が入金され、金額丁度で成功となる
2022/1/15の課金申込に残り5,000円分が入金される

振込期限

管理画面で振込期限を設定できます。

また、課金申込時にウィジェット・リンクフォーム・APIそれぞれのパラメータを指定することで、決済ごとに異なる期限を指定できます。
各パラメータの指定方法は、利用ガイド「振込 – 要注意なパラメータ」を参照してください。
パラメータを指定しない場合は、管理画面の振込期限が適用されます。

振込期限を超えた課金申込はステータスが失敗となり、該当口座への振込を行うことができなくなります。

※「リカーリング型」は同じ口座で複数の課金申込が存在するため、該当口座に紐づく全ての課金ステータスが成功か失敗となった段階で、振込を行うことができなくなります。

管理画面での設定方法

一般設定＞決済サービス＞決済方法＞銀行振込＞振込のお支払い期限　から設定できます。
設定可能な振込期限のパターンとそれに対する期限の例（1/1に申し込みを行った場合）は下記です。

振込上限額

管理画面から振込上限額を設定することで、超過入金を防ぎ、返金対応を減らせます。

設定方法

管理画面＞一般設定＞決済サービス＞決済方法＞銀行振込＞振込の受付　から振込上限額を設定できます。

使用上の注意

口座への入金額に応じて、振込上限額がその都度更新されます。
そのため、「超過入金を防ぐ」を設定している場合でも、振込タイミング等により完全に防げない可能性があります。

また、「リカーリング型」は同じ口座で複数の課金申込が存在するため、該当口座に紐づく課金申込金額の合計が振込上限額として判断されます。

入金が反映されるタイミング

該当口座へ入金が確認できたら、時間帯や曜日を問わずおよそ1時間以内に課金ステータスおよび結果が更新されます。
なお、振込元金融機関の処理によっては、該当口座への入金が金融機関の翌営業日以降となる可能性があります。
入金予定時間は、振込元の金融機関にお問い合わせください。

結果の通知・確認

管理画面＞一般設定＞一般＞通知　で「銀行振込」の設定を有効にしている場合は、それぞれの処理に対応したメールが送信されます。
結果を加盟店さまの配送（または、それに準ずる会員ステータス等の）システムに自動で反映する必要がある場合は、ウェブフックで結果を受信して注文システムを更新するプログラムを設置してください。

※メールおよびウェブフックでの入金結果の通知には、2時間程度かかる場合があります。
　銀行振込の場合、ウェブフックのイベントは「課金」を利用して判定してください。
　また、銀行振込 / 不足入金 の通知はメールのみ対応しています。

また、結果はAPIへリクエストすることでも取得できます。
システム連動を行わず、管理画面またはメールで結果を確認する場合は作成する必要はありません。

以下では、銀行振込の各処理時に通知されるメールのテンプレートを抜粋して紹介します。

メンテナンスについて

GMOあおぞらネット銀行側で、定期的にシステムメンテナンスがあります。「課金申込」「入金通知」「請求停止」「振込期限切れによる口座停止」などの処理で、エラーや処理遅延が発生する可能性があります。予めご了承ください。
システムメンテナンス中に発生するエラーは以下です。

本ページは、銀行振込に対してパラメータを使用する場合に、注意すべき点の補足説明です。

事前に読むべきページ

このページでは、以下のページが読まれていることを前提に説明します。

ウィジェット

• ウィジェット – 概要
• 設置 – （HTML／JavaScript）

リンクフォーム

• リンクフォーム – 概要
• パラメータ（基本動作）

API

• 課金 – 概要
• 課金 – CREATE

表示させる決済手段の限定

課金作成時に以下記述をすることで、他の決済手段を含まず、銀行振込の手続きだけを消費者に行わせることができます。
また、役割の異なるパラメータが、意図せず適用されることを防げます。

この指定をしない場合は、利用可能なすべての決済手段が表示されます。
全てではなく、いくつか特定の決済手段を表示させたい場合は、それぞれの決済手段を指定してください。

独自のはたらきをするパラメータ

銀行振込利用時に独自のはたらきをするパラメータを、抜粋して紹介します。

振込期限の指定

トランザクショントークン作成時および課金作成時に以下記述をすることで、任意の銀行振込の期限を指定できます。

方法1　日時を指定

課金作成時に以下記述をしてください。

方法2　間隔を指定（銀行振込 / コンビニ決済に対応）

課金作成時に以下記述をしてください。

方法3　間隔を指定（銀行振込のみ対応）

課金作成時に以下記述をしてください。

本ガイドは、銀行振込における各API処理の補足説明です。

銀行振込に必要な消費者の情報には、カード番号のような保護が必要な情報は含まれていないため、決済を行うシステムがPCI DSSに準拠していない場合でもAPIへのリクエストでトークンを作成できます。

以下では、本サービスのウィジェットやリンクフォームを使用せず、加盟店さま側で支払ページを作成しAPIで処理する場合のフローを説明します。

1．トークン作成

消費者の情報をトークン化して保存します。
詳細は、APIリファレンス「トランザクショントークン – CREATE」を確認してください。

リクエストBody例

{
  "payment_type" : "bank_transfer",
  "type" : "one_time",
  "email" : "demo@univapay.com",
  "data" : {
    "brand" : "aozora_bank"
  },
  "metadata": {
    "memberid" : "12345"
  }
}

2．課金作成

作成したトークンに対して課金申込を行います。
詳細は、APIリファレンス「課金 – CREATE」を確認してください。

リクエストBody例

{
  "transaction_token_id": "11ed00f1-da1b-c4d2-b420-37b91ef1b282",
  "amount": "100",
  "currency": "jpy",
  "metadata": {
    "orderid": "12345"
  }
}

3．課金の取得

課金申込の結果を取得します。
詳細は、APIリファレンス「課金 – GET」を確認してください。

"status": "awaiting"が確認できたら正常に課金申込が完了し、消費者からの振込待ちの状態です。

ウェブフックで結果を受信することも可能です。
（ウェブフックのイベント名はcharge_updatedです。）

レスポンス / ウェブフック Body 例

{
  "id": "11ed07f5-345d-4308-a4c9-9f6b3663e18f",
  "store_id": "11ec9f7f-fb01-2620-af32-af7eb1bedc1a",
  "transaction_token_id": "11ed07f5-2da0-18ce-96f7-9f06340a7a87",
  "transaction_token_type": "one_time",
  "subscription_id": null,
  "merchant_transaction_id": null,
  "requested_amount": 100,
  "requested_currency": "JPY",
  "requested_amount_formatted": 100,
  "charged_amount": 100,
  "charged_currency": "JPY",
  "charged_amount_formatted": 100,
  "only_direct_currency": false,
  "capture_at": null,
  "descriptor": null,
  "descriptor_phone_number": null,
  "status": "awaiting",
  "error": null,
  "metadata": {
    "orderid": 123456
  },
  "mode": "live",
  "created_on": "2022-07-20T06:28:44.521327Z"
}

4．トークン取得（任意）

課金申込後に発行した口座の支店や口座番号の情報を取得できます。
詳細は、APIリファレンス「トランザクショントークン – GET」を確認してください。

口座情報は、レスポンスの”data”の値として反映されます。
口座情報が反映されるタイミングは、トランザクショントークンを作成した時ではなく、課金申込が成功して"status": "awaiting"になった時以降です。

レスポンス Body例

{
  "id": "11ed00f1-da1b-c4d2-b420-37b91ef1b282",
  "store_id": "11ec9f7f-fb01-2620-af32-af7eb1bedc1a",
  "email": "demo@univapay.com",
  "payment_type": "bank_transfer",
  "active": true,
  "mode": "live",
  "type": "recurring",
  "usage_limit": null,
  "confirmed": null,
  "metadata": {
    "customer_id": 12345
  },
  "created_on": "2022-07-11T08:17:06.47037Z",
  "updated_on": "2022-07-26T09:37:05.663521Z",
  "last_used_on": "2022-07-26T09:37:05.666269Z",
  "data": {
    "brand": "aozora_bank",
    "bank_code": "0310",
    "bank_name": "GMOあおぞらネット銀行",
    "branch_name": "アジサイ",
    "branch_code": "123",
    "account_holder_name": "カ)ユニヴア ペイキヤスト",
    "account_number": "1234567"
  }
}

5．課金の取得

APIリクエストで入金結果および振込期限切れの結果を取得します。
詳細は、APIリファレンス「課金 – GET」を確認してください。

ウェブフックで結果を受信することも可能です。
（ウェブフックのイベント名はcharge_finishedです。）

レスポンス Body例

{
  id: "11ed00f1-f0c4-1ca2-b754-db0d9311d5a0",
  store_id: "11ec9f7f-fb01-2620-af32-af7eb1bedc1a",
  transaction_token_id: "11ed00f1-da1b-c4d2-b420-37b91ef1b282",
  transaction_token_type: "one_time",
  subscription_id: null,
  merchant_transaction_id: null,
  requested_amount: 100,
  requested_currency: "JPY",
  requested_amount_formatted: 100,   //元々の申込金額
  charged_amount: 100,
  charged_currency: "JPY",
  charged_amount_formatted: 100,   //実際の入金額
  only_direct_currency: false,
  capture_at: null,
  descriptor: null,
  descriptor_phone_number: null,
  status: "successful",
  error: null,
  metadata: {
    "orderid": 123456
  },
  mode: "live",
  created_on: "2022-07-11T08:17:44.481834Z"
}

状況は、課金の状態"status"および入金額"charged_amount_formatted"から確認できます。

電算システムを利用した決済手段です。

決済フォームでの情報入力が完了すると、指定したコンビニエンスストアで入金を行うための情報が発行されます。
入金に必要な情報は、通知メールもしくはメタデータから確認可能です。
発行された情報をもとに消費者が入金を行うと、入金確認を自動で行い、結果を反映します。

また、管理画面の「ウェブフック」でURLを登録することによって、入金結果のシステム通知を受けることも可能です。

コンビニ決済でサポートしている内容は、以下を参照してください。

課金方式

都度課金およびリカーリング課金を利用できます。
定期課金には利用できません。

実装方法

当社決済フォーム（リンクフォーム，ウィジェット）の設置と、APIでの連携が可能です。

処理

以下の処理は対応していないため、有効にしても無視されます。

消費者の支払いフロー

コンビニ決済の申込後、通知メールの情報を確認してコンビニで入金すると、決済が完了する流れです。
当社決済フォームを利用した場合の消費者の支払いフローは、下記の画像付き資料を参照してください。

消費者の支払いフロー（PDFファイル）

課金ステータス

管理画面＞決済　から、申込や入金の履歴を確認できます。
「ステータス」は決済履歴一覧および詳細画面の「課金詳細」から確認できます。

課金ステータスの種類

テストモードの挙動

テストモードでは本番モードと挙動が異なります。

テストモードで決済を行った場合、申込完了の直後は「処理待ち」のステータスになります。
その約10分後に自動的に「成功」のステータスへ変化します。

電話番号の末尾4桁を指定することで決済結果別の挙動を確認することが可能です。

入金期限

管理画面、ウィジェット・リンクフォーム・APIのパラメータで振込期限を設定できます。
各パラメータの指定方法は、利用ガイド「コンビニ – 要注意なパラメータ」をご覧ください。

入金期限を超えた課金申込は失敗となり、決済失敗メールが送信されます。

管理画面での設定方法

一般設定＞決済サービス＞決済方法＞コンビニ　から、入金期限（期間および時刻）を設定できます。

• 振込のお支払期限：入金期限（期間）
• 振込期限（時間）：入金期限（時刻）

パラメータで指定しない限り、ここでの設定が適用されます。
デフォルトは30日、期限時間は23:59:59です。

設定可能な入金期限のパターンとそれに対する期限の例（1/1に申し込みを行った場合）は下記です。

使用上の注意点

下記の支払先は、時刻を指定できません。
時刻を指定している場合は無視され、自動で23:59:59になります。

• セブンイレブン
• セイコーマート/他支払（サークルK/サンクス/ペイジー）

通知メールテンプレート

管理画面＞通知メールテンプレート　から、通知メールの内容を編集できます。

新しくテンプレートを作成する場合は、「＋新規作成」ボタンから行ってください。
作成済のテンプレートを編集する場合は、一覧から任意のテンプレートを選択してください。

デフォルト内容は、利用ガイド「通知メールテンプレート」を参照してください。

テンプレートの種別

以下では、コンビニ決済の処理時に通知されるメールのテンプレートを抜粋して紹介します。

本ページは、コンビニ決済に対してパラメータを使用する場合に、注意すべき点の補足説明です。

事前に読むべきページ

このページでは、以下のページが読まれていることを前提として説明します。

ウィジェット

• ウィジェット – 概要
• 設置 – （HTML／JavaScript）

リンクフォーム

• リンクフォーム – 概要
• パラメータ（基本動作）

API

• 課金 – 概要
• 課金 – CREATE

表示させる決済手段の限定

課金作成時に以下記述をすることで、他の決済手段を含まず、コンビニ決済の手続きだけを消費者に行わせることができます。
また、役割の異なるパラメータが、意図せず適用されることを防げます。

この指定をしない場合は、利用可能なすべての決済手段が表示されます。
全てではなく、いくつか特定の決済手段を表示させたい場合は、それぞれの決済手段を指定してください。

独自のはたらきをするパラメータ

コンビニ決済利用時に独自のはたらきをするパラメータを、抜粋して紹介します。

入金期限の指定

トランザクショントークン作成時および課金作成時に以下記述をすることで、任意の銀行振込の期限を指定できます。
トランザクショントークン作成時と課金作成時の両方で入金期限を指定した場合は、課金作成時の入金期限が優先されます。

方法1　日時を指定

課金作成時に以下記述をしてください。

方法2　間隔を指定（銀行振込 / コンビニ決済に対応）

トランザクショントークン作成時に以下記述をしてください。

課金作成時に以下記述をしてください。

方法3　間隔を指定（コンビニ決済のみ対応）

課金作成時に以下記述をしてください。

本ガイドは、コンビニ決済における各API処理の補足説明です。

コンビニ決済に必要な消費者の情報には、カード番号のような保護が必要な情報は含まれていないため、決済を行うシステムがPCI DSSに準拠していない場合でもAPIへのリクエストでトークンを作成できます。

以下では、本サービスのウィジェットやリンクフォームを使用せず、加盟店さま側で支払ページを作成しAPIで処理する場合のフローを説明します。

1．トークン作成

消費者の情報をトークン化して保存します。
詳細は、APIリファレンス「トランザクショントークン – CREATE」を確認してください。

リクエストBody例

{
  "payment_type" : "konbini",
  "type" : "one_time",
  "email" : "demo@univapay.com",
  "data" : {
　　"customer_name" : "テスト　太郎",
　　"phone_number" : {
     "country_code" : "81",
     "local_number" : "0364413400"
   }, 
    "convenience_store" : "family_mart"
  },
  "metadata": {
    "memberid" : "12345"
  }
}

2．課金作成

作成したトークンに対して課金申込を行います。
詳細は、APIリファレンス「課金 – CREATE」を確認してください。

リクエストBody例

{
  "transaction_token_id": "11ed00f1-da1b-c4d2-b420-37b91ef1b282",
  "amount": "100",
  "currency": "jpy",
  "metadata": {
    "orderid": "12345"
  }
}

3．課金の取得

課金申込の結果を取得します。
詳細は、APIリファレンス「課金 – GET」を確認してください。

"status": "awaiting"が確認できたら正常に課金申込が完了し、消費者からの入金待ちの状態です。

ウェブフックで結果を受信することも可能です。
（ウェブフックのイベント名はcharge_updatedです。）

レスポンス / ウェブフック Body例

{
  "id": "11ed07f5-345d-4308-a4c9-9f6b3663e18f",
  "store_id": "11ec9f7f-fb01-2620-af32-af7eb1bedc1a",
  "transaction_token_id": "11ed07f5-2da0-18ce-96f7-9f06340a7a87",
  "transaction_token_type": "one_time",
  "subscription_id": null,
  "merchant_transaction_id": null,
  "requested_amount": 100,
  "requested_currency": "JPY",
  "requested_amount_formatted": 100,
  "charged_amount": 100,
  "charged_currency": "JPY",
  "charged_amount_formatted": 100,
  "fee_amount": null,
  "fee_currency": null,
  "fee_amount_formatted": null,
  "only_direct_currency": false,
  "capture_at": null,
  "descriptor": null,
  "descriptor_phone_number": null,
  "status": "awaiting",
  "error": null,
  "metadata": {
    "internal_convenience_payment_number": "20020-123456789012",
    "internal_convenience_payment_url": "https:/example.com"
  },
  "mode": "live",
  "created_on": "2022-07-20T06:28:44.521327Z"
}

支払先の情報は、レスポンスの"metadata"の値として反映されます。
支払先の情報が反映されるタイミングは、課金作成のリクエスト時ではなく、課金申込が成功して"status": "awaiting"になった時以降です。
"metadata"の値とその内容は以下の通りです。

Pay-easyの場合は支払いに別途「収納機関番号」が必要です。
値は固定されていて、共通で58091です。
課金取得時のレスポンスには反映されず、申込完了メールにのみ反映されます。

4．課金の取得

入金の結果を取得します。
詳細は、APIリファレンス「課金 – GET」を確認してください。

ウェブフックで結果を受信することも可能です。
（ウェブフックのイベント名はcharge_finishedです。）

レスポンス Body例

{
  id: "11ed00f1-f0c4-1ca2-b754-db0d9311d5a0",
  store_id: "11ec9f7f-fb01-2620-af32-af7eb1bedc1a",
  transaction_token_id: "11ed00f1-da1b-c4d2-b420-37b91ef1b282",
  transaction_token_type: "one_time",
  subscription_id: null,
  merchant_transaction_id: null,
  requested_amount: 100,
  requested_currency: "JPY",
  requested_amount_formatted: 100,   //申込金額
  charged_amount: 100,
  charged_currency: "JPY",
  charged_amount_formatted: 100,   //入金額
  only_direct_currency: false,
  capture_at: null,
  descriptor: null,
  descriptor_phone_number: null,
  status: "successful",
  error: null,
  metadata: {
    "orderid": 123456
  },
  mode: "live",
  created_on: "2022-07-11T08:17:44.481834Z"
}

状況は、課金の状態"status"および入金額"charged_amount_formatted"から確認できます。

決済処理を行う際に各QR事業者（プロバイダ事業者）の画面に遷移し、消費者側がログインして決済する または 各アプリを開いて決済する手段です。
下記がオンライン決済に該当します。

• PayPay Online
• Alipay Online
• Alipay Plus Online
• WeChat Pay Online
• ｄ払い Online

オンライン決済でサポートしている内容は、以下を参照してください。

課金方式

都度課金のみ利用できます。
定期課金やリカーリングトークンを用いた継続的な課金には利用できません。

実装方法

当社決済フォーム（リンクフォーム，ウィジェット）の設置と、APIでの連携が可能です。

処理

以下の処理は対応していないため、有効にしても無視されます。

消費者の支払いフロー

ここでは、当社決済フォームを開いてから決済が完了するまでの流れを説明します。
決済手段や消費者の使用するデバイスによっては、利用できない方法があります。

PCブラウザで開く場合

モバイル端末で開く場合

※PayPay Onlineは決済時に消費者の情報を取得しないため、決済情報から消費者を特定できません。
　そのため、決済フォームから消費者の情報を取得する（メールアドレスを必須項目にする等）または メタデータを付与するなど、消費者を特定できる実装を推奨します。

消費者の支払い画面は、下記の画像付き資料を参照してください。

消費者の支払いフロー（PDFファイル）

テストモードの挙動

テストモードでは本番モードと挙動が異なります。
テストモードの挙動は下記のとおりです。

テストモードでリクエストすることで、メール通知とウェブフック（システム通知）を確認できます。

事前に読むべきページ

このページでは、以下のページが読まれていることを前提として説明します。

ウィジェット

• ウィジェット – 概要
• 設置 – （HTML／JavaScript）

リンクフォーム

• リンクフォーム – 概要
• パラメータ（基本動作）

表示させる決済手段の限定

課金作成時に以下記述をすることで、他の決済手段を含まず、オンライン決済の手続きだけを消費者に行わせることができます。
また、役割の異なるパラメータが、意図せず適用されることを防げます。

この指定をしない場合は、利用可能なすべての決済手段が表示されます。
全てではなく、いくつか特定の決済手段を表示させたい場合は、それぞれの決済手段を指定してください。

本ガイドは、オンライン決済における各API処理の補足説明です。

オンライン決済に必要な消費者の情報には、カード番号のような保護が必要な情報は含まれていないため、決済を行うシステムがPCI DSSに準拠していない場合でもAPIへのリクエストでトークンを作成できます。

以下では、本サービスのウィジェットやリンクフォームを使用せず、加盟店さま側で支払ページを作成しAPIで処理する場合のフローを説明します。
APIの処理によって各QR事業者の支払い画面を呼び出すための流れは下記です。

1．トークン作成

消費者の情報をトークン化して保存します。
詳細はこちらのドキュメントを確認してください。

決済手段によって必要な情報が異なります。
また、 http_get や http_post など、各QR事業者が要求する実行方法によっても指定する値が異なります。

リクエストBody例

{
  "payment_type" : "online",
  "type" : "one_time",
  "email" : "demo@univapay.com",
  "data" : {
    "brand" : "alipay_plus_online",
    "call_method" : "http_get"
  },
  "metadata": {
    "memberid" : "12345"
  },
}

2．課金作成

作成したトークンに対して課金申込を行います。
詳細はこちらのドキュメントを確認してください。

リクエストBody例

{
"transaction_token_id": "9c3b37f8-1851-11e7-9b58-8b8ddbe8f1d1",
"amount": 1000,
"currency": "JPY",
"metadata": {
    "order_id": 12345,
    "shipping_details": "Customer wants it now"
  },
"redirect": {
    "endpoint": "https://test.url/path?additionalParams=paramValue"
  }
}

3．課金取得

課金申込の結果を取得します。
詳細はこちらのドキュメントを確認してください。

"status": "awaiting" が確認できたら正常に課金申込が完了し、消費者からの入金待ちの状態です。

ウェブフックで結果を受信することも可能です。
（ウェブフックのイベント名はcharge_updatedです。）

レスポンス / ウェブフック Body例

{
  "id": "0fe1e42a-1845-11e7-9b1f-d3bd0c055a99",
  "store_id": "af857264-180c-11e7-9be2-276aea4fed28",
  "transaction_token_id": "9c3b37f8-1851-11e7-9b58-8b8ddbe8f1d1",
  "transaction_token_type": "one_time",
  "subscription_id": null,
  "requested_amount": 1000,
  "requested_currency": "JPY",
  "requested_amount_formatted": 1000,
  "charged_amount": 1000,
  "charged_currency": "JPY",
  "charged_amount_formatted": 1000,
  "status": "awaiting",
  "error": null,
  "metadata": {
    "customer_id": 12345,
    "shipping_details": "Customer wants it now"
  },
  "mode": "test",
  "created_on": "2018-07-13T02:55:00.07367Z"
}

状況は、課金の状態 "status" および入金額 "charged_amount_formatted" から確認できます。

4．イシュアトークン取得

取得した課金IDを基に各QR事業者の支払い画面を呼び出します。
レスポンスで発行された各QR事業者の支払いURLを消費者側に表示すると、支払いに進めます。
詳細はこちらのドキュメントを確認してください。

レスポンス Body例

{ "issuer_token": "test", "call_method": "http_get" }

Paidy（後払い）とは、購入代金を自由な方法で翌月にまとめて支払うことができる決済手段です。
決済フォームでメールアドレスと電話番号を入力し、SMS認証を行うことで決済を行います。

Paidyでサポートしている内容は、以下を参照してください。

課金方式

都度課金および定期課金、リカーリング課金を利用できます。

実装方法

当社決済フォーム（リンクフォーム，ウィジェット）の設置のみ対応しています。
APIでの連携には対応していません。

処理

以下の処理は無効な項目のため、有効にしても無視されます。

• CVV認証（CVV auth）
• 分割払い

消費者の支払いフロー

当社決済フォームへ情報を入力後、Paidyの決済画面が開いたら案内に沿って進むと、再度当社画面に戻って決済が完了する流れです。
ウィジェットの場合は「支払う」ボタンを押し、リンクフォームの場合は待機すると支払い完了画面が表示されます。

消費者の支払い画面は、下記の画像付き資料を参照してください。

消費者の支払いフロー（PDFファイル）

結果の通知・確認

結果を加盟店さまの配送（または、それに準ずる会員ステータス等の）システムに自動で反映する必要がある場合は、ウェブフックで結果を受信して注文システムを更新するプログラムを設置してください。また、結果はAPIへリクエストすることでも取得できます。

システム連動を行わず、管理画面またはメールで結果を確認する場合は作成する必要はありません。

テストモードの挙動

Paidyはテストモードの決済に対応していません。
本番モードの挙動は本ページ「消費者の支払いフロー」で確認してください。

本ページは、Paidyに対してパラメータを使用する場合に、注意すべき点の補足説明です。

事前に読むべきページ

このページでは、以下のページが読まれていることを前提として説明します。

ウィジェット

• ウィジェット – 概要
• 設置 – （HTML／JavaScript）

リンクフォーム

• リンクフォーム – 概要
• パラメータ（基本動作）

表示させる決済手段の限定

課金作成時に以下記述をすることで、他の決済手段を含まず、Paidyの手続きだけを消費者に行わせることができます。
また、役割の異なるパラメータが、意図せず適用されることを防げます。

この指定をしない場合は、利用可能なすべての決済手段が表示されます。
全てではなく、いくつか特定の決済手段を表示させたい場合は、それぞれの決済手段を指定してください。

定期課金では、事前に指定したサイクルで自動的に課金を行います。
2回目以降の課金は、課金日の午前7時※より順次課金を開始します。
※毎日の定期課金 および 定期課金開始日が定期課金作成日の1日後な場合に限り午前9時

定期課金を作成する方法については実装ガイドの各ページを参照してください。

ステータス

定期課金で行うことができる処理

定期課金の支払い失敗後、再度課金を行うことができます。
課金に失敗した日から指定した間隔日後に課金の再実行され、その後成功するまで設定された回数リトライを行います。

リトライの指定方法

リトライ間隔

リトライを行う間隔は定期課金毎に任意で指定できます。
また、作成済定期課金のリトライ間隔は管理画面から変更が可能です。

リトライ回数

リトライを行う回数は 管理画面＞一般設定＞決済サービス＞全体設定 から設定できます。
初回を含め、設定回数以上のリトライが失敗した場合、定期課金が停止します。
一時停止中の定期課金を再開すると、もう一度設定された回数リトライを実行します。

リトライ終了後のステータス

リトライ終了後のステータスは 管理画面＞一般設定＞決済サービス＞全体設定 から設定できます。
デフォルトは「一時停止」で、任意で「永久停止」を選択できます。

リトライ後の課金スケジュール

リトライの結果やタイミングによって、その後の課金スケジュールが異なります。

例）
課金間隔：毎月
リトライ回数：5回
リトライ間隔：10日

リトライ日

リトライ日は、「課金失敗日からリトライ間隔後の日付」と「指定した次回課金日」を参照して決定されます。

• 「指定した次回課金日」の方が未来：指定した次回課金日にリトライを実行
• 「課金失敗日からリトライ間隔後の日付」の方が未来：リトライ間隔後にリトライを実行

課金が失敗してリトライ待ちになった定期課金の次回課金日を変更しても、「課金失敗日からリトライ間隔後の日付」の方が未来の場合は次回課金日にリトライされないためご注意ください。
この場合、管理画面からリトライ間隔の変更を行うことによってリトライ間隔後より前に課金を実行させることが可能です。

継続中の定期課金を任意で一時停止して再開した場合は、リトライ待ちであってもリトライ日が表示されず、次回課金日に課金を実行します。

停止

定期課金に停止処理をすると、その時点から継続的な課金を行わないようになります。
停止する方法は下記です。

停止予約について

定期課金作成時、もしくは作成後管理画面（またはAPI）で操作することで、
停止リクエストがあった時に次回課金実行日に定期課金を停止させるかどうかを設定することができます。
※ここでの「停止リクエスト」は一時停止、永久停止の両方を指します

管理画面から変更する場合

「定期課金を停止する場合」

定期課金の停止リクエストを受けた場合に停止するタイミングを設定できます。

「次回課金実行日の処理（リトライ日含む）」

リトライ含む次回の課金実行日の処理を設定できます。
前の項目で「次回課金日に定期課金を停止」を指定した場合に選択できるようになります。

再開

一時停止している定期課金に限り、再開処理をすることができます。
再開方法については下記の表を確認してください。

再開後の挙動

再開する時、設定されていた次回課金日の状態によって挙動が異なります。

次回課金日が過去の場合の例：
毎月１日の毎月サイクルの定期課金
8/1：課金
8/15：一時停止（次回課金日は9/1の状態）
10/2：再開（直後には課金されない）
→次回課金日が自動で11/1にセットされる

再開時に次回課金日を指定する

前回課金の処理結果によって処理が分かれます。

• 前回課金が成功：指定した次回課金日で課金実行
• 前回課金が失敗：前ページの仕様に従い、課金実行日を決定

回数指定の定期課金を再開する

再開時に過去の未払いの決済がある場合、元の課金スケジュールを後ろ倒しで支払い予定を追加します。

例：
毎月1日の毎月サイクル、5回の回数指定で、
8/15に停止し、10/2に再開した際の課金スケジュールは下記です。
未払いの9/1・10/1の分は後ろ倒し、1/1・2/1と支払い予定が追加されます（本来は12/1が最後の支払予定日）

消費者が自ら支払い方法を更新する方法はいくつか存在します。
新たに情報を登録して加盟店さまで既存の支払い情報と紐づけていただくか、既存の支払い情報を引き継いで更新する2つの場合に分かれます。

定期課金

リカーリングトークン

以下のページでは「支払い情報の確認・変更画面」についての利用方法を説明します。

支払い情報の確認・変更画面では、消費者が定期課金のカード情報変更や停止、リカーリングトークンの追加や変更が可能です。
決済時やカード登録時に入力したメールアドレスをキーにして、定期課金やリカーリングトークンが表示されます。

確認・変更できる内容

定期課金情報

• 課金停止処理
  定期課金を停止できます。回数制限付きの定期課金は停止できません。
• カード管理 　
  定期課金のカード情報を変更できます。設定で許可された方法から選択できます。
  • 現在のカードで名義・有効期限の変更
  • 新規カードを登録
  • その他のカードを使う（作成済のリカーリングトークンから選択）
    ※この方法の場合はメタデータなど変更前のトークン情報が引き継がれません。

お支払い方法

• 新規カードの登録
  リカーリングトークンを作成できます。メタデータ等の情報は付与されません。
• 名義・期限の変更
  作成済リカーリングトークンのカード名義/有効期限を変更できます。
  変更処理を行うと、名義/有効期限が変更されたリカーリングトークンが新しく作成されます。
  • 更新後のリカーリングトークン
    更新前のリカーリングトークンの情報を引き継ぎます。（カード番号、メタデータ、メールアドレス等）
  • 更新前のリカーリングトークン
    ステータス：停止になり、管理画面から閲覧できます。過去に行われた課金の情報も引き続き閲覧できます。

関連ページ

詳細は下記のページで説明しています。

• 1.消費者の利用フロー
• 2.加盟店さまの設定
• 3.消費者へのURLの共有方法

1．メール通知など、加盟店さまから案内された支払い情報の確認・変更画面URLをクリックする
　※消費者へのURLの共有方法は、「消費者へのURLの共有方法」のページを参照してください。

2．メールアドレスを入力する（URLにメールアドレスを未指定の場合のみ）

3．指定のメールアドレス宛に届いた認証コードを入力し、ログインする
　 （認証コードの有効期限：5分）

4．各変更/停止処理を行う

5．処理ごとに通知メールが届く（通知設定がONの場合のみ）

※消費者の各処理が完了すると、処理ごとに加盟店さまに通知メールやウェブフックが送信されます。（通知メール設定およびウェブフックのトリガーがONの場合のみ）

変更・停止の許可設定

支払い情報の確認・変更画面から実行可能な処理は、管理画面の 一般設定＞一般＞全体設定＞支払い情報の確認・変更画面から設定できます。

消費者側の制限

支払い情報の確認・変更画面のモード

支払い情報の確認・変更画面のモードを本番/テストから選択できます。
すべての支払い情報の確認・変更画面に対して指定したモードが反映されます。

管理画面「通知メールテンプレート」

メールテンプレート内に${customer_refer_link}のパラメータがある場合、支払い情報の確認・変更画面のURLが表示されます。

デフォルトのメールテンプレートを利用する

一般設定＞一般＞通知の「定期課金イベント発生時に通知」をONにしてください。
上記設定によって、定期課金関連の通知メールにURLが表示されます。

※メールテンプレートのデフォルト内容はこちらを参照してください

独自のメールテンプレートを作成する

「定期課金イベント発生時に通知」の設定次第で、通知メールテンプレートの利用方法が異なります。
※都度課金と定期課金を併用している場合、「定期課金イベント発生時に通知」をONし、メールの文面を分けることを推奨します

前提として、定期課金関連のメールには二種類のテンプレートが存在します。
サブテンプレートの文面は、メインテンプレートの${subscription_payment_details:- }として反映されます。

用途に合わせてテンプレートにパラメータを追加してください。

${customer_refer_link}を追加可能なメールテンプレート

• 　定期課金作成
• 　定期課金決済
• 　定期課金決済失敗
• 　定期課金の一時停止
• 　定期課金のカード情報変更の案内　※開発中のため現在は利用不可
• 　定期課金の詳細
• 　回数制限付き定期課金の詳細
• 　決済完了通知
• 　決済失敗

手動でURLを作成・送信

下記URLに店舗IDを入力して消費者に共有することで、支払い情報の確認・変更画面へアクセスできます。
加盟店さま側でメールアドレスを指定したい場合は、メールアドレスも入力してください。

管理画面「定期課金」（開発中）

対象の定期課金を選択し「定期課金の管理画面」のメール送信ボタンを押すと、消費者のメールアドレス宛に「定期課金のカード情報変更の案内」の通知メールが送信されます。

決済、定期課金、リカーリングトークンの情報をCSVデータで管理画面からダウンロードすることができます。

作成したデータのダウンロード有効期限は1時間です。
仕様上、50万件以上のダウンロードを行おうとするとエラーが発生しますので、それより少ない件数で実行してください。

各検索条件を指定することで、出力させたい情報を絞り込むことが可能です。
検索条件は加盟店さまがいる国が基準となって変動しますが、CSVに出力される決済データの時間帯は固定で日本標準時(JST)に設定されています。
　例：加盟店さまが台湾にいる場合
　　　検索場所…台湾　GMT+8: 2023/7/1 00:00:00 ～2023/8/1 00:00:00
　　　出力結果…日本　GMT+9:  2023/7/1 01:00:00 ～2023/8/1 01:00:00

ダウンロード方法によって取得できる項目は一部異なります。
決済、定期課金、リカーリングトークンに加え、決済の中でも管理画面の「すべてのプロバイダ」から決済方法毎に絞り込むことで一部項目が変化します。
方法毎の取得項目の一覧についてはこちらのファイルから確認して下さい。

取得できる項目一覧

イベント種別について

CSVファイルをアップロードすることで、既存の顧客に再び課金することができる機能です。
顧客の支払い情報が予めリカーリングトークンとして登録されている必要があります。

CSVファイルで提供された情報を元に、指定された顧客データの中で最も新しく作成されたリカーリングトークンを識別します。
その後、リカーリングトークンに保存された支払い情報を再利用して、新たな課金を行います。

対応している決済方法は、クレジットカード / Paidyのみです。
銀行振込 / コンビニ決済は対応していません。

※ご利用にはオプション契約が必要です。

トークンのステータスの確認について

CSV課金の仕様上、顧客データがあるもののうち、最も新しく作成されたリカーリングトークンが自動で選択されて課金を実行するため、決済可能なリカーリングトークンかどうかの確認は加盟店さま側で行ってください。

• トークン作成のみ行う場合：CVV認証（実行している場合）と3-Dセキュア認証が成功しているかの確認
• トークン作成と課金を行う場合：課金が成功しているかの確認

ファイルのフォーマット

CSVファイルのコンテンツ

※アップロード、結果ダウンロード時の文字コードはUTF-8です。

CSVファイル作成には、4つの項目が必要です：

CSV課金アップロード時にメタデータを付与する

メタデータを付与するためには、「通貨」の右の列にフィールドを指定する必要があります。

基本のパターンは「:」で区切ったキーと値です。
key-one:value one
複数追加したい場合は「|」で区切ります。
key-one:value one|key-two:value two
値に「,」を利用する場合は下記のように指定してください。
key-one:"value one,123"

各ジョブIDについて

①顧客ID（ジョブID = 1）

顧客IDはメタデータ（univapay-customer-id）であり、リカーリングトークン登録処理時に任意で付与することができます。
システムでは、この顧客IDでタグ付けされたリカーリングトークンを検索し、新しい課金を行います。

例：
1,c5d1b760-c7db-4696-a943-8ce90c988486（顧客ID）,1000,JPY

②顧客のメールアドレス（ジョブID = 2）

このオプションを使用するには、1列目にジョブIDとして2を、2列目に顧客のメールアドレスを入力してください。
システムでは、このメールアドレスがタグ付けされた最新のリカーリングトークンを検索し、新しい課金を行います。

例：
　2,test@univapay.com（メールアドレス）,1000,JPY

③リファレンスID（ジョブID = 3）

リファレンスIDはメタデータ（univapay-reference-id）であり、リカーリングトークン登録処理時に任意で付与することができます。
システムでは、このリファレンスIDがタグ付けされた最新のリカーリングトークンを検索し、新しい課金を行います。

例：
　3,AB0001（リファレンスID）,1000,JPY

④リカーリングトークンID（ジョブID = 4）

リカーリングトークン作成時に当システムで自動的に発番されるIDを用います。
システムでは、このIDを持つリカーリングトークンを検索し、新しい課金を行います。

例：
 4,11ecc509-cc27-28fe-9283-033858e9ed30（リカーリングトークンID）,1000,JPY

サンプルファイル

csvcharges-sample.csv

※異なるジョブの指定を同じCSVファイルにまとめることも可能です

1,c5d1b760-c7db-4696-a943-8ce90c988486,3000,JPY
2,test001@test.com,2500,JPY
3,AB00001,1000,JPY
4,11ecc509-cc27-28fe-9283-033858e9ed30,500,JPY

決済結果のダウンロード

CSV課金完了後、管理画面から結果ファイルをダウンロード可能です。
ファイルの内容（ヘッダー）は下記となります。

検索コマンド,検索パラメータ,リクエスト金額,リクエスト通貨,メタデータ,課金ステータス,課金金額,課金通貨,課金ID,エラーメッセージ

3,AB00001,1000,JPY,metadata,SUCCESSFUL,1000,JPY,11ed1a13-525e-1bea-b97b-a

商品機能は加盟店さまが販売している商品の、名称や金額・課金方式について登録することができます。
登録した商品は各決済フォームで選択・指定することでテンプレートのように使用することができます。

※ご利用にはオプション契約が必要になります。

利用方法

まず管理画面で商品を作成します。
作成方法、各項目についてはこちらを確認して下さい。

次に各決済フォームで登録した商品の情報を指定します。

パラメータで利用する場合の注意点

• 複数の商品を同時に指定する場合は「,」（カンマ）で区切って下さい。
• 商品のパラメータを指定する場合は、app-id,checkoutを指定する必要があります。
• 商品に含まれる情報をパラメータで別途指定すると商品の情報より優先されます。
  ex) amount や定期課金の場合 period 等
• 商品に含まれない情報であればその他パラメータで併用可能です。
  ex) 初回0円の定期課金を作成する際はcvv-authorizeの指定が必要です。
• 仮売上を行いたい場合はcaptureを併用して指定してください。

テンプレートでは、決済メールテンプレートの作成・編集ができます。

テンプレートを作成しない場合は、決済システム側のデフォルトの決済完了メールが送信されます。
別ページに例を記載していますが、その他メールの内容についてはテストモードで決済をすることで確認できます。