コンビニ決済　導入ガイド

コンビニ決済について

電算システムを利用した決済サービスです。決済フォームでの情報入力が完了すると、指定したコンビニエンスストアで支払いを行うための情報が発行されます。支払いに必要な情報は、通知メールもしくはメタデータから確認可能です。
こちらの情報をもとに支払いを行うと、入金確認を自動で行い、結果を反映いたします。
また、管理画面の「ウェブフック」でURLを登録することによって、入金結果のシステム通知を受けることも可能です。

課金ステータス

管理画面の[決済]から申込や入金の履歴を確認することができます。

処理待ち
決済フォームから申込が完了しているが消費者からの入金がされていない、もしくは入金確認中の状態です。
成功
消費者が各コンビニエンスストアで入金を完了した状態です。
キャンセル
加盟店さま側で申込を取り消した状態です。
失敗
決済フォームでの申込時に何かしらのエラーが発生した、もしくは入金期限を過ぎた状態です。

入金期限について

入金期限を超えた課金申込は失敗となり、決済失敗メールが送信されます。
後述するように様々な方法で入金期限を指定できますが、それぞれの日数ごとの入金期限日時について下記を参考にして下さい。

期限パターン例

一週間
- 1/1 に申込を行った場合、1/8 23時59分までに振込
二週間
- 1/1 に申込を行った場合、1/15 23時59分までに振込
30日
- 1/1 に申込を行った場合、1/31 23時59分までに振込

入金期限の指定方法

管理画面、ウィジェット・インラインフォームのパラメータ、APIで入金期限を設定できます。

管理画面で指定
一般設定>決済サービス>決済方法から、支払期限期間と入金期限時間を設定できます。
パラメータ、APIで指定しない限り、ここでの設定が適用されます。
デフォルトは30日、期限時間は23:59:59です。

ウィジェット・インラインフォームのパラメータで指定
HTMLとJavaScriptのパラメータで期間を指定可能です。

時間は”時刻+タイムゾーン”の形式で表します。

（タイムゾーンの例：日本であれば+09:00）

HTML
　※詳細はこちら
- 入金可能期間：data-expiration-period=”P7D” (決済申込を行ってから何日間入金が可能か)
- 入金期限時間：data-expiration-time-shift=”12:00:00+09:00″　(expiration-periodで入金期限日を決定し、期限日の何時まで入金を行えるか)
- 入金期限日時：data-capture=”false”、data-capture-at=”2023-04-01 21:00″(申込日時に関わらず入金期限日時を指定)
JavaScript
　※詳細はこちら
- 入金可能期間：expirationPeriod=”P7D” (決済申込を行ってから何日間入金が可能か)
- 入金期限時間：expirationTimeShift=”12:00:00+09:00″　(expirationPeriodで入金期限日を決定し、期限日の何時まで入金を行えるか)
- 入金期限日時：capture=”false”、captureAt=”2023-04-01 21:00″(申込日時に関わらず入金期限日時を指定)

APIで指定
APIのリクエストを送る際にパラメータで支払期限を指定できます。

トランザクショントークンを作成時に指定
- 　data.expiration_period で支払いの有効期限を指定できます。最短30分、最大は60日(0:00に決済、59日後の23:59までで実質60日間)です。
  ※詳細はこちら
課金を作成時に指定
- 　capture_at で支払い期限日時を指定できます。ここで期日を指定した場合、トランザクショントークンで指定した期間より優先されます。
  ※詳細はこちら

※日付および時間の指定は、両方/日付のみ/両方なし（パラメータを送信しない）のいずれかのパターンでリクエストしてください。

※下記支払先は、時刻指定がご利用いただけません。

セブンイレブン
セイコーマート/他支払（サークルK/サンクス/ペイジー）
この場合、時刻は無視されその日までという扱いになります。

Widget / リンクフォームの実装

弊社提供のWidgetやリンクフォームで実装する場合の説明です。
加盟店様で1から支払ページを作成する必要がなくスムーズな導入が可能です。

