決済 API
共通情報
決済APIの共通情報です。決済APIは、決済サービス『Zaif Payment』を導入するために使用します。
事前準備
決済APIの利用には事業者用アカウントおよびAPI Keyが必要になります。
アカウント情報 のページからAPI Keyの発行をおこなってください。
リクエスト方法
エンドポイント：https://api.zaif.jp/ecapi
メソッド：POST
認証
取得したAPI Keysを利用して、下記のようにHTTPヘッダを設定し、認証情報を送信します。
パラメータ |
詳細 |
例 |
|---|---|---|
key |
APIキー |
490f983a-5fab-49b2-b789-9d1f130874d3 |
md5secret |
Secret Keyをmd5ハッシュ化した文字列 |
|
sha1secret |
Secret Keyをsha1ハッシュ化した文字列 |
注釈
"md5secret"と"Secret Key"はどちらかをセット
パラメータ
キー |
詳細 |
例 |
|---|---|---|
nonce |
1以上の数 |
23123 |
method |
APIメソッド名 |
get_info |
注釈
メソッド毎の固有のパラメータも全てPOSTパラメータにて送信してください。 nonceパラメータの値は実効毎に増分されていないとエラーが発生します。また、増分量は少数点以下の値にも対応しております。 ミリ秒まで含むunixtimeを使うと比較的簡単にAPIを呼び出すことができますが、多重送信の防止と呼び出し順序にnonceパラメータを使用して呼び出しの管理をすることを検討してください。
戻り値
キー |
詳細 |
型 |
|---|---|---|
success |
成功フラグ |
int |
return |
実行結果 |
dict or string |
{
"success": 1,
"return": {
...
}
}
エラーメッセージ
メッセージ |
詳細 |
|---|---|
nonce not incremented |
前回API実行時よりnonce値が加算されていません。 |
account has not permission to use ec api |
アカウントが決済APIを使用する権限がありません。 |
invalid parameter {} |
パラメータ{}が不正です。 |
補足
戻り値
処理に成功した場合、successには1が、returnには実行結果が設定されます。 処理に失敗した場合、successには0が、returnにはエラーメッセージが設定されます。
インボイスの表示
作成したインボイスから支払フォームを表示することにより、利用者から暗号資産による支払いを促します。 支払いフォームのURLは以下の通りです。
https://zaif.jp/invoice/form/{invoiceId}
{invoiceId}はインボイスの作成時に発行されたIDになります。 下記のようにしてiframeによる表示を行うことも可能です。
https://zaif.jp/invoice/iframe/{invoiceId}
<iframe id="zaif_ec_iframe"
scrolling="no"
allowtransparency="true"
frameborder="0" src='https://zaif.jp/invoice/iframe/{invoiceId}'
style='width:500px; overflow: hidden; padding:10px;'></iframe>
また、インボイス作成時に取得したデータを利用し、事業者様のECサイト上で独自にフォームを表示していただくことも可能です。
個別情報
決済APIの個別情報です。
インボイスの作成
決済金額・商品名・通貨などの情報を送信してインボイスを作成し、暗号通貨による決済を開始します。 インボイスを作成すると、決済用のBitcoinアドレスが発行され、暗号通貨建ての請求が行なわれます。 インボイスには有効期限（現在３０分としていますが、これは変更になる可能性があります）があり、有効期限内に顧客が決済用のアドレスへ支払を行うことにより、決済が完了します。
パラメータ
パラメータ |
必須 |
詳細 |
型 |
例 |
|---|---|---|---|---|
method |
Yes |
createInvoice |
str |
|
speed |
No |
（廃止済み）決済完了とみなすスピード。 |
str |
high medium low |
notificationUri |
No |
決済完了したタイミングでの通知先URI 事業者様のECサイトシステムに通知を行うためのものになります。 |
str |
|
notificationMethod |
No |
決済完了したタイミングでの通知先URIへ通知する際に使用されるHTTPメソッド。デフォルトはPOSTになります。 |
str |
GET または POST |
webhookUrl |
No |
決済の状態が変化したタイミングでwebhook通知を送信する先のURL。事業者様のECサイトシステムに通知を行うためのものになります。 |
str |
|
redirectUri |
No |
決済フォームで着金後、ECサイトへ戻るためのリダイレクト先のURI。設定されなかった場合はリダイレクトせず着金後のステータスが表示されます。 |
str |
|
currency |
Yes |
決済に使用する暗号通貨 |
str |
btc または SKEB |
amount |
Yes |
決済金額（日本円）。実際の請求対象金額。1円単位、カンマ無し。 |
int |
|
subTotal |
No |
小計（日本円） |
int |
|
tax |
No |
消費税（日本円） |
int |
|
regularPrice |
No |
定価（日本円） |
int |
|
discount |
No |
割引額（日本円） |
int |
|
merchantName |
No |
店舗名 |
str |
|
orderNumber |
No |
注文番号。店舗側での識別用に任意の番号やコードを利用することができます。 |
str |
|
referenceNumber |
No |
リファレンス番号。店舗側での識別用に任意の番号やコードを利用することができます。 |
str |
|
itemName |
No |
商品名 |
str |
|
buyerId |
No |
利用者ID |
str |
|
buyerName |
No |
利用者名 |
str |
|
buyerKana |
No |
利用者ふりがな |
str |
|
buyerZip |
No |
利用者郵便番号 |
str |
|
buyerAddr1 |
No |
利用者住所１ |
str |
|
buyerAddr2 |
No |
利用者住所２ |
str |
|
buyerAddr3 |
No |
利用者住所３ |
str |
|
buyerPhone |
No |
利用者電話番号 |
str |
|
buyerCellphone |
No |
利用者携帯番号 |
str |
|
buyerEmail |
No |
利用者メールアドレス |
str |
注釈
speed（決済スピード）について
speedパラメーターについては2022年の再開以降無効となり、high/mediaum/lowどのパラメーターを指定しても共通で下記のような状態推移となります。
決済の有効期限はインボイスの作成から10分間となり、支払トランザクションが暗号資産ネットワーク上に検知された状態（未承認の状態）でstatusがpaid(支払い開始)と見なされます、その後、暗号資産ネットワーク上で1承認された時点でstatusがconfirmed（確認済み）となり、暗号資産毎の必要承認数（BTCで3など）を経過した時点でstatusはcomplete（完了）となります。
有効期限内に着金した場合、有効期限の10分以内に1承認とならなくても直ちに有効期限切れにはなりませんが、1時間以内（有効期限切れ後50分以内）に1承認とならない場合は有効期限切れとなります。
注釈
利用者の氏名・住所などについて
利用者の氏名・住所・電話番号などのフィールドについては、送信していただくと決済フォームに表示されます。ただし、利用者IDについては表示されません。
決済フォームはインボイスIDがもれない限りアクセスすることができませんが、インターネット上ではアクセス制限なしに公開される状態になりますので、個人情報保護の観点から、必要でない場合（注文番号などから顧客が関連付けできる場合）は顧客の情報を送信されないことをお勧めします。
戻り値
キー |
詳細 |
型 |
|---|---|---|
invoiceId |
作成したインボイスを識別するためのID |
str |
invoiceUri |
作成したインボイスに対する支払フォームのURI |
str |
invoiceIframeUri |
作成したインボイスに対するiframe版支払フォームのURI |
str |
created |
インボイス作成日時 |
int |
expired |
インボイスの有効期限 |
int |
amount |
決済対象金額（送信された金額） |
int |
currency |
決済対象の暗号通貨 |
str |
rate |
決済時の換算レート |
int |
btc |
Bitcoinによる請求額（bitcoinによる決済時のみ） |
str |
SKEB |
Skebcoinによる請求額。(skebcoinによる決済時のみ) |
str |
address |
Bitcoinの決済用支払先アドレス |
str |
BIP21 |
bitcoinの支払いURI |
str |
EIP681 |
SKEBでの支払いに利用可能なEIP681形式のURIです。currencyが SKEBの場合に返却されます。 |
str |
speed |
決済スピード（送信されたものまたはデフォルトで適用されたもの) |
str |
orderNumber |
送信された注文番号（送信された場合のみ） |
str |
referenceNumber |
送信されたリファレンス番号（送信された場合のみ） |
str |
buyerId |
送信された利用者ID（送信された場合のみ） |
str |
webhookUrl |
請求書作成時に指定されたwebhook通知先のURL。指定されなかった 場合は返却されません。 |
str |
{
"success": 1,
"return": {
"invoiceId": "d7dd735c-1650-11e5-b412-4437e6999eec",
"invoiceUri": "https://zaif.jp/invoice/form/d7dd735c-1650-11e5-b412-4437e6999eec",
"invoiceIframeUri": "https://zaif.jp/invoice/iframe/d7dd735c-1650-11e5-b412-4437e6999eec",
"created": 1434696690,
"expired": 1434698490,
"amount": 10800,
"currency": "btc",
"rate": "30012",
"btc": "0.359856",
"address": "19yhwoY8ysDNy1J1JBZf6nRBsUfLTe2Lvb",
"BIP21": "bitcoin:19yhwoY8ysDNy1J1JBZf6nRBsUfLTe2Lvb?amount=0.359856",
"speed": "high",
"orderNumber": "<the order number if you sent>"
}
}
注釈
webhookUrlについて
webhookUrlで指定されたURLに対しHTTP(S)によるPOSTを行い、決済情報を通知します。 POSTデータの内容はgetInvoiceで取得できるものと同様のデータをJSON形式にしたものとなります。
事業者様のECサイトシステム側で決済状況の確認をリアルタイムに行うためにはwebhookUrlのご利用を推奨します。 webhookによる通知は、ご請求に対し「着金があったとき」「入金開始となったとき」「入金完了となったとき」「有効期限切れとなったとき」「有効期限切れ後の過入金があったとき」など、決済の状態が変化する度に通知が送信されます。 また、webhookによる通知は、受け取り側がHTTPステータスコード200を返すまで（間隔を明けて）再送されますので、通知漏れも起こらないようになっています。
これに対しnotificationUriへの通知は決済完了時に1回しか行わず、ステータスコードにかかわらず1回しか送信されません。
注釈
決済完了通知(notificationUri)について
notificationUriを設定した場合、決済完了となったタイミングで決済完了の通知がHTTP(S)で送信されます。
キー |
詳細 |
型 |
|---|---|---|
invoiceId |
作成したインボイスを識別するためのID |
str |
settled |
決済完了日時 |
UNIX_TIMESTAMP |
settledFormat |
決済完了日時 |
TIMESTAMP |
amount |
決済対象金額（送信された金額） |
int |
btc |
Bitcoinによる請求額（bitcoinによる決済時のみ） |
int |
例）SKEB |
請求額 |
str |
crypto_amount |
請求額 |
str |
orderNumber |
送信された注文番号（送信された場合のみ） |
str |
referenceNumber |
送信されたリファレンス番号（送信された場合のみ） |
str |
buyerId |
送信された利用者ID（送信された場合のみ） |
str |
警告
notificationMethodにGETを設定した場合は、パラメータは送信されません。 notificationMethodにGETを設定する場合、notificationUriに注文を識別できるような工夫をして設定してください。
通知のエラー時の対応について notificationUriに対するエラー時の再送は行っておりません。webhookUrlによる通知の受け取りをご検討ください。
注釈
決済完了時のリダイレクト(redirectUri)について
顧客がzaif上の決済フォームを表示したまま送金（支払い）したとき、暗号通貨ネットワーク上で着金を確認したタイミングで自動的にリダイレクトされます。 redirectUriを設定してない場合はリダイレクトされず、こちらのフォームが表示されたままになります。その際、入金ステータスは自動的に更新されます。
インボイス情報の取得
作成したインボイスの情報を得ることができます。
パラメータ
パラメータ |
必須 |
詳細 |
型 |
例 |
|---|---|---|---|---|
method |
Yes |
getInvoice |
str |
|
invoiceId |
Yes |
発行されたinvoiceId |
str |
戻り値
キー |
詳細 |
型 |
|---|---|---|
invoiceId |
作成したインボイスを識別するためのID |
str |
created |
インボイス作成日時 |
int |
expired |
インボイスの有効期限 |
int |
status |
インボイスの状態 |
str |
settled |
決済完了日時 |
int |
amount |
決済対象金額（送信された金額） |
int |
currency |
決済対象の暗号通貨 |
str |
rate |
決済時の換算レート |
int |
received |
暗号資産の受取金額 |
str |
overpaid |
暗号資産の過入金額 |
str |
btc |
Bitcoinによる請求額（bitcoinによる決済時のみ） |
str |
mona |
Monacoinによる請求額（monacoinによる決済時のみ） |
str |
SKEB |
Skebcoinによる請求額（Skebcoinによる決済時のみ） |
str |
address |
BitcoinまたMonacoinの決済用支払先アドレス |
str |
BIP21 |
bitcoinまたはmonacoinの支払いURI |
str |
EIP681 |
SKEBでの支払いに利用可能なEIP681形式のURIです。currencyが SKEBの場合に返却されます。 |
str |
speed |
決済スピード（送信されたものまたはデフォルトで適用されたもの) |
str |
orderNumber |
送信された注文番号（送信された場合のみ） |
str |
referenceNumber |
送信されたリファレンス番号（送信された場合のみ） |
str |
インボイスの状態(status)
インボイスには下記のような「状態」があります。
new : 作成され、請求が開始された状態。
paid : 支払先アドレスに対して支払いが行なわれ、着金開始した状態。
confirmed : 支払先アドレスに対する支払いが暗号通貨ネットワーク上で1承認以上確認された状態。
complete : 支払先アドレスに対する支払いが暗号通貨ネットワーク上で3承認以上確認された状態。このタイミングで決済完了となります。また、3承認はBTCの場合で、暗号資産の種別によって必要承認数は違う値になります。
expired : 支払先アドレスに対して支払いが行なわれず、有効期限が切れた状態。
invalid : 支払先アドレスに対して支払いが開始されたが、1承認までに時間がかかりすぎてしまった場合や、額が不足した状態で有効期限が切れた状態。または有効期限切れ後に支払いされた場合。
canceled : 作成者によりキャンセルされた状態。
インボイスの状態と他に、決済完了とみなすかどうかについては、インボイス作成時に設定されたspeedに従って下記の項目が対応します。
settled: 決済完了日時（unixtime）、決済を完了とみなしたタイミング（statusがcompleteになったタイミング）でセットされます。
インボイスの検索
注文番号でインボイスを検索し、インボイスIDを返します。 インボイスの詳細については インボイス情報の取得メソッド を使用してください。
パラメータ
パラメータ |
必須 |
詳細 |
型 |
例 |
|---|---|---|---|---|
method |
Yes |
getInvoiceIdsByOrderNumber |
str |
|
orderNumber |
Yes |
注文番号 |
str |
戻り値
キー |
詳細 |
型 |
|---|---|---|
invoiceIds |
検索結果 |
dict |
counts |
検索結果の件数 |
int |
インボイスのキャンセル
作成したインボイスを取消します。 支払が完了していたり既に有効期限が切れている場合はエラーとなります。 部分的に入金されていた場合は、過払いとして処理されます。
パラメータ
パラメータ |
必須 |
詳細 |
型 |
例 |
|---|---|---|---|---|
method |
Yes |
cancelInvoice |
str |
|
invoiceId |
Yes |
キャンセルしたいinvoiceId |
str |
戻り値
キー |
詳細 |
型 |
|---|---|---|
invoiceId |
作成したインボイスを識別するためのID |
str |
created |
インボイス作成日時 |
int |
expired |
インボイスの有効期限 |
int |
status |
インボイスの状態 |
str |
settled |
決済完了日時 |
int |
amount |
決済対象金額（送信された金額） |
int |
currency |
決済対象の暗号通貨 |
str |
rate |
決済時の換算レート |
int |
overpaid |
暗号資産の過入金額 |
str |
btc |
Bitcoinによる請求額（bitcoinによる決済時のみ） |
str |
SKEB |
Skebcoinによる請求額（Skebcoinによる決済時のみ） |
str |
address |
BitcoinまたはSkebcoin決済用支払先アドレス |
str |
BIP21 |
bitcoinの支払いURI |
str |
EIP681 |
SKEBでの支払いに利用可能なEIP681形式のURIです。currencyが SKEBの場合に返却されます。 |
str |
speed |
決済スピード（送信されたものまたはデフォルトで適用されたもの) |
str |
orderNumber |
送信された注文番号（送信された場合のみ） |
str |
referenceNumber |
送信されたリファレンス番号（送信された場合のみ） |
str |
注釈
キャンセル失敗時はエラーが帰るため、成功時のstatusは常に'canceled'となります。