トランザクショントークン

トランザクショントークンは、決済情報と顧客に関する個人情報を取得する為のリソースです。課金(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.statuscurrent に更新されます。
トークンは、承認プロセスが正常に完了するまで課金を作成することはできません。

課金作成を行う前に、常にステータスが current であることを確認することを推奨します。それ以外の場合は、続行する前にCVV値を更新してください。

なんらかの理由でゲートウェイが加盟店からリンク解除されている場合、トークンは「非アクティブ」( inactive )状態に移行するため、CVV値をトランザクショントークンのUPDATEで更新する必要があります。その後、自動的に認証が試行されます。

支払い手段

加えて、トランザクショントークンは以下の支払い手段を持ちます:

  • card – クレジットカード決済。
  • qr_scan – CPM(ユーザーが表示する方式)のQRコード決済。ワンタイムトークンのみ。
  • qr_merchant – MPM(加盟店が表示する方式)のQRコード決済。ワンタイムトークンのみ。
  • online – Online決済。ワンタイムトークンのみ。
  • apple_pay – Apple Pay
  • konbini – コンビニ決済。リカーリングトークンでは使用できません。
  • bank_transfer – 銀行振込決済。

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

トランザクショントークンオブジェクト

Fields
idUUID
トランザクショントークンのID
store_idUUID
店舗ID
emailstring
支払いの為の顧客のメールアドレス
ip_addressstring
ユーザーのデバイスのIPv4アドレス
typestring
トークンが作成できる課金の種類。次のいずれか: one_time, subscription, recurring
usage_limitstring
typerecurring の場合、このトークンが使用可能な間隔。次のいずれかの値: daily, weekly, monthly, annually, null (トークンの利用制限が無い場合)
modestring
どのモードでトークンが作成されたか。これはトークン作成時に使ったアプリケーショントークンにより決定されます。livetest のいずれか
payment_typestring
このトークンが保持する支払い手段の種類。
metadataobject
トランザクショントークンに保存されているメタデータ
created_onstring (ISO-8601)
トランザクショントークンの作成日時
last_used_onstring (ISO-8601)
トランザクショントークンの最終使用日時
data.card.cardholderstring
クレジットカードの所有者の名前
data.card.exp_monthnumber
有効期限(月)
data.card.exp_yearnumber
有効期限(年)
data.card.last_fourstring
クレジットカード番号の最後4桁
data.card.brandstring
カードブランド。visa, mastercard, jcb, diners_club, unionpay, american_express, maestro, discover, unknownのいずれか
data.card.categorystring
カードのカテゴリ。Apple Pay の場合は利用できません
data.card.issuerstring
カード発行会社。Apple Pay の場合は利用できません
data.card.sub_brandstring
カードのサブブランド。Apple Pay の場合は利用できません
data.billing.line1string or null
カードの請求先住所1
data.billing.line2string or null
カードの請求先住所2
data.billing.statestring or null
カードの請求先住所の州/地域/都道府県
data.billing.citystring or null
カードの請求先住所の市町村区
data.billing.countrystring (ISO Alpha-2)
カードの請求先住所の国
data.billing.zipstring or null
カードの請求先住所の郵便番号
data.billing.phone_number.country_codestring or null
請求先住所の電話番号の国コード
data.billing.phone_number.local_numberstring
請求先住所の電話番号
data.cvv_authorize.enabledboolean
セキュリティコード認証機能が有効かどうか
data.cvv_authorize.statusstring
認証のステータス。 「保留」( pending )、「処理中」( current )、「失敗」( failed )、または「非アクティブ」( inactive )のいずれか
data.cvv_authorize.currencystring (ISO-4217)
手動で更新された場合に認証を行うように要求された通貨
data.cvv_authorize.charge_idstring (UUID)
認証に使用された課金情報のID
data.cvv_authorize.credentials_idstring (UUID)
認証に使用された資格情報ID
トークンはこの資格情報にロックされ、非アクティブ化すると、トークンは「非アクティブ」( inactive )状態に変わります
data.gatewaystring
支払い処理を行ったゲートウェイ
QRコード支払いの場合に利用可能
data.brandstring
ブランド
onlinebank_transfer支払いの場合に利用可能
data.call_methodstring
クライアントが要求した実行方法
HTTP get , HTTP post , sdk MiniApp, app Native App , web in-app browser H5のいずれか
data.user_identifierstring
一部のブランドで使用されているユーザー固有の識別子
data.os_typestring
モバイルデバイスのOS
data.customer_namestring
顧客名。コンビニ払いの場合に利用可能
data.phone_number.country_codestring or null
電話番号の国コード
data.phone_number.local_numberstring
電話番号
data.convenience_storestring
支払いを行うコンビニエンスストアの名前。コンビニ払いの場合に利用可能
data.expiration_periodstring (ISO-8601 Duration)
支払期間。コンビニ払いの場合に利用可能
data.match_amountstring
振込金額のマッチングアルゴリズム。銀行振込の場合に利用可能
data.bank_codestring
振込支払先の銀行コード。銀行振込の場合に利用可能
data.bank_namestring
振込支払先の銀行名。銀行振込の場合に利用可能
data.branch_codestring
振込支払先の支店コード。銀行振込の場合に利用可能
data.branch_namestring
振込支払先の支店名。銀行振込の場合に利用可能
data.account_numberstring
振込支払先の口座番号。銀行振込の場合に利用可能
data.account_holder_namestring
振込支払先の口座名義。銀行振込の場合に利用可能