Zenn
💴

ZaifPaymentの決済API利用方法

2024/09/19に公開
API
決済
Zaif
Skeb
Skeb Coin
tech

Zaif Paymentとは何か

お客さんが支払った暗号通貨（BTC、MONA、SKEB）を日本円で受け取ることができるサービス。
例えばお客さんに300円払ってほしい場合、ZaifPaymentのAPIでインボイスを発行すれば300円分の暗号通貨を算出して決済用のページを作ってくれる。
2024年9月4日、ZaifPaymentにSkebCoinが追加された。

利用方法

ZaifPaymentを利用するには

  1. Zaifのアカウント
  2. ZaifPaymentの利用申請

が必要である。

https://zaif.jp/payment?lang=ja

Zaifのアカウントを作成してからZaifPaymentの利用申請をすればスムーズだ。筆者の場合は申請から2日ほどで利用可のメールが届いた。

APIキーの取得方法

  1. 上部メニューの各種サービスから開発者用APIのページに行く。Zaifの導線はわかりづらいがここだ。

  2. 2段階認証のトークンが必要になっているはずなので、入力してキーを追加できるようにする。

  3. キーの名前を決めてCreateボタンを押す。名前は適当でよい。また、決済関係のみを使用する場合権限は全て不要。

  4. アクセス可能なIPアドレスを制限できるので、必要であれば設定しておく。

  5. keyとsecretが発行される。APIの利用には両方必要。

APIの使い方

Zaifの決済用エンドポイントは1つしかなく、送信するパラメーターに応じて4つの機能が利用できるようになっている。ただし2024年9月19日現在、ドキュメントは不完全かつ嘘が書いてある。

エンドポイント

エンドポイント：https://api.zaif.jp/ecapi
メソッド：POST

必須設定

4つの機能全てで必要なヘッダー情報とパラメーター

パラメーター 説明
key APIキー
md5secret secretをMD5でハッシュ化したもの
sha1secret secretをSHA1でハッシュ化したもの

md5secretとsha1secretはどちらか片方だけでよい。
ドキュメントによるとヘッダーに設定すれば良いように読めるが、これらは必ずヘッダーとPOSTで送信するパラメーターの両方に含めなければならない。さもないとno data found for the keyという未記載のエラーが返される。

インボイスの作成

インボイス（請求）を作成し、支払用アドレスとページを作成する。
最低限必要なパラメーターはkeyとsecretを含めて6つだ。

パラメーター 説明
key APIキー
sha1secret secretをSHA1でハッシュ化したもの
nonce 1以上の数（※注意、後述）
method APIメソッド名。この機能では"createInvoice"
currency 使用通貨。"btc","mona","SKEB"のいずれか
amount 請求金額。日本円。

nonceについて

ドキュメントには

注釈
メソッド毎の固有のパラメータも全てPOSTパラメータにて送信してください。 nonceパラメータの値は実効毎に増分されていないとエラーが発生します。また、増分量は少数点以下の値にも対応しております。 ミリ秒まで含むunixtimeを使うと比較的簡単にAPIを呼び出すことができますが、多重送信の防止と呼び出し順序にnonceパラメータを使用して呼び出しの管理をすることを検討してください。

と書いてあるが不可能である。実際にはミリ秒まで含むunixtimeを受け付けず、ミリ秒のunixtimeを送信するとnonce out of rangeという未記載エラーが返却される。 通常のunixtime（10桁）なら実行できる。

コード例（Ruby）

require "http"

API_KEY = "作成したkey"
API_SECRET = "作成したsecret"
API_SECRET_SHA1 = Digest::SHA1.hexdigest(API_SECRET)

headers = {
  key: API_KEY,
  sha1secret: API_SECRET_SHA1
}

params = {
  key: API_KEY,
  sha1secret: API_SECRET_SHA1,
  nonce: Time.now.to_i,
  method: "createInvoice",
  currency: "SKEB",
  amount: 300,
}

res = HTTP.headers(headers).post("https://api.zaif.jp/ecapi", :form => params).to_s

p res

レスポンス

成功すれば送信した情報や換算レートとともに決済用アドレスとURLが返ってくる。
URLにアクセスすると下記のような画面が表示される。

インボイス情報の取得

作成したインボイスの情報を得る。
最低限必要なパラメーターはkeyとsecretを含めて5つだ。

パラメーター 説明
key APIキー
sha1secret secretをSHA1でハッシュ化したもの
nonce 1以上の数（※作成時と同様に注意）
method APIメソッド名。この機能では"getInvoice"
invoiceId 情報を取得したいインボイスのID

