トランザクショントークン
トランザクショントークンは、決済情報と顧客に関する個人情報を取得する為のリソースです。課金（Charge）や定期課金を作成する為にはトランザクショントークンが事前に作成されている必要があります。
決済を行うシステムが PCI DSS に準拠していない場合、カード番号のような保護が必要な情報を直接取得することはできません。
代わりにAndroid, iOS向けのモバイルウィジェットや、当サービスが提供するブラウザウィジェット や 決済端末 など弊社の提供するソリューションを使用する必要があります。
トークンの種類
トランザクショントークンは、以下の種類があります:
one_time– ワンタイムトークン。課金（Charge） リソースを作成します。デフォルトではこのタイプになります。subscription– 定期課金トークン。定期課金 リソースを作成します。recurring– リカーリングトークン。課金（Charge） リソースを作成します。
ワンタイムトークン
ワンタイムトークンは、1回だけ課金を作ることができ、有効期間は作成から5分間です。大量の課金を処理するために、並行して複数のワンタイムトークンを作ることができますが、一定期間内に同一のカードで課金できる回数には制限があります。
ワンタイムトークンは課金のオーソリ（仮売上）と、後日に売上を確定させるキャプチャ（実売上）にも使用することができます。
キャプチャは指定した日付に自動的に行うことや任意のタイミングでAPIを呼び出して行うことができます。
キャプチャする金額はオーソリを行った金額以下である必要があります。課金のオーソリを行うには、オーソリに対応したゲートウェイクレデンシャル（仕向け）が必要になります。詳しくは課金（Charge）を参照してください。
定期課金トークン
一定のスケジュールで顧客に請求をする必要がある場合、定期課金トークンを使用することをお薦めします。
このトークンは定期課金を作成することができ、定期課金では課金の間隔、初回金額、定期課金金額、開始日を指定することができます。
このトークンの有効期間は作成から5分間です。定期課金はキャンセルされるまで期限なしで継続されます。
定期課金は、一定期間をかけて支払いをする為の、分割払いのプランを作成することができます。詳しくは定期課金リソースを参照してください。
本システムでは同一カード番号で定期課金トークンを作成できるのは1つまでのため、5分以内に同一カード番号を入力して送信するとエラーが発生します。
定期課金トークンに対して課金されると再度作成が可能になります。
リカーリングトークン
一度決済したクレジットカードで、任意のタイミングで再び決済を行いたい場合はリカーリングトークンの作成をお勧めします。
リカーリング（再利用可能）トランザクショントークンを作成するには、アカウントに対して作成権限が必要となります。審査によって、トークンを無制限(infinite)に利用できるか、制限付き(bounded)で利用可能かが決まります。無制限の場合は、そのトークンは任意のタイミングで課金を作成することができます。制限付きの場合は、そのトークンは一定期間に1回しか課金を作成することができません。
トークンが作成されると、その個人情報は UnivaPay のプラットフォーム上に安全に保管され、変更することはできなくなります。PATCH （変更）可能な情報は、email, metadataと セキュリティコード（CVV） のみです。CVVはリカーリングトークンを使用している場合で、課金金額がストア設定で指定したしきい値を超えた場合に必要となります。
これは設定された上限を超える追加の請求について、ユーザーの同意を得る為の仕組みです。
作成後5分以内にトークンが使用されない場合、CVVは自動的に期限切れになり、構成によっては、トークンのCVV値で再度更新する必要がある場合があります。
セキュリティコード（CVV）認証
セキュリティコード（CVV）認証は、リカーリングトークンによるクレジットカード払いでのみ利用できる機能です。
有効なクレジットカードとそれに対応するCVVを事前に承認して、後で支払いに利用できるようにします。
たとえば、顧客がカード情報を保存すれば、その後いつでもそれを使って購入することができます。
デフォルトでは、 data.cvv_authorize.enabled = true でない限り、この機能は有効になっていません。
内部的には、システムがゲートウェイに認証リクエスト（1円の仮売のリクエスト）を行い、これには少なくとも数秒かかる場合があります。
これが完了すると、リカーリングトークンはそのゲートウェイに承認済みとしてロックされ、 cvv_authorize.status は current に更新されます。
トークンは、承認プロセスが正常に完了するまで課金を作成することはできません。
課金作成を行う前に、常にステータスが current であることを確認することを推奨します。それ以外の場合は、続行する前にCVV値を更新してください。
なんらかの理由でゲートウェイが加盟店からリンク解除されている場合、トークンは「非アクティブ」( inactive )状態に移行するため、CVV値をトランザクショントークンのUPDATEで更新する必要があります。その後、自動的に認証が試行されます。
支払い手段
加えて、トランザクショントークンは以下の支払い手段を持ちます:
card– クレジットカード決済。qr_scan– CPM（ユーザーが表示する方式）のQRコード決済。ワンタイムトークンのみ。qr_merchant– MPM（加盟店が表示する方式）のQRコード決済。ワンタイムトークンのみ。online– Online決済。ワンタイムトークンのみ。apple_pay– Apple Paykonbini– コンビニ決済。リカーリングトークンでは使用できません。bank_transfer– 銀行振込決済。
支払手段ごとに異なる支払い情報が必要となります。詳細は、トランザクショントークンの作成 のdata パラメータを参照ください。
トランザクショントークンオブジェクト
| Fields | |
|---|---|
| id | UUID トランザクショントークンのID |
| store_id | UUID 店舗ID |
| string 支払いの為の顧客のメールアドレス | |
| ip_address | string ユーザーのデバイスのIPv4アドレス |
| type | string トークンが作成できる課金の種類。次のいずれか: one_time, subscription, recurring |
| usage_limit | stringtype が recurring の場合、このトークンが使用可能な間隔。次のいずれかの値: daily, weekly, monthly, annually, null (トークンの利用制限が無い場合) |
| mode | string どのモードでトークンが作成されたか。これはトークン作成時に使ったアプリケーショントークンにより決定されます。 live か test のいずれか |
| payment_type | string このトークンが保持する支払い手段の種類。 |
| metadata | object トランザクショントークンに保存されているメタデータ |
| created_on | string (ISO-8601) トランザクショントークンの作成日時 |
| last_used_on | string (ISO-8601) トランザクショントークンの最終使用日時 |
| data.card.cardholder | string クレジットカードの所有者の名前 |
| data.card.exp_month | number 有効期限（月） |
| data.card.exp_year | number 有効期限（年） |
| data.card.last_four | string クレジットカード番号の最後４桁 |
| data.card.brand | string カードブランド。 visa, mastercard, jcb, diners_club, unionpay, american_express, maestro, discover, unknownのいずれか |
| data.card.category | string カードのカテゴリ。Apple Pay の場合は利用できません |
| data.card.issuer | string カード発行会社。Apple Pay の場合は利用できません |
| data.card.sub_brand | string カードのサブブランド。Apple Pay の場合は利用できません |
| data.billing.line1 | string or null カードの請求先住所１ |
| data.billing.line2 | string or null カードの請求先住所２ |
| 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.gateway | string 支払い処理を行ったゲートウェイ QRコード支払いの場合に利用可能 |
| data.brand | string ブランド onlineとbank_transfer支払いの場合に利用可能 |
| 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.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 振込支払先の口座名義。銀行振込の場合に利用可能 |