Omiseのコンビニ対応について公式ドキュメントの不備不足を補填してみた

# 前提
決済サービスの [Omise](https://www.omise.co/ja) がコンビニ対応してくれました。
海外に軸足置きつつ日本にも対応している新興の各決済サービスの中で、コンビニ対応までしてくれているのは Omise くらいです。素晴らしい。

が。

以前から他記事でも書いてきました通り、 Omise は公式ドキュメントが大変不親切です。正確でなかったり古かったり不足していたり……その代わり(？)サポートの方からの返信は早いです。

なので、今回、問い合わせてみて返ってきた回答をまとめました。

### ＃Attention！ 現時点(2018/06/01)でコンビニ決済ができるようになったはずです
現時点(2018/06/01)でテスト環境において決済用の URL が発行されるようになりました。ただ、イーコンテクスト側での動作テストはテスト環境ではできません。申請通過させた上で本番環境でないとテストできないというのは、利用ストーリーを想像できないので、かなりつらいですね。なので、まだ、実際には使えてません。

* 参照： [イーコンテクストのWEBサイトにおけるコンビニページ](https://www.econtext.jp/service/settlement/konbini)
    * 特に事業者側のフローは書いてありませんでした。


## コンビニ決済の公式ドキュメント
https://www.omise.co/ja/convenience-store-payment

## 以前に書いた Omise 関連の記事
* [クレジットカード決済のOmiseからPOSTで渡されるデータをGoogleAppsScriptにて受け取る](https://qiita.com/Hi_Noguchi/items/effbcf129dfaa77608b7)
* [クレジットカード決済にOmiseを導入してみている最中で、良さそうな点・いまいちな点](https://qiita.com/Hi_Noguchi/items/b8d71a1341ad07ce3296)
* [Omise.jsのdata-amount値を可変にする](https://qiita.com/Hi_Noguchi/items/14a3d4e16afcf6fb35ed)

# 質問 ＆ 回答集
いきまーす。

### Q： どうやったらコンビニ支払を使い始められますか？
#### A： ショップアカウント開設後、クレジットカードとは別に利用申請書類が必要です。営業担当に問い合わせてください。

### Q： テストショップでも申請が必要ですか？
#### A： テストショップの場合、利用申請の必要はありません。
ただし、以前からの利用者の場合、 API のバージョンを更新しておく必要があります。次の項を参照。

### Q： サンプルとして置いてある cUrl を叩いたら「you are using api version which does not support this operation」というエラーが返ってくるのですが……
#### A： 管理画面で API の version を最新に更新してください。

右上のメニュー内にある「APIバージョン」をクリックしてください。

![image.png](https://qiita-image-store.s3.amazonaws.com/0/37739/86d4ed49-2316-14c9-a29c-6f5916b887dd.png)

以下のような状態だと、まだ Source API が利用できません。

![image.png](https://qiita-image-store.s3.amazonaws.com/0/37739/26fde3ab-404d-e30d-efcf-c066fa0b60cd.png)

更新して、以下のようになっていれば OK です。

![image.png](https://qiita-image-store.s3.amazonaws.com/0/37739/653c37c1-a051-ba88-182a-4a1289d45a57.png)

「コンビニ決済の実装は 2018/05 なのに、最新版は 2017/11/02 なんですか！？」というのはツッコミどころです。セマンティックバージョニングを導入した上で、更新タイムラインを掲載したらいいんじゃないかと思います。してください（強い願望）

サンプルのコマンドは以下です（一部値を汎用的なものへ書き換え）

```
curl https://api.omise.co/sources \
  -X POST \
  -u 自身のsecret_key: \
  -d "amount=150" \
  -d "currency=jpy" \
  -d "type=econtext" \
  -d "name=Customer" \
  -d "email=hogehoge@fugafuga" \
  -d "phone_number=01234567891" 
```

#### 補足
ちなみに管理画面では source オブジェクトを閲覧する UI がまだ提供されていないようです。
左側メニューの一番下にある API > ログ から、「リクエストパラメータ」と「レスポンスヘッダとボディ」とを見ることはできるので、ひとまずそちらで我慢。

![image.png](https://qiita-image-store.s3.amazonaws.com/0/37739/afa522fe-7c59-1d23-f360-25154686504e.png)


### Q： 上記で作成した source オブジェクトをもとに Charge API を叩いて課金オブジェクトを作ってみたのですが、 authorize_uri が null で返ってきてしまいます。

#### A： 2018/06/01 付で解消されました。 authorize_uri に入っているにアクセスしてみると、以下のキャプチャ画像のような画面に遷移します。なお、それでもまだ null で返ってきてしまう場合はサポートにお問合せください。

![image.png](https://qiita-image-store.s3.amazonaws.com/0/37739/5f4a0725-a05c-bee9-ada6-cf4adfe82abc.png)

どうやらイーコンテクスト側での動作テストはできないようです。

### Q: 上記で作成した課金オブジェクト内の reference の値について。サンプルでは null になっているのに、実際には値が返ってきましたが？

#### A：  [Charge API のドキュメント](https://www.omise.co/ja/charges-api) によれば、 reference の値が入ってくるのは、「return_uriがレスポンスに含まれている場合に、Chargeのリファレンスコードが含まれます。」とのことです。サンプルが誤っているのでしょう。ちなみに表示順も誤っています。

以下は、公式ドキュメント内の JSON レスポンスの例から、末尾抜粋したもの。

``` 
  },
  "disputable": false,
  "capturable": false,
  "reversible": false,
  "refundable": false
}
```

以下は、実際に返ってくるもの。

```
  },
  "disputable": false,
  "capturable": false,
  "reversible": false,
  "refundable": false,
  "reference": "oflp_test_5bvt5yvo305brpfnx2d",
  "authorize_uri": "https://pay.omise.co/offlines/econtext/instructions/hogehogefugafuga"
}
```

### Q： Omise.js のように、 js でモーダル表示させてコンビニ決済させることはできますか？
#### A： Omise.js はあくまでクレジットカード決済用です。コンビニ決済には対応していません。
いかにも使えそうなサンプル画面がドキュメントの上部に表示されているのですが、それはダミーです。
なお、この問合せを受け、これからコンビニ決済も対応させる予定とのこと。対応されたら記事更新します。

### Q： コンビニブランドの選択をユーザがした結果を、こちらが受け取ることはできますか？　例えば、ローソンでの支払を選択した。とか。
#### A： 限定的に可能です。
ユーザに渡せるのは、以下いずれかの支払方法を選択するための URL のみになります。 ​authorize_uri という項目に該当の URL が値として入って返ってきます。

* 各コンビニ
    * セブンイレブン
    * ファミリーマート
    * サークルK・サンクス
    * ローソン
    * ミニストップ
    * セイコーマート）

なお、以下については、現時点(2018/05/12)では利用できないとのことです。

* 銀行系
    * ゆうちょ銀行
    * Pay-easy（ペイジー）
    * 各ATM
    * モバイルバンキング

### Q： ユーザが支払番号を紛失したなどの問合せをしてくることがあります。その際に、担当者が支払番号を確認することができますか？
#### A： 上記の ​authorize_uri を開くと確認できます。
authorize_uri をカラムに格納するなどしておけば良さそうです。また、サンプルコード内にある通り、以下の source > references > payment_code がそれっぽいです。

```
  "source": {
    "object": "source",
    "id": "src_hogehogefugafuga",
    "references": {
      "payment_code": "12345678",
      "expires_at": "yyyy-mm-ddT23:59:59Z"
    },
```

### Q： ドキュメント内に「お客様がメールアドレスと電話番号を入力すると、Omiseからリンクが送付されます。 リンク先のページでコンビニエンスストアの選択などを行うことができます。」とありますが、ユーザがメールアドレスと電話番号を入力するのは一体どこ？
#### A： …… Omise.js を対応させるようにします(2018/05/11時点回答)
しばらくお待ちくださいとのことです。


### Q： ドキュメント内に「Convini payment （コンビニ決済） を選択すると、コンビニエンスストアや上記の他の方法で支払いを行うことができます。」とありますが、 Convini payment という値を指定する箇所は一体どこでしょうか。
#### A： Convini payment という値は実際には存在しません……。

以下に記述している Source API の type: econtext というのが、コンビニ決済の意です（であればドキュメント内に不用意に用語を増やして混乱を招かないようにすべきですね……）



### Q： JSON Response の各項の意味を教えてください。見た目で分かるものは良いのですが、いくつか、分からないものがあり、かつ、解説がドキュメントに記載ありません。

* Source API において
    * type： econtext 以外に取りうる値があるのかどうか
    * flow： ？

* Charge API において
    * disputable： ？
    * capturable： ？
    * reversible： ？
    * refundable： ？
    * それ以外は [Chrage Api のドキュメント](https://www.omise.co/ja/charges-api) を参照　

#### A： 以下の通りです。

* Source API において
    * type： 今後、コンビニ以外の決済手段が増えた際には econtext 以外の値を取りうることになる
    * flow： ？

* Charge API において
    * disputable： ？
    * capturable： ？
    * reversible： ？
    * refundable： ？
    * それ以外は [Chrage Api のドキュメント](https://www.omise.co/ja/charges-api) を参照

結局、回答を得られていないままです。引き続き回答を待っていますので、後日更新予定です。


# 終わりに
何か自分がすごい Omise の回し者になったような感があるのですが、特にそんなことはないです……