Widget：

詳細な設置方法はリンク先のドキュメントをご確認ください。

Widget HTML 記載例）

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

※Widget上に利用可能な支払方法を全て表示させる場合は、
「data-payment-type=”konbini”」の行を取り除いてください。

リンクフォーム：

詳細な設置方法はリンク先のドキュメントをご確認ください。
なお、コンビニ決済ではリンクフォーム作成時に、「詳細設定」の以下項目にご注意いただき、作成をお願いいたします。

CVV認証（CVV auth）、仮売上、分割払い：
コンビニ決済では無効な項目です。有効にしてもコンビニ決済ではご利用いただけません。
定期課金:
コンビニ決済では未実装です。有効にしてもコンビニ決済ではご利用いただけません。

APIの実装について

弊社提供のWidgetやリンクフォームを使用せず、加盟店様側で支払ページを作成しAPIで処
理するフローの説明です。本ガイドはコンビニ決済における各API処理の補足説明となっております。

1、トークン作成

お客様情報をトークン化して保存します。

リクエスト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、課金作成

作成したトークンに対して課金申込を行います。

リクエストBody 例)

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

3、課金の取得

課金申込の結果を取得します。ウェブフック(※)で結果を受信することも可能です。
「”status”: “awaiting”」が確認できたら正常に課金申込が完了し、お客様の入金待ちの状態です。
※ウェブフックのイベント名は「charge_updated」です。

支払先の情報はレスポンスの"metadata"内で確認できます。

"internal_convenience_payment_number"は各種コンビニの支払い番号、"internal_convenience_payment_url"は支払い票のURLになります（セブンイレブンのみ）。
※Pay-easyの場合は別途支払いに収納機関番号が必要になり、申込完了メールにのみ反映されます。値は58091で固定です。

課金作成リクエストに対するレスポンスでは反映されず、”status”: “awaiting”になったタイミング以降でGETリクエストを送信すると反映されています。

レスポンス / ウェブフック 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"
}

4、課金の取得

APIリクエストで入金結果、入金期限切れの結果を取得します。
ウェブフックで結果を受信することも可能です。
※ウェブフックのイベント名は「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」で入金額を確認できます。
2つの項目の組み合わせで状況をご確認ください。

テストについて

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

通知メールテンプレートについて

管理画面の[通知メールテンプレート]から、コンビニ決済に関する通知メールの内容を編集することができます。

コンビニ決済のご案内
決済申し込みを行った際に送信されます。${konbini_payment_details}に各コンビニエンスストアでの支払い番号などが記載されます。
${date}では入金期日が表示されます。
コンビニ決済の取り消し
ユーザーが入金を行う前に加盟店側で注文を取り消した際に送信されます。
コンビニ決済(各種コンビニ名)の詳細
このテンプレートでは${konbini_payment_details}の内容をそれぞれ編集可能です。

※入金が完了した際には[決済完了通知]、支払い期限切れの場合は[決済失敗]の場合はメールをそれぞれ送信します。

「コンビニ決済のご案内」のテンプレート(デフォルト)

${store}　コンビニ決済のお申し込みを受け付けました

=========================================================
このメールは決済されたメールアドレス宛に自動的に送信しております。
決済情報をご確認のうえ、大切に保管してください。
=========================================================

この度は、${store}をご利用いただき誠にありがとうございます。
内容をご確認の上、期日までにご入金をお願いいたします。
——————————————————————————————-
[支払方法　] コンビニ決済
[コンビニ名] ${payment_brand}
[課金ID　　] ${charge_id}
[金額　　　] ${amount}
[入金期限　]${date}

${konbini_payment_details}

——————————————————————————————-
${store}　お問い合わせ先情報
[電話番号　　　] ${contact_phone}
[メールアドレス] ${contact_email}

※このメールは送信専用のため、このアドレスへご連絡いただいても返信できかねます。
　ご連絡はご利用の商品/サービス提供者様へお願いいたします。

コンビニ決済 導入ガイド