コード例（Ruby）

require "http"

API_KEY = "作成したkey"
API_SECRET = "作成したsecret"
API_SECRET_SHA1 = Digest::SHA1.hexdigest(API_SECRET)

headers = {
  key: API_KEY,
  sha1secret: API_SECRET_SHA1
}

params = {
  key: API_KEY,
  sha1secret: API_SECRET_SHA1,
  nonce: Time.now.to_i,
  method: "getInvoice",
  invoiceId: "情報を取得したいインボイスのID",
}

res = HTTP.headers(headers).post("https://api.zaif.jp/ecapi", :form => params).to_s

p res

レスポンス

成功すると指定したインボイスの情報が返却される。

インボイスの検索

注文番号でインボイスを検索してインボイスIDを返す。
最低限必要なパラメーターはkeyとsecretを含めて5つだ。

パラメーター 説明
key APIキー
sha1secret secretをSHA1でハッシュ化したもの
nonce 1以上の数（※作成時と同様に注意）
method APIメソッド名。この機能では"getInvoiceIdsByOrderNumber"
orderNumber 注文番号

orderNumber

インボイス作成時に設定していないと検索できないと思われる。あとから検索する可能性があれば、createInvoiceのパラメーターにorderNumberを設定しておこう。

コード例（Ruby）

require "http"

API_KEY = "作成したkey"
API_SECRET = "作成したsecret"
API_SECRET_SHA1 = Digest::SHA1.hexdigest(API_SECRET)

headers = {
  key: API_KEY,
  sha1secret: API_SECRET_SHA1
}

params = {
  key: API_KEY,
  sha1secret: API_SECRET_SHA1,
  nonce: Time.now.to_i,
  method: "getInvoiceIdsByOrderNumber",
  orderNumber: "インボイス作成時に設定した任意の注文番号"
}

res = HTTP.headers(headers).post("https://api.zaif.jp/ecapi", :form => params).to_s

p res

レスポンス

成功すると見つかったインボイスのIDが返ってくる。

インボイスのキャンセル

作成した有効期限内のインボイスを取消す。
最低限必要なパラメーターはkeyとsecretを含めて5つだ。

パラメーター 説明
key APIキー
sha1secret secretをSHA1でハッシュ化したもの
nonce 1以上の数（※作成時と同様に注意）
method APIメソッド名。この機能では"cancelInvoice"
invoiceId キャンセルしたいインボイスのID

コード例（Ruby）

require "http"

API_KEY = "作成したkey"
API_SECRET = "作成したsecret"
API_SECRET_SHA1 = Digest::SHA1.hexdigest(API_SECRET)

headers = {
  key: API_KEY,
  sha1secret: API_SECRET_SHA1
}

params = {
  key: API_KEY,
  sha1secret: API_SECRET_SHA1,
  nonce: Time.now.to_i,
  method: "cancelInvoice",
  invoiceId: "キャンセルしたいインボイスのID",
}

res = HTTP.headers(headers).post("https://api.zaif.jp/ecapi", :form => params).to_s

p res

レスポンス

成功すると取り消したインボイスの情報が返ってくる。該当するインボイスの決済ページにアクセスすると下記のように取消済みと表示される。

ZaifPaymentでSkebCoinによる支払いを受けたかった

ここからは余談だ。私は自分の運営するサービスでSkebCoinによる支払いを実装しようとしたが、今のところは様子見することにした。
注意深い方はインボイス作成時の画面でお気付きであろう。2024-09-19 20:54:54の時点で300円分のインボイスを作成すると29326.08696SKEBを要求される。この時の換算レートは0.01022980であり、ZaifのSkebCoinのレート0.1159とは乖離している。これでは、お客さんは300円を払うのに実質3398円ほどを負担しなければならないのではないだろうか？何度かインボイスの発行を試しているが、APIの換算レートがZaifの時価に近づくことはなかった。レートが安定しないと決済には使えない。なお、Zaifに問い合わせたらレート乖離は仕様と回答された。

私は表現の自由を守る決済の選択肢[1]であるSkebCoinを応援している。ぜひ頑張ってほしい。

追記、スプレッドについて

10月1日、なるがみ氏に本記事が拾われた。氏の情報によると以下とのことだ。

スプレッドは送金金額が大きいほど小さくなるそうです。

https://x.com/nalgami/status/1840991080168444229

脚注

  1. https://www.skebcoin.com/ja ↩︎

Discussion