APIとは、様々な決済手段を提供する RESTfulな HTTPS インターフェースです。

API を呼び出す為に、直接 HTTP リクエストを実行することも可能ですが、いくつかの開発言語向けにライブラリを提供しています。これらは様々なベストプラクティスや、型情報を提供するので、APIの統合をより簡単に行うことができます。これらの使用例は、本ドキュメントのリソースに対する呼び出し例として記載されています。

API連携

画面遷移をシンプルにする等の理由で、加盟店サイト内に独自の決済フォームを設けたい場合は、API連携を行ってください。

クレジットカード情報の送信を伴う場合

クレジットカード情報を加盟店サイト内に入力させ、APIに送信する場合は、カード情報の「通過」にあたるため、加盟店サイトがPCI DSSに準拠することが必要です。
PCI DSSに準拠していない場合、カード情報は当社準備の決済フォームを利用する構築をしてください。
PCI DSSに準拠している場合、トークン化から課金、返金までの全てのリクエストを本サービスのAPIに送信することが可能です。

APIの呼び出しについて

APIはシークレットトークンなどの機密情報を含むためCORSでの実行を許可していません。
APIを呼び出す場合はサーバーアプリケーションから呼び出すよう実装してください。

SDK

ここでは、API連携開発をシンプルにする「SDK」について説明します。

APIとの連携開発を行う際は、本ドキュメントを参照して設計・開発してください。
開発言語が対応しているようであれば、SDK（Software Development Kit）の利用を推奨します。

SDKは、APIを利用するためのライブラリです。GitHub上で公開しています。
利用フローについては、Githubの「Readme」を参照してください。

SDK利用のメリット

• APIと通信するためのコードを記述する必要がない
• セキュリティ（トークンの有効期限や利用回数制限のアルゴリズム）の取り扱いについても考慮する必要がない

SDKの機能やツール例

IDE、オートコンプリート、コンパイルエラー etc…

GitHubについて

GitHubは、ソフトウェア開発プロジェクトのためのソースコード管理サービスです。
GitHubの公式言語は英語で、アカウント設定画面から言語を日本語に指定することはできません。以降、最低限必要なアクションを日本語で解説します。

技術的な不明点や、Github内ドキュメントへのフィードバックがある場合

SDKの組込において技術的な質問がある場合や、ドキュメントへのフィードバックがある場合は、該当のリポジトリ※から「Issues」を選択し、当社エンジニアに質問・要望を日本語または英語で送信してください。

リポジトリとは：
「格納庫」を意味する言葉で、Githubでは組織またはプロジェクトの階層下に設置されるサブプロジェクトのような存在です。例：https://github.com/univapay/univapay-java-sdk
この場合は「univapay-java-sdk」がリポジトリです。

サポートしている開発言語

• Javascript Typescript NodeJS
• JAVA
• PHP

本サービスのAPIは、認証の為に JWT(JSON Web Token) を利用しています。

ヘッダで認証を行い、ペイロード部分にリクエストを記述するのが基本的な使い方です。

アプリケーショントークンの構成

はじめに、ガイドの初期設定に従い、アプリケーショントークン（以降「アプリトークン」）を作成してください。

アプリケーショントークンは、「トークン」と「シークレット」の2部で構成されます。

シークレットは、アプリトークンを作成した時だけ表示されます。
表示されたシークレットは、くれぐれも忘れずに控えるようにしてください。

また、このシークレットは機密情報として取り扱う必要があります。
消費者のブラウザ上で実行されるようなフロントエンドアプリケーションのコードの中にシークレットを記述したり、インターネットで第三者が閲覧できる状態にしないでください。
レポートの生成、ブラウザ以外の経路での課金の作成など、サービスのバックエンドでの処理で利用されることを想定している、たいへん大きな権限を行使できる情報です。

当社では、加盟店さまのシークレットの管理上の問題に起因する事故について、一切の責任を負いかねます。

アプリトークンの使い方

以降、全てのページで、HTTPリクエストヘッダのAuthorizationに記述する

• アプリトークンを「{jwt}」
• シークレットを「{secret} 」

と、それぞれ記述します。

Bearer認証の記述例

// シークレットなし
Bearer {jwt}

// シークレットあり
Bearer {secret}.{jwt}

アプリトークンの種類

