支払い用ボタンの生成 - ビットコイン決済APIドキュメント
リクエスト先
POST https://coincheck.com/api/ec/buttons
作成されたボタンの例
ビットコインで支払う
支払い用ボタンの使い方
coincheck paymentでのビットコイン決済は、全てこのボタンを通じて行われます。このボタンは一般的に、支払い方法を選び、注文の確認、そして購入確定ボタンを押した次のページに設置されます。
ボタンを設置するには、サーバー側でこのAPIに対し、注文の合計金額（日本円）とコールバックURL等の情報を送信し、ボタンのHTMLタグ button[html_tag] を受け取ります（認証が必要です）。そのHTMLタグを含んだページを生成し、購入者に表示をします。
購入者がボタンをクリックすると、2種類の支払い方法が提示されます。
1つ目は通常のビットコインのトランザクションを使って支払いをする方法です。購入者は送付先のビットコインのアドレス、ビットコインの量が示されます。そのアドレスに指定されたビットコインを送付し、{{minConfirmation}} confirmation に達することで決済が完了します。1 confirmation に対して約10分が必要であるため、約30分後に完了します。
2つ目はcoincheckのウォレットを使って支払いをする方法です。購入者が coincheck のアカウントを持っており、ビットコインを指定された量より所有している場合利用できます。coincheck内でのビットコインの受け渡しとなるため、{{minConfirmation}} confirmation を待たずとも、約1分で決済完了状態になります。
システムイメージ図
システムイメージ図
① 支払い用ボタンのAPIを使い、注文の合計金額等を送信（リクエスト）
② ボタンに関するレスポンスを返答
③ button[html_tag] をページに埋め込み、ユーザーにボタンを表示
④ ユーザーがビットコインを送金
⑤ 送金されたビットコインを取得し、正しく送金されているか確認
⑥ ①で指定されたURLへコールバックをPOST
リクエストサンプル
# Request
POST https://coincheck.com/api/ec/buttons
{
"button": {
"name": "注文 #123",
"currency": "JPY",
"display_currency": "JPY",
"amount" : 5000,
"callback_url": "http://www.example.com/coincheck/callback",
"success_url": "http://www.example.com/order/complete",
"max_times": 1,
"include_name": true,
"include_email": true,
"include_address": false,
"custom": "123",
"notify_mispayment": true
}
}
# Response
{
"success": true,
"button": {
"name": "注文 #123",
"currency": "JPY",
"display_currency": "JPY",
"amount" : 5000,
"callback_url": "http://www.example.com/coincheck/callback",
"success_url": "http://www.example.com/order/complete",
"max_times": 1,
"html_tag": "<script>...</script><a src="...">...</a>",
"url": "https://coincheck.com/checkouts/...",
"include_name": true,
"include_email": true,
"include_address": false,
"custom": "123",
"notify_mispayment": true
}
}
リクエストパラメーター
| 項目 |
説明 |
button
必須 |
作成するボタンに関する情報のハッシュです。 |
button[name]
必須 |
販売する商品の名前です。ショッピングカートのような機能を持たず、単品の商品を販売する場合は商品の名前を入れます。カートがあり、複数個の商品を1回の決済で購入する場合は、「注文 #[注文番号]」と設定すると販売履歴で確認する際に便利です。 |
button[currency]
必須 |
決済する商品の価格の通貨を設定します。現在は JPY のみ対応しています。 |
button[amount]
必須 |
決済する商品の価格を設定します。5000円の商品でしたら、 button[amount] に 5000 、 button[currency] に JPY を設定します。 |
button[display_currency]
任意 |
支払いのページで表示する価格の通貨を設定します。JPYとUSDに対応しています。デフォルトはJPYです。 |
button[callback_url]
任意 |
ビットコイン受け取り時、承認済みになったときにPOSTする先のURLを指定します。詳しくはコールバックを参照下さい。 |
button[success_url]
任意 |
消費者がビットコインの支払いをした際に、指定されたURLへのリンクを表示します。一般的に「購入完了しました」という旨のページを指定します。指定されなかった場合は、リンク自体を表示しません。 |
button[max_times]
任意 |
このボタンが最大何回の支払いの受付に対応するか指定します。デフォルトは 0 で、その場合は回数制限無しとなります。ショッピングカートでの決済で使う場合は、他のユーザーからの支払いを受け付けることはないため 1 を指定します。 1 を指定すると、誰かが支払った時点でそのボタンは使えなくなります。ブログ等で多くのユーザーに同じボタンで商品を販売したい場合は 0 を指定します。
これは分割払いのオプションではありません。 |
button[description]
任意 |
購入時に表示される商品の説明を登録できます。 |
button[include_name]
任意 |
購入時に名前の入力を必要とするか設定できます。 true ならば名前の入力が必須となります。デフォルトは false です。 |
button[include_email]
任意 |
購入時にメールアドレスの入力を必要とするか設定できます。 true ならばメールアドレスの入力が必須となります。デフォルトは false です。 |
button[include_address]
任意 |
購入時に住所の入力を必要とするか設定できます。 true ならば住所の入力が必須となります。デフォルトは false です。 |
button[include_phone_number]
任意 |
購入時に電話番号の入力を必要とするか設定できます。 true ならば電話番号の入力が必須となります。デフォルトは false です。 |
button[include_notes]
任意 |
購入時に備考欄の入力フォームを表示させるか設定できます。 true ならば備考欄の入力フォームが表示されます。備考欄の入力は必須ではありません。デフォルトは false です。 |
button[custom]
任意 |
自由な値を設定できます。コールバックでこの値を返します。注文番号や顧客番号、製品番号等を入力し、コールバックで判別するのに使います。 |
button[notify_mispayment]
任意 |
支払いミスが発生した際に指定したコールバックURLにPOSTします。デフォルトは false です。 |
レスポンス
レスポンスはJSONで返します。
| 項目 |
説明 |
| success |
正常に認証、パラメータが指定されていた場合は true 。そうでない場合は false 。 |
| button |
作成されたボタンに関する情報のハッシュです。 |
| button[name] |
リクエストで指定したものです。 |
| button[currency] |
リクエストで指定したものです。 |
| button[amount] |
リクエストで指定したものです。 |
| button[callback_url] |
リクエストで指定したものです。 |
| button[success_url] |
リクエストで指定したものです。 |
| button[max_times] |
リクエストで指定したものです。 |
| button[description] |
リクエストで指定したものです。 |
| button[include_name] |
リクエストで指定したものです。 |
| button[include_email] |
リクエストで指定したものです。 |
| button[include_address] |
リクエストで指定したものです。 |
| button[include_phone_number] |
リクエストで指定したものです。 |
| button[include_notes] |
リクエストで指定したものです。 |
| button[custom] |
リクエストで指定したものです。 |
| button[notify_mispayment] |
リクエストで指定したものです。 |
| button[html_tag] |
ボタンを表示するためのHTMLタグです。これをページを組み込むことにより、消費者がビットコインで支払うことが可能になります。 |
| button[url] |
決済に利用できるURLです。こちらのURLにアクセスすれば決済を行うことができます。 html_tag のタグ情報の中に、このURLが含まれているため、どちらか一方を利用することが一般的です。 |
コールバック
コールバックURLは購入者がビットコインの送付をしたとき、承認済みの状態になったときに呼ばれます。ビットコインの送付をしたときは未承認（unconfirmed）な状態であるため、基本的には決済完了状態にしない方が良いでしょう。その後、承認状態になるともう一度コールバックURLにPOSTします。その際に、決済完了状態にし発送処理などを進めると良いです。
承認の条件は、アドレスを使って支払いをした場合は、 {{minConfirmation}} confirmation になることです。coincheckのウォレットを使い支払った場合は、即時に承認されます。
また、コールバック先URLには、注文番号などを設定しておくことで、コールバックが呼ばれた時にスムーズに注文状況を更新できます。
（例）コールバックURL : https://www.example.com/coincheck/callback?order_id=123
コールバックの内容
コールバックは指定されたURLにHTTP(HTTPS) POSTでリクエストされます。
{
"order": {
"id": "ABC123abc",
"button_name": "注文 #15",
"total_native": {
"amount": 1080,
"currency": "JPY"
},
"total_btc": {
"amount": 0.1,
"currency": "BTC"
},
"created_at": "2014-09-03 09:50:01 UTC",
"confirmed_at": "2014-09-03 10:20:01 UTC",
"status": "received",
"custom": "15",
"customer": {
"name": "和田 晃一良",
"email": "test@gmail.jp",
"address": "東京都渋谷区東4-4-6"
}
}
}
| 項目 |
説明 |
| order |
ユーザーが支払った注文情報のハッシュです。 |
| order[id] |
coincheck paymentで管理される一意な注文番号です。販売履歴で詳細を確認できます。 |
| order[button_name] |
ボタンを作るリクエストで指定した button[name] です。 |
| order[total_native] |
支払い用ボタンを作るリクエストで指定した、価格、通貨に関する情報を含んだハッシュです。 |
| order[total_native][amount] |
支払い用ボタンを作るリクエストで指定した価格です。 |
| order[total_native][currency] |
支払い用ボタンを作るリクエストで指定した通貨です。日本円で作成した場合は JPY であり、ビットコインで作成した場合は BTC です。 |
| order[total_btc] |
商品の価格をビットコインでのレートに換算した情報を含むハッシュです。 |
| order[total_btc][amount] |
ビットコインに換算された価格です。 |
| order[total_btc][currency] |
常に BTC です。 |
| order[created_at] |
購入者が支払った時間です。 |
| order[confirmed_at] |
ビットコインの送金が承認された時間です。承認がされていない場合は nil が入ります。 |
| order[status] |
注文の状況です。received , confirmed , invalid_payment の3種類があります。
received はビットコインを送付した瞬間で、まだ承認されていません。
confirmed はビットコインの送付が承認済みになった状態で、 receiveの後に呼ばれます。
invalid_payment は ビットコインを受け取った( receive )のち、1週間たっても送付が承認されなかった場合に呼ばれます。この場合は支払いは無効となります。
|
| order[custom] |
ボタン生成時に指定した、 button[custom] が入ります。 |
| order[customer] |
注文をした顧客に関する情報のハッシュです。 |
| order[customer][name] |
注文した顧客の名前です。ボタン生成時に button[include_name] を true にした場合のみ情報が入ります。 |
| order[customer][email] |
注文した顧客のメールアドレスです。ボタン生成時に button[include_email] を true にした場合のみ情報が入ります。 |
| order[customer][address] |
注文した顧客の住所です。ボタン生成時に button[include_address] を true にした場合のみ情報が入ります。 |
コールバックの署名
コールバックにはcoincheckから送信されたことを保証するために署名を送信しています。
HTTP Headerとして送信しており、ヘッダー名は COINCHECK-SIGNATURE です。
署名は、"コールバックのリクエストボディ + コールバックの署名キー" のSHA256ハッシュです。
署名キーはショップ情報編集で設定でき、デフォルトでランダムな値が入力されています。
たとえばリクエストボディが hoge=true 、署名キーが foo である場合、署名は、 hoge=truefoo のSHA256ハッシュ 9894eb87846ac2f0acc1b75c644752656968ec4f3001622090b962efea3efc5c になります。
コールバックのリトライ
コールバックには、レスポンスコードとして 200 を返して下さい。
そうでないレスポンスが帰ってきた場合は、コールバックを再度送信いたします。
再度送信する場合のスケジュールは以下のとおりになります。( 4 ^ n 秒後に送信します。 )
- 初回送信
- 4秒後
- 16秒後
- 1分後
- 4分後
- 17分後
- 1時間後
- 5時間後
- 18時間後
- 3日後
決済失敗時のコールバック
決済失敗時に指定のURLに対してPOSTリクエストを送信ます。
送信されるデータの説明は以下のページによりご参照ください。
決済失敗時のコールバック
コールバックのテスト送信
coincheck paymentではテスト環境を用意しておりませんが、コールバックをテストでお送りすることができます。
以下のフォームに必要事項を入力し、送信ボタンを押して下さい。
coincheck paymentにログインした状態でのみ利用できます。
Exchange
