CardV Merchant API

#ドキュメント一覧

#環境

Sandboxは、テスト用の資金で動くCardVの独立したテスト環境です。APIキー、残高、注文、商品IDは環境ごとに別々です。

#クイックスタート

1. 申し込み：Portalでマーチャントアカウントを申し込み、メールアドレスを確認します。

2. 審査を待つ：CardVが貴社の事業内容を審査します。承認されると、M00000001 のようなMerchant IDが発行されます。

3. Sandboxを開く：Portalにサインインし、画面上部で Sandbox を選びます。テスト用の資金として1,000 USDが入っています。

4. APIキーを作成する：Portalで Integrations → API keys を開きます。キーを作成し、CardVからメールで届く確認コードを入力してキーを表示します。表示したキーはシークレット管理ツールに保存してください。

5. 残高を確認する：

   ShellCopy

   export CARDV_BASE=https://sandbox.cardv.net
   export CARDV_MERCHANT_ID=M00000001     # yours
   export CARDV_API_KEY=cvb2b_...         # from your secret store
   AUTH=(-H "X-Merchant-Id: $CARDV_MERCHANT_ID" -H "X-Api-Key: $CARDV_API_KEY")
   
   curl -sS "$CARDV_BASE/api/v1/balance" "${AUTH[@]}"

6. 商品を探す：

   ShellCopy

   curl -sS "$CARDV_BASE/api/v1/skus?search=steam&limit=20" "${AUTH[@]}"

   "availability": "available" の商品を選び、その sku_id を控えておきます。

7. 価格を確認する：

   ShellCopy

   curl -sS "$CARDV_BASE/api/v1/skus/S000001/quote?quantity=1" "${AUTH[@]}"

   merchant_price を控えておきます。これが1個あたりの購入価格です。

8. 注文する：この呼び出しには署名が必要です。認証のサンプルコードに、次のリクエスト本文を入れて送信します。

   JSONCopy

   {
     "external_order_id": "TEST-0001",
     "items": [
       {"sku_id": "S000001", "quantity": 1, "expected_unit_price": "9.2500"}
     ]
   }

   成功するとHTTP 201が返り、O-00001234 のようなCardVの注文IDが発行されます。

9. コードを受け取る：ステータスが succeeded になるまで GET/api/v1/orders/O-00001234 を呼び出します。コードは items[].deliveries[].display_fields に入っています。注文の完了はWebhookで受け取ることもできます。

10. 本番を開始する：Sandboxのチェックリストをすべて終えてから、本番に切り替えます。

上記のIDと価格は例です。実際には、貴社のカタログで返される値を使ってください。

#APIの概要

エンドポイントは7つです。パスはすべて /api/v1 から始まります。

これ以外のエンドポイントをAPIキーで呼び出すと、HTTP 403が返ります。

{"detail": "This operation is only available in the Merchant Portal."}

携帯電話のチャージ（通話料のチャージ）はAPIでは利用できません。

#ID

IDは文字列として保存し、中身を解析しないでください。詳しくは共通ルールをご覧ください。

#Merchant Portalで行う操作

• ウォレットへの入金と、残高が少なくなったときのメール通知
• 注文履歴の確認、検索、CSVの書き出し
• 注文の請求書
• ウォレットの取引履歴と照合
• Webhookの設定、送信履歴、再送
• APIキー
• IP許可リスト
• チームメンバーと権限
• 監査ログ
• 2段階認証（2FA）
• LiveとSandboxの切り替え

#互換性とサポート

レスポンスのフィールドやステータスの値は、予告なく追加されることがあります。知らないフィールドは無視してください。知らない注文ステータスは「まだ完了していない」ものとして扱ってください。エラーメッセージの文言には依存しないでください。

お問い合わせは [email protected] まで、Merchant ID、環境、注文ID、日時（UTC）、HTTPステータスを添えてご連絡ください。APIキー、署名、Webhookのシークレット、カードのコードは絶対に送らないでください。