管理画面からは、2種類のアプリトークンを作成可能です。
それぞれの意味合いと役割を表にしたものが以下です。

ウィジェットやインラインフォーム出力リクエストは、登録したドメインからであることを認証しています。
管理画面で「店舗」のアプリトークンを作成する際には、ドメインを登録してください。

本サービスのAPIには、レート制限と、リソース制限の2種類の制限があります。

また、このレート制限とは別に、クレジットカード決済において同一の

• リカーリングトークン
• 金額

の組み合わせで、30秒以内に課金処理すると重複エラー（エラーコード：311）にを起こす仕様があります。
これは、重複課金を防止する事を目的としています。

レート制限

本サービスのAPIは、アクセス先のリソースとパスに応じて「レート制限」を設定しています。

APIへのリクエスト元は、リクエストを行う度に「バーストレート」と呼ばれるものをレスポンスで受け取ります。
バーストレートは一度に送信できるリクエストの残高のような役割を果たします。
バーストレートは一定時間で補充されますが、使い果たした状態でリクエストを行うと、Too Many Requestsのエラーが発生します。
このバーストレートは、リクエストに対するレスポンスのヘッダで取得できます。

ヘッダの出力例

以下は、イグザクトバーストレートの上限が10、ルートバーストレートの上限が30に設定されたAPIへ、1件だけGETのリクエストを送った直後のレスポンス例です。

X-Remaining-Requests-Exact: 9
X-Remaining-Requests-Route: 29
X-Requests-Per-Minute-Exact: 120
X-Requests-Per-Minute-Route: 1200

意味合いとしては、以下の通りです。

• 1回あたりのイグザクトバーストレート：残り9
• 1回あたりのルートバーストレート：残り29
• 1分あたりのリクエスト上限（イグザクト）：120
• 1分あたりのリクエスト上限（ルート）：1,200

イグザクトバーストレートの上限が10であるため、1件のリクエストは許容され、イグザクトバーストレートが「9」、パスバーストレートが「29」に、それぞれ減算されレスポンスされています。

イグザクトバーストレートは、0.001（1ミリ）秒ごとに0.02（この場合は1分あたり上限÷1分間のミリ秒換算＝1,200/60,000）だけ回復します。
つまり、仮に次回10件のリクエストをするなら、イグザクトバーストレートが10まで回復するのを待つ必要があり、最短で0.05秒（1/0.02=50ミリ秒）の待機が必要になるということです。

なお、元のイグザクトバーストレートの上限が10であるため、0.05秒以上の待機をしても、上限の10以上まで増えることはありません。

レート制限の種類

各種レート制限には規定値が設定されており、規定値のあるものが、リクエストへのレスポンスのヘッダに出力されます。

課金レート制限

課金の作成に関するリクエストを行う際にカウントされます。

これらのリクエストに対して

• バーストレート
• 1分あたりのリクエスト上限

が、レスポンスされます。

後述する標準レート制限が同時に適用されることはなく、レスポンス内容も異なります。

標準レート制限

標準レート制限は、以下2つに分類されます。
なお、全てのリクエストに対して

• イグザクトバーストレート
• ルートバーストレート
• 1分あたりのリクエスト上限（イグザクト）
• 1分あたりのリクエスト上限（ルート）

が、レスポンスされます。

また、全てのリクエストでルートバーストレートとイグザクトバーストレートの両方がカウントされます。
この制限が課金レート制限と同時に適用されることはなく、レスポンス内容も異なります。

ルートバーストレート

アクセスするリソースの「パス」に対しての制限です。例えば

GET /charges/{charge_id_1} 
GET /charges/{charge_id_2} 

という2回のリクエストは、「/charges」という同一のパスに対するものであるため、1つのパスに対し２回リクエストしたとカウントされます。
本サービスは全てのパスに対し、同一のルートバーストレートを設定しています。

イグザクトバーストレート

イグザクトバーストレートは、Exact（完全一致）の名の通り、リソースIDやクエリ文字列も含めて完全に一致するパスに対して適用されます。例えば

GET /charges/{charge_id_1}

というリクエストがされた場合は、この/charges/{charge_id_1}に対して、カウントされます。
本サービスは全てのリクエストに対し、同一のイグザクトバーストレートを設定しています。

リソースの制限

