トランザクショントークン – 概要
決済情報と消費者に関する個人情報を取得する為のリソースです。
課金（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”オブジェクトのデータ構造
| フィールド | データ型 | 備考 |
|---|---|---|
| id | UUID | トランザクショントークンのID |
| store_id | UUID | 店舗ID 契約時に自動付与 |
| string | 支払いの為の消費者のメールアドレス | |
| ip_address | string | 消費者のデバイスのIPv4アドレス |
| type | string | トークンが作成できる課金の種類 one_time / subscription / recurring |
| active | boolean | トークンが利用済みか無効かどうか ※typeがone_timeかsubscriptionの場合 |
| usage_limit | string | typeがrecurringの場合、このトークンが使用可能な間隔 存在し得る値： daily weekly monthly annually null（トークンの利用制限が無い場合） |
| mode | string | どのモードでトークンが作成されたか トークン作成時に使ったアプリケーショントークンにより決定 存在し得る値： live（本番モード） test（テストモード） |
| payment_type | string | このトークンが保持する支払い手段の種類 |
| metadata | object | トランザクショントークンに保存されているメタデータ |
| created_on | ISO-8601 | トランザクショントークンの作成日時 |
| updated_on | ISO-8601 | トランザクショントークンの更新日時 |
| last_used_on | ISO-8601 | トランザクショントークンの最終使用日時 |
| data.card.cardholder | string | カードの所有者の名前 |
| data.card.exp_month | number | 有効期限（月） |
| data.card.exp_year | number | 有効期限（年） |
| data.card.last_four | string | カード番号の最後４桁 |
| data.card.card_bin | string | カード番号のBIN番号 |
| data.card.card_type | string | カードのタイプ |
| data.card.country | string | カードの発行国 |
| data.card.brand | string | カードブランド 存在し得る値： visa mastercard jcb diners_club unionpay american_express maestro discover unknown |
| data.card.category | string | カードのカテゴリー |
| data.card.issuer | string | カード発行会社 |
| data.card.sub_brand | string | カードのサブブランド |
| data.billing.line1 | string or null | カードの請求先住所1 |
| data.billing.line2 | string or null | カードの請求先住所2 |
| data.billing.state | string or null | カードの請求先住所の州 / 地域 / 都道府県 |
| data.billing.city | string or null | カードの請求先住所の市町村区 |
| data.billing.country | string (ISO Alpha-2) | カードの請求先住所の国 |
| data.billing.zip | string or null | カードの請求先住所の郵便番号 |
| data.billing.phone_number.country_code | string or null | 請求先住所の電話番号の国コード |
| data.billing.phone_number.local_number | string | 請求先住所の電話番号 |
| data.cvv_authorize.enabled | boolean | セキュリティコード認証機能が有効かどうか |
| data.cvv_authorize.status | string | 認証のステータス 存在し得る値： 保留（pending） 有効（current） 失敗（failed） 非アクティブ（inactive） |
| data.cvv_authorize.currency | string (ISO-4217) | 手動で更新された場合に認証を行うように要求された通貨 |
| data.cvv_authorize.charge_id | string（UUID） | 認証に使用された課金情報のID |
| data.cvv_authorize.credentials_id | string（UUID） | 認証に使用された資格情報ID トークンはこの資格情報にロックされ、非アクティブ化するとトークンは非アクティブ（inactive）状態に変わる |
| data.three_ds.enabled | boolean | このトランザクショントークンで3D-セキュアを実行するかどうか トークンタイプが recurringの場合のみtrueを指定可未指定時、既存ルールに応じて trueまたはfalseのいずれかに指定されます。この値を falseに指定すると、後で課金を作成する際に3-Dセキュア認証がトリガーされる可能性があります |
| data.three_ds.status | string | 有効時の3D-セキュアのステータスpending、awaiting、successful、failed、errorのいずれか |
| data.three_ds.redirect_endpoint | string (URL) | 顧客が3D-セキュア認証から戻る際のリダイレクトエンドポイント 未指定時、デフォルトの完了ページを表示し、元のウェブサイトに手動で戻るよう求められます。 指定すると、顧客はGET httpメソッドで指定されたエンドポイントにリダイレクトされます。 すべてのメタデータ（課金作成時に指定されたもの、作成後に更新された追加メタデータは含まない）と univapayTokenIdは、クエリパラメータの一部として自動的に送信されます。任意でエンドポイントURLにクエリパラメータを追加することができます。 |
| data.three_ds.redirect_id | string (UUID) | リダイレクトリクエストの一意な識別子 リダイレクトURLが正常に指定された場合当システム側で入力されます。 |
| data.gateway | string | 支払い処理を行ったゲートウェイ QRコード支払いの場合に利用可能 |
| data.brand | string | ブランド onlineとbank_transfer支払いの場合に利用可能 |
| data.issuer_token | string | イシュアトークン payment_typeがonlineの場合 |
| data.issuer_token_payload | string | イシュアトークンのペイロード payment_typeがonlineの場合 |
| data.call_method | string | クライアントが要求した実行方法 存在し得る値： HTTP get HTTP post sdk MiniApp app Native App web in-app browser H5 |
| data.user_identifier | string | 一部のブランドで使用されている消費者固有の識別子 |
| data.os_type | string | モバイルデバイスのOS |
| data.customer_name | string | 顧客名 コンビニ決済の場合に利用可能 |
| data.phone_number.country_code | string or null | 電話番号の国コード |
| data.phone_number.local_number | string | 電話番号 |
| data.convenience_store | string | 支払いを行うコンビニエンスストア名 コンビニ決済の場合に利用可能 |
| data.expiration_period | string (ISO-8601 Duration) | 支払期間 コンビニ決済 / 銀行振込の場合に利用可能 |
| data.expiration_time_shift | string (ISO-8601 Duration) | 支払期限の時間 コンビニ決済 / 銀行振込の場合に利用可能 |
| data.match_amount | string | 振込金額のマッチングアルゴリズム 銀行振込の場合に利用可能 |
| data.bank_code | string | 振込支払先の銀行コード 銀行振込の場合に利用可能 |
| data.bank_name | string | 振込支払先の銀行名 銀行振込の場合に利用可能 |
| data.branch_code | string | 振込支払先の支店コード 銀行振込の場合に利用可能 |
| data.branch_name | string | 振込支払先の支店名 銀行振込の場合に利用可能 |
| data.account_number | string | 振込支払先の口座番号 銀行振込の場合に利用可能 |
| data.account_holder_name | string | 振込支払先の口座名義 銀行振込の場合に利用可能 |
