決済 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パラメータの値は実効毎に増分されていないとエラーが発生します。また、増分量は少数点以下の値にも対応しております。

戻り値

キー 詳細
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にはエラーメッセージが設定されます。

インボイスの表示

作成したインボイスから支払フォームを表示することにより、利用者からBitcoin/Monacoinによる支払いを促します。 支払いフォームのURLは以下の通りです。

https://zaif.jp/invoice/form/{invoiceId}

{invoiceId}はインボイスの作成時に発行されたIDになります。 下記のようにしてiframeによる表示を行うことも可能です。

<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またはMonacoinアドレスが発行され、暗号通貨建ての請求が行なわれます。 インボイスには有効期限(現在30分としていますが、これは変更になる可能性があります)があり、有効期限内に顧客が決済用のアドレスへ支払を行うことにより、決済が完了します。

パラメータ

パラメータ 必須 詳細
method Yes createInvoice str  
speed No 決済完了とみなすスピード。 str high medium low
notificationUri No 決済完了したタイミングでの通知先URI 事業者様のECサイトシステムに通知を行うためのものになります。 str  
notificationMethod No 決済完了したタイミングでの通知先URIへ通知する際に使用されるHTTPメソッド。デフォルトはPOSTになります。 str GET または POST
redirectUri No 決済フォームで着金後、ECサイトへ戻るためのリダイレクト先のURI。設定されなかった場合はリダイレクトせず着金後のステータスが表示されます。 str  
currency Yes 決済に使用する暗号通貨 str btc または mona
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 利用者住所1 str  
buyerAddr2 No 利用者住所2 str  
buyerAddr3 No 利用者住所3 str  
buyerPhone No 利用者電話番号 str  
buyerCellphone No 利用者携帯番号 str  
buyerEmail No 利用者メールアドレス str  

注釈

speed(決済スピード)について

highとすると、暗号通貨ネットワーク上での送金トランザクションについて、確認前の状態でも、着金次第決済完了とみなします。 mediumとすると、1件以上の確認が入ったタイミングで決済完了とみなします。これはbitcoinで平均10分、monacoinで平均2分程度になります。 lowとすると、6件以上の確認が入ったタイミングで決済完了とみなします。これはbitcoinで平均1時間、monacoinで平均12分程度になります。 highとすると顧客側の送金が完了したタイミングとほぼ同時に着金し、決済完了とみなされますが、万一このトランザクションがネットワーク上で認証されなかった場合、決済が後から取り消しされる場合があります。

注釈

利用者の氏名・住所などについて

利用者の氏名・住所・電話番号などのフィールドについては、送信していただくと決済フォームに表示されます。ただし、利用者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による決済時のみ) int
mona Monacoinによる請求額(monacoinによる決済時のみ) int
address BitcoinまたMonacoinの決済用支払先アドレス str
speed 決済スピード(送信されたものまたはデフォルトで適用されたもの) str
orderNumber 送信された注文番号(送信された場合のみ) str
referenceNumber 送信されたリファレンス番号(送信された場合のみ) str
buyerId 送信された利用者ID(送信された場合のみ) 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>"
    }
}

注釈

決済完了通知(notificationUri)について

notificationUriを設定した場合、speedで設定した状態となったタイミングで、決済完了の通知がHTTP(S)で送信されます。

キー 詳細
invoiceId 作成したインボイスを識別するためのID str
settled 決済完了日時 int
amount 決済対象金額(送信された金額) int
btc Bitcoinによる請求額(bitcoinによる決済時のみ) int
mona Monacoinによる請求額(monacoinによる決済時のみ) int
orderNumber 送信された注文番号(送信された場合のみ) str
referenceNumbe 送信されたリファレンス番号(送信された場合のみ) str
buyerId 送信された利用者ID(送信された場合のみ) str

警告

notificationMethodにGETを設定した場合は、パラメータは送信されません。 notificationMethodにGETを設定する場合、notificationUriに注文を識別できるような工夫をして設定してください。

通知のエラー時の対応について エラー時の再送については準備中です。

注釈

決済完了時のリダイレクト(redirectUri)について

顧客がzaif上の決済フォームを表示したまま送金(支払い)したとき、暗号通貨ネットワーク上で着金を確認したタイミングで自動的にリダイレクトされます。 redirectUriを設定してない場合はリダイレクトされず、こちらのフォームが表示されたままになります。その際、入金ステータスは自動的に更新されます。

注釈

Bitcoin建てまたはMonacoin建ての決済

  • 円建てではなく、Bitcoin建てまたはMonacoin建てでの決済を行うことができます。 createInvoiceのbillingCurrencyパラメータ(一覧にはないパラメータです)に"btc"または"mona"を指定して下さい。このときcurrencyパラメータも同じ暗号通貨を指定する必要があります。
  • 戻り値からrateは削除されることに注意してください。
  • BTCまたはMONAがそのまま決済事業者様のアカウントに精算されますので、決済手数料は完全にゼロ%になりますが、円換算を行う際の相場の変動リスクはそのまま決済事業者様が担うことになりますことにご注意ください。

インボイス情報の取得

作成したインボイスの情報を得ることができます。

パラメータ

パラメータ 必須 詳細
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
btc Bitcoinによる請求額(bitcoinによる決済時のみ) int
mona Monacoinによる請求額(monacoinによる決済時のみ) int
address BitcoinまたMonacoinの決済用支払先アドレス str
BIP21 bitcoinまたはmonacoinの支払いURI str
speed 決済スピード(送信されたものまたはデフォルトで適用されたもの) str
orderNumber 送信された注文番号(送信された場合のみ) str
  • インボイスの状態(status)

    • インボイスには下記のような「状態」があります。

      1. new : 作成され、請求が開始された状態。

      2. paid : 支払先アドレスに対して入金が行なわれ、着金した状態(speed=highの場合の決済完了タイミング)。

      3. confirmed : 支払先アドレスに対する入金が暗号通貨ネットワーク上で1確認以上された状態(speed=mediumの場合の決済完了タイミング)。

      4. complete : 支払先アドレスに対する入金が暗号通貨ネットワーク上で6確認以上された状態(speed=lowの場合の決済完了タイミング)。

      5. expired : 支払先アドレスに対して入金が行なわれず、有効期限が切れた状態。

      6. invalid : 支払先アドレスに対して入金が開始されたが、なんらかの理由で確認されなかった状態や、入金金額が不足した状態で有効期限が切れた状態。

      7. canceled : 作成者によりキャンセルされた状態。

        インボイスの状態と他に、決済完了とみなすかどうかについては、インボイス作成時に設定されたspeedに従って下記の項目が対応します。

      8. settled: 決済完了日時(unixtime)、speedに応じて決済を完了とみなしたタイミングでセットされます。


インボイスの検索

注文番号でインボイスを検索し、インボイス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
btc Bitcoinによる請求額(bitcoinによる決済時のみ) int
mona Monacoinによる請求額(monacoinによる決済時のみ) int
address BitcoinまたMonacoinの決済用支払先アドレス str
BIP21 bitcoinまたはmonacoinの支払いURI str
speed 決済スピード(送信されたものまたはデフォルトで適用されたもの) str
orderNumber 送信された注文番号(送信された場合のみ) str

注釈

キャンセル失敗時はエラーが帰るため、成功時のstatusは常に'canceled'となります。