1つの加盟店または店舗で、有効にできるリソース数には上限があります。
この上限を超えるリソースの作成リクエストには、ResourceLimitReachedエラーが出力されます。

当社APIからのレスポンスは JSON 形式で返されます。

レスポンスと共に返されるHTTPステータスコードによって、リクエストの結果を判別できます。
APIの呼び出しが失敗すると、HTTP ステータスコードが 4xx もしくは 5xx 系統で返されます。

詳細はエラーコードを参照ください。

リストとして返されるすべてのリソースはページネートされリソースの作成日の降順でソートされます。
ページあたりのアイテムの件数はデフォルトで10件です。

ページネートされたリストの形式

• items（array）：リソースのリスト
• has_more（boolean）：表示されているリストの最後のリソースの次に更にリソースがあるかどうか

{
  "items": [],
  "has_more": false
}

次ページのリソースの取得

以下のパラメータを指定することでリストの次のページを取得することが可能です。

• limit（number）：10–100の範囲の整数で返却するリソースの数
• cursor（string）：リソースの取得開始位置を指定する為のリソースのID
  　　　　　　　　　このリソースの次のリソースから取得され、このIDで指定したリソースはレスポンスには含まない
• cursor_direction：リソースのソート順で、asc (昇順) もしくは desc (降順)

例えば、以下のリクエストで最初の100個の課金（Charge）リソースを取得することができます。

curl -h 'Authorization: Bearer {secret}.{jwt}' https://api.univapay.com/charges?limit=100

{
  "items": [
    {
      "id": "4050058b-646a-4fae-8876-babf0dc0c3f0"
      ...
    },
    ...
    {
      "id": "34daac6d-63a8-485b-a9ea-75a2e24a258d"
      ...
    }
  ],
  "has_more": true
}

"has_more":true となっているのでさらにリソースがある事がわかります。
次の100件の課金を取得するには、リストの最後のリソースID34daac6d-63a8-485b-a9ea-75a2e24a258dをリクエストパラメータのcursorとして指定します。

curl -h 'Authorization: Bearer {secret}.{jwt}' https://api.univapay.com/charges?cursor=34daac6d-63a8-485b-a9ea-75a2e24a258d&limit=100

以下の新規リソース作成時にメタデータ付与 / 既存リソースのメタデータ更新が可能です。

• トランザクショントークン
• 課金（Charge）
• 返金（Refund）
• 定期課金（Subscription）

付与できるメタデータの個数に制限はありませんが、リクエストボディ全体は最大256KBです。

メタデータはフラットなJSONとして保存されます。
本サービスと加盟店のシステム上のレコード（消費者や消費者による注文データ等）とを関連付けるために使用することを推奨します。

有効なメタデータの例

{
  // Other request parameters
  "metadata": {
    "customer_id": 12345,
    "shipping_details": "Customer wants it now"
  }
}

概要

ポーリングとは、対象のトランザクションに対してステータスの変化を検出するまで GET リクエストを行い、トランザクションのステータスが変化したタイミングで通知を受け取れる実装方法です。

当社APIのトランザクションは、作成直後に処理中（pending）のステータスになりますが、処理結果がクレジットカード会社などの決済事業者によって反映されていない状態のため、参考になる情報ではありません。
そのため、決済を行った後、消費者に対して決済の状態をなるべく早く反映させたい場合は、ポーリングの利用を推奨します。

ポーリングではなく、ウェブフックを利用してステータスを取得する場合は、こちらのページを参照してください。

ポーリング可能なリソース

以下4つのリソースに対して、1回のAPIリクエストでトランザクションのステータスを効率的にポーリングする手段を提供しています。

• 課金（Charge）
• 返金（Refund）
• キャンセル（Cancel）
• 定期課金（Subscription）

これらのリソースに GET リクエストを送信する時、リクエストURLに対してクエリパラメータで polling ： true と指定すると、対象のリソースが最終的な状態に遷移するまでAPIの内部でポーリングします。

例）課金の GET リクエスト
https://api.univapay.com/stores/{storeId}/charges/{chargeId}?polling=true

リソースごとの、最終的な状態を表すステータスは下記の通りです。

最初の状態が、課金：処理中（pending） / 定期課金：待機中（Unverified）の場合、何かしらステータスが変化したタイミングで「最終的な状態」とみなし、ポーリングは終了します。

注意点

ポーリング利用時は、以下の点に注意してください。

• ポーリング実行から3秒以内にステータスが変化した場合、更新されたレスポンスを返します。
  ステータス変更がない場合は、状態が何であっても3秒後時点の状態を返します。
• GETリクエストのレスポンスが502,503,504のエラーだった場合は、一時的な通信環境の悪化が原因の可能性があるため、数秒後に再度リクエストを行うと、結果が成功（Successful）になる場合があります。
  そのため、これらのエラーが返却された場合、すぐに決済失敗と判断しないよう注意してください。
• 当社提供のパラメータを利用せず、加盟店さま側で独自にポーリング処理を実装する場合、APIの制限を受けないよう適切なエラー処理を行ったポーリングの仕組みを実装する必要があります。
  そのため、当社の提供する手段を利用した実装を推奨します。

当社APIでは冪等なリクエストを行うことができます。
冪等性は強力な安全性を提供するため、予期しない理由などで1つのリクエストが複数回実行されないようにし、重複決済を防ぐことができます。

利用可能なメソッド

冪等性リクエストは POST、PATCH リクエストでのみ利用可能です。
特にトランザクショントークン、課金、定期課金、返金などの作成や更新時は、常に冪等性リクエストを使用することを推奨します。

利用方法

上記、利用可能メソッドのリクエストヘッダに Idempotency-Key キーを指定することで利用可能です。
※任意の文字列を指定できますが、UUIDのようにランダムに生成された文字列を使用することを推奨します

※冪等性の保証は現在ベストエフォートで提供されており、冪等性のチェックができない状態が発生する可能性があります。
この場合リクエストが処理された後、レスポンスの Idempotency-Status ヘッダに error が入ります。

冪等性リクエストの仕組み

リクエストに冪等性キーが指定された場合、当社APIはまず、以前に同じキーのリクエストが処理されたかを確認します。

• 既に処理されていた場合：そのリクエストを再度処理せずに、API内部のキャッシュに保存されている過去のレスポンスを返却します。
• まだ処理されていなかった場合：通常どおりリクエストを処理し、将来冪等性リクエストが来る時に備え、レスポンスの内容を冪等性キーをキーとしてAPI内部のキャッシュに保存します。

※冪等性キーの有効期間は24時間です。同じ冪等性キーの2回目リクエストがこの期限を過ぎてしまった場合、APIはこれを1回目のリクエストとみなして実行してしまいます。

レスポンス

冪等性リクエストのレスポンスには、Idempotency-Status ヘッダが含まれます。(以下表参照)

冪等性リクエストによる課金制限の変更

同一リカーリングトークンまたは同一カードに対して同一金額 ※ で連続して課金を行う場合、30秒以下の間隔で実行しようとすると、課金制限によってエラー「400 CHARGE_TOO_QUICK」が発生します。
※定期課金に関して、以下の場合のみ、違う金額でも課金制限が適用されます。

• 同一カードに対して、連続して定期課金を行う場合
• 同一リカーリングトークンに対して、連続して行う課金の種類が異なる場合（都度課金後、定期課金 / 定期課金後、都度課金）

課金制限は、冪等性キーの実装 かつ サポートデスクへの依頼によって、最短1秒に変更可能です。
同一消費者に対して連続で課金できる間隔を短縮したい場合は、サポートデスク（ips-support@univapay.com）へお問い合わせください。

本サービスは主要な通貨で直接決済を行うことができますが、直接決済できない通貨の場合には決済処理時に自動で変換することができます。
ドルの場合セントという２桁の補助単位がありますが、通貨単位のドルと補助単位のセントを合わせて一つの整数にしてリクエストしてください。例えば、10.00ドルは、1000と送ります。
直接決済可能な通貨は以下の通りです。

• JPY 日本円
• USD 米ドル

※接続しているアクワイアラ（カード会社）やセンター（カード会社と紐づくオンライン処理用のセンター）で許可されている通貨であることが必須です。
加盟店さまで直接決済が利用可能な通貨についてはサポートデスクにお問い合わせください。

直接決済に対応していない通貨を使用する場合、振込先の銀行口座に設定してある通貨に自動的に変換されます。
設定された通貨が使用できない場合は、デフォルト設定である日本円に変換されます。
請求情報には変換後の通貨が使用されますので、別の通貨に変換される場合は、カード利用者に通知するようにして下さい。

本ドキュメントについて

目的

本ドキュメントは、「国際ブランドが付帯したカードの決済」「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制限のページを確認してください。

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

あ行

か行

さ行

た行

な行

は行

ま行

や行

ら行

英数字・記号

本サービスを利用開始するためのガイドです。
利用開始前に、必ずご通読ください。

本ドキュメントについて

目的

本ドキュメントは、「国際ブランドが付帯したカードの決済」「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制限のページを確認してください。

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

あ行

か行

さ行

た行

な行

は行

ま行

や行

ら行

英数字・記号

本サービスと加盟店さまの商用サイトとを連携するための実装ガイドです。
「はじめに」を通読の上、ご覧ください。

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

ウィジェットの役割

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

支払い方法の選択

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

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

必須情報の入力

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

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

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

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

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

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

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

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

詳しくはこちら

ウィジェットのデザイン

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

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

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

消費者の支払いフロー

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

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

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

リンクフォームは、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ファイル）

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

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

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

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

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

必須情報の入力

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

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

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

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

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

詳しくはこちら

本サービスと加盟店さまの商用サイトとを連携するための実装ガイドです。
「はじめに」を通読の上、ご覧ください。

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

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

課金方式

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

実装方法

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

処理

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

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

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

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

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

課金方式

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

実装方法

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

処理

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

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

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

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

課金方式

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

実装方法

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

処理

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

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

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

課金方式

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

実装方法

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

処理

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

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

本サービスを実装する上で、必要に応じて理解する必要がある各機能の仕様について記載しています。

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

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

ステータス

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

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

定期課金

リカーリングトークン

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

決済、定期課金、リカーリングトークンの情報を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ファイルのコンテンツ

※アップロード、結果ダウンロード時の文字コードは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はメタデータであり、リカーリングトークン登録処理時に任意で付与することができます。
システムでは、この顧客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はメタデータであり、リカーリングトークン登録処理時に任意で付与することができます。
システムでは、このリファレンス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を併用して指定してください。

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

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

本サービスで発生する各種イベントの結果は「ウェブフック」として、それぞれの指定先URLにHTTP POSTメソッドで送信されます。

ウェブフックは、管理画面＞ウェブフック＞ウェブフック追加　から設定できます。
複数のイベントで同じURLを、チェックボックスで指定することも可能です。

作成したウェブフックのURL、Authorizationヘッダー、トリガーは、後から変更することもできます。

※通知内容の各オブジェクトの説明、ウェブフック情報の取得・変更処理のAPIについてはこちら

注意事項

ウェブフックはベストエフォートのため、通知の成功や通知速度を保証するものではありません。
決済の結果を短時間で加盟店さまのページで次の処理を行いたい場合は、APIのリクエストで課金情報の取得(課金:GET)、もしくはウィジェットのパラメータに記述を追加することでコールバックのイベントをリアルタイムで受け取ることを推奨します。

ウェブフックの失敗後の挙動

ウェブフックの通知が失敗した場合、返却されたエラーコードによってリトライを行います。
失敗により停止したウェブフックは管理画面・もしくはAPIで再開する必要があります。

リトライ間隔は、1回目は1分でその後指数関数的に増加※し、最大は15分です。
※1分、2分、4分、8分、、と間隔が伸びていくこと

ウェブフック失敗・停止時のお知らせ機能

管理画面より、ウェブフックが失敗・停止した際にメール通知を受け取る設定ができます。

必要な場合は、管理画面＞一般設定＞一般＞通知　の「ウェブフック」の各項目を有効にしてください。

イベント名の一覧

※イベントごとに取得できる情報の一覧やパラメータの説明、ステータスについては各リソースタイプのリンク先よりご確認ください。

決済情報と消費者に関する個人情報を取得する為のリソースです。
課金（Charge）や定期課金を作成する為にはトランザクショントークンが事前に作成されている必要があります。

決済を行うシステムの PCI DSS 準拠

決済を行うシステムが PCI DSS に準拠していない場合、カード番号のような保護が必要な情報を直接取得することはできません。
代わりにAndroidのモバイルウィジェットや、本サービスが提供するブラウザウィジェット や 決済端末 など当社の提供するソリューションを使用する必要があります。

トークンの種類

• one_time – ワンタイムトークン
• subscription – 定期課金トークン
• recurring – リカーリングトークン

ワンタイムトークン

1回だけ課金を作ることができ有効期間は作成から5分間です。
大量の課金を処理するために並行して複数のワンタイムトークンを作ることができますが、一定期間内に同一のカードで課金できる回数には制限があります。
課金のオーソリ（仮売上）と、後日に売上を確定させるキャプチャ（実売上）にも使用することができます。
キャプチャは指定した日付に自動的に行うことや任意のタイミングでAPIを呼び出して行うことができます。
キャプチャする金額はオーソリを行った金額以下である必要があります。
課金のオーソリを行うには、オーソリに対応したゲートウェイ（接続先）を使用する必要があります。
詳しくは課金（Charge）を参照してください。

定期課金トークン

一定のスケジュールで顧客に請求をする必要がある場合、定期課金トークンを使用することをお薦めします。
定期課金を作成することができ、定期課金では課金の間隔、初回金額、定期課金金額、開始日を指定することができます。
このトークンの有効期間は作成から5分間です。
定期課金はキャンセルされるまで期限なしで継続されます。
定期課金は、一定期間をかけて支払いをする為の分割払いのプランを作成することができます。
詳しくは定期課金リソースを参照してください。
当システムでは同一カード番号で定期課金トークンを作成できるのは1つまでのため、5分以内に同一カード番号を入力して送信するとエラーが発生します。
定期課金トークンに対して課金されると再度作成が可能になります。

リカーリングトークン

一度決済したクレジットカードで、任意のタイミングで再び決済を行いたい場合はリカーリングトークンの作成をお勧めします。
リカーリング（再利用可能）トランザクショントークンを作成するには、アカウントに対して作成権限が必要となります。
審査によって、トークンを無制限（infinite）利用できるか、制限付き（bounded）で利用可能かが決まります。
無制限の場合は、そのトークンは任意のタイミングで課金を作成することができます。
制限付きの場合は、そのトークンは一定期間に1回しか課金を作成することができません。
トークンが作成されると、その個人情報は UnivaPay のプラットフォーム上に安全に保管され、変更することはできなくなります。
PATCH（変更）可能な情報は、email / metadataとセキュリティコード（CVV）のみです。
CVVはリカーリングトークンを使用している場合で、課金金額がストア設定で指定したしきい値を超えた場合に必要となります。
これは設定された上限を超える追加の請求について、消費者の同意を得る為の仕組みです。
作成後5分以内にトークンが使用されない場合、CVVは自動的に期限切れになり、構成によっては、トークンのCVV値で再度更新する必要がある場合があります。

セキュリティコード（CVV）認証

リカーリングトークンによるクレジットカード払いでのみ利用できる機能です。
有効なクレジットカードとそれに対応するCVVを事前に承認して、後で支払いに利用できるようにします。
たとえば、消費者がカード情報を保存すれば、その後いつでもそれを使って購入することができます。
デフォルトでは、data.cvv_authorize.enabled=true でない限り、この機能は有効になっていません。
内部的には、システムがゲートウェイに認証リクエスト（1円の仮売のリクエスト）を行い、これには少なくとも数秒かかる場合があります。
これが完了すると、リカーリングトークンはそのゲートウェイに承認済みとしてロックされ、 cvv_authorize.status は current に更新されます。
トークンは、承認プロセスが正常に完了するまで課金を作成することはできません。
課金作成を行う前に、常にステータスが current であることを確認することを推奨します。
それ以外の場合は、続行する前にCVV値を更新してください。
なんらかの理由でゲートウェイが加盟店からリンク解除されている場合、トークンは「非アクティブ」（inactive）状態に移行するため、CVV値をトランザクショントークンのUPDATEで更新する必要があります。
その後、自動的に認証が試行されます。

支払い手段

トランザクショントークンは以下の支払い手段を持ちます。

• card – クレジットカード決済
• paidy – Paidy決済
• online – オンラインモバイル決済
  ワンタイムトークンのみ
• konbini – コンビニ決済
  リカーリングトークンでは使用不可
• bank_transfer – 銀行振込決済

支払手段ごとに異なる支払い情報が必要となります。
詳細は、トランザクショントークンの作成 のdataパラメータを参照ください。

“transaction”オブジェクトのデータ構造

イシュアトークン