支払いと入札

支払い/入札（Checkout/Bid）ガイド

概要

Checkout/Bid APIを使用すると、ユーザーは注文の支払管理および完了、またはオークション商品への入札を行うことができます。

APIのユースケース

注文の支払い管理と完了
オークション商品への入札

注文の支払い管理と完了

Order APIを使用すると、ユーザーはeBayメンバーおよびeBayゲストユーザー向けのチェックアウトセッションを作成・管理できます。これらのAPIメソッドを使用することで、チェックアウトセッションの作成と更新、セッションへのクーポンやアドオンの適用、注文の支払い、および注文情報の取得が可能です。

Order APIには2つのバージョンがあります：

Order API v1: eBayメンバーのチェックアウトセッションの作成と管理に使用します。「メンバーチェックアウト」とは、eBayアカウントにログインしているバイヤーが、アカウントに保存されている情報（支払い詳細や配送先など）を使用して商品を購入することを指します。このチェックアウト方法を統合するアプリケーションは、機密性の高いクレジットカードデータを適切に取り扱うために、Payment Card Industry Data Security Standards (PCI DSS)に準拠する必要があります。
Order API v2: eBayゲストチェックアウトセッションの作成と管理に使用します。「ゲストチェックアウト」とは、eBayアカウントを持っていない、またはログインしていないバイヤーが取引を行う場合を指します。商品の購入と配送に必要な情報を収集し、注文はCheckout with eBayウィジェットを通じて完了します。Checkout with eBayウィジェットの詳細については、「Checkout with eBayボタンの統合」を参照してください。

Order API v1

eBayメンバーのチェックアウトセッションを作成および管理するために使用されるOrder API v1のメソッドについて、以下で説明します：

InitiateCheckoutSessionを使用してメンバーチェックアウトセッションを作成し、カートに商品を追加します。リクエストに必要な主要なコンテナは以下の通りです：
- lineItemInputs: チェックアウトセッション中にカートに追加されるラインアイテム（商品項目）の配列。
- creditCard (オプション): バイヤーのクレジットカード情報。メンバーが登録済み以外のクレジットカードを使用する場合を除き、必須ではありません。
- shippingAddress (オプション): チェックアウトセッションに関連付けられた注文の配送先住所情報。メンバーが登録済み以外の配送先住所を使用する場合を除き、必須ではありません。
呼び出しが成功すると、チェックアウトセッションに関する情報がレスポンスで返されます。レスポンスには以下の主要なコンテナとフィールドが含まれます：
- acceptedPaymentMethods: 注文の支払いに使用できる支払い方法の配列。
- checkoutSessionId: チェックアウトセッションの一意のeBay識別子。
注意: この値は、他のチェックアウトメソッドのURIパラメータとして使用されます。現時点ではプログラムでこの値を再取得する方法がないため、必ずこの値を保存してください。
- expirationDate: チェックアウトセッションの有効期限が切れる日時（UTC形式）。
- shippingOptions: 注文で利用可能な配送オプションの配列。デフォルトでは、最初に返された配送オプションが選択されます。注文の配送オプションを変更する方法については、次のステップを参照してください。
- pricingSummary: 注文内のすべてのラインアイテムの合計コスト。
必要に応じて、updateShippingOptionを使用して、注文内の特定のラインアイテムの配送方法を変更します。このメソッドは、チェックアウトセッションの作成時に自動選択された最初の配送オプションをバイヤーが希望しない場合に使用します。ラインアイテムで利用可能なすべての配送オプション（コストと予想配送日範囲を含む）を確認するには、InitiateCheckoutSessionレスポンス内のshippingOptionsコンテナを参照してください。
placeOrderを使用して注文を確定し、支払いを行います。注文のpurchaseOrderIdも返されます。これは、次のステップで注文の詳細を取得するために必要になります。
getPurchaseOrderを使用して、購入注文の詳細を確認および取得します。このメソッドは、purchaseOrderPaymentStatusフィールドの値を確認して注文の支払いが完了したかどうかをチェックしたり、lineItemStatus列挙型を確認して商品のフルフィルメント（発送）状況をチェックしたりするために使用できます。

eBayメンバーのチェックアウトセッションを管理するために適用可能なその他のOrder API v1メソッドは以下のとおりです：

updateQuantity: チェックアウトセッション内の特定のラインアイテムの数量を変更します。
updateShippingAddress: チェックアウトセッションの注文内のすべてのラインアイテムの配送先住所を変更します。
updatePaymentInfo: 指定したチェックアウトセッションの支払い方法を変更します。
updateAddonServiceStatus: チェックアウトセッションの注文内の特定のラインアイテムに対して、真贋保証（Authenticity Guarantee）などのアドオンサービスの追加または削除を行います。
applyCoupon: 注文にクーポンを追加します。クーポンはredemptionCodeで指定し、注文ごとに1つのクーポンを適用できます。クーポンはremoveCouponを使用して注文から削除できます。
getCheckoutSession: 特定のチェックアウトセッションに関する詳細を取得します。

Order API v2

eBayゲストチェックアウトセッションを作成および管理するために使用されるOrder API v2のメソッドについて、以下で説明します：

InitiateGuestCheckoutSessionを使用してチェックアウトセッションを作成し、カートに商品を追加します。リクエストに必要な主要なコンテナは以下の通りです：
- lineItemInputs: チェックアウトセッション中にカートに追加されるラインアイテムの配列。
- shippingAddress: チェックアウトセッションに関連付けられた注文の配送先住所情報。
- contactEmail: バイヤーのメールアドレス。
呼び出しが成功すると、チェックアウトセッションに関する情報がレスポンスで返されます。レスポンスには以下の主要なコンテナとフィールドが含まれます：
- acceptedPaymentMethods: 注文の支払いに使用できる支払い方法の配列。
- checkoutSessionId: チェックアウトセッションの一意のeBay識別子。
注意: この値は、他のチェックアウトメソッドのURIパラメータとして使用されます。現時点ではプログラムでこの値を再取得する方法がないため、必ずこの値を保存してください。
- expirationDate: チェックアウトセッションの有効期限が切れる日時（UTC形式）。
- shippingOptions: 注文で利用可能な配送オプションの配列。デフォルトでは、最初に返された配送オプションが選択されます。注文の配送オプションを変更する方法については、次のステップを参照してください。
- pricingSummary: 注文内のすべてのラインアイテムの合計コスト。
重要: このメソッドを使用するとX-EBAY-SECURITY-SIGNATUREレスポンスヘッダーが返されます。このヘッダーには、Checkout with eBayウィジェットを起動するために必要なトークンが含まれます。現時点ではプログラムでこの値を再取得する方法がないため、ユーザーはこのトークンを保存しておく必要があります。
必要に応じて、updateGuestShippingOptionを使用して、注文内の特定のラインアイテムの配送方法を変更します。このメソッドは、チェックアウトセッションの作成時に自動選択された最初の配送オプションをバイヤーが希望しない場合に使用します。ラインアイテムで利用可能なすべての配送オプション（コストと予想配送日範囲を含む）を確認するには、InitiateGuestCheckoutSessionレスポンス内のshippingOptionsコンテナを参照してください。
Checkout with eBayウィジェットを使用して注文を確定し、支払いを行います。注文のpurchaseOrderIdは、Checkout with eBayウィジェットを通じて送信されるレスポンスURLに含まれて返されます。これは、次のステップで注文の詳細を取得するために必要になります。Checkout with eBayウィジェットの詳細については、「Checkout with eBayボタンの統合」を参照してください。
getGuestPurchaseOrderを使用して、購入注文の詳細を確認および取得します。このメソッドは、purchaseOrderPaymentStatusフィールドの値を確認して注文が支払われたかどうかをチェックしたり、lineItemStatus列挙型を確認して商品のフルフィルメント状況をチェックしたりするために使用できます。

eBayゲストチェックアウトセッションを管理するために適用可能なその他のOrder API v2メソッドは以下のとおりです：

updateGuestQuantity: チェックアウトセッション内の特定のラインアイテムの数量を変更します。
updateGuestShippingAddress: チェックアウトセッションの注文内のすべてのラインアイテムの配送先住所を変更します。
applyGuestCoupon: 注文にクーポンを追加します。クーポンはredemptionCodeで指定し、注文ごとに1つのクーポンを適用できます。クーポンはremoveGuestCouponを使用して注文から削除できます。
getGuestCheckoutSession: 特定のチェックアウトセッションに関する詳細を取得します。

オークション商品への入札

Offer APIを使用すると、ユーザーはバイヤーに代わって特定のオークション商品に入札し、その商品に対して支払ってもよい上限金額を設定できます。eBayはこの金額まで自動的にオファー（入札）を行い、他の入札者に上回られた場合や入札額が設定金額を超えた場合にユーザーに通知します。ユーザーはこのAPIを使用して、特定のオークションのバイヤーに固有の入札詳細を取得することもできます。

オークション商品への入札に使用されるAPIメソッドについて、以下で説明します：

オプションとして、Browse APIのsearchメソッドを使用して、バイヤーが入札したいオークション商品を検索します。例えば、オークション商品のみを検索するには、filter=buyingOptions:{AUCTION}というフィルタを使用できます。バイヤーは、返されたcurrentBidPriceコンテナを確認して、オークション商品の現在の最高入札額を知ることもできます。Browse APIを使用した商品の取得に関する詳細については、「在庫の発見と更新ガイド」を参照してください。
placeProxyBidを使用して、バイヤーが設定した上限金額まで、特定のオークション商品に対してバイヤーの代わりに代理入札（Proxy Bid）を行います。入札する商品のitem_idと、バイヤーがその商品に入札する意思のある最大金額（maxAmount）を渡す必要があります。maxAmountの値までは複数回の入札が発生する可能性があり、他のユーザーからのより高い入札によって各入札が上回られることがあります。この値は、前のステップで取得したcurrentBidPriceよりも高い必要があります。
getBiddingを使用して、特定のオークションの入札詳細を取得します。オークションがまだ進行中の場合、商品の現在の最高入札額がcurrentPriceコンテナで返されます。この金額がバイヤーの設定したmaxAmountよりも高い場合、再度placeProxyBidを呼び出して、最大入札額を引き上げてください。バイヤーの現在の代理入札額もcurrentProxyBidコンテナで返され、suggestedBidAmountsコンテナは次の入札の推奨額を返します。auctionStatusがENDEDになり、highBidderの値がtrueであれば、バイヤーがオークションに勝利したことになります。

コードサンプル

メンバーチェックアウトセッションの作成

curl -X POST "https://apix.ebay.com/buy/order/v1/checkout_session/initiate" \
-H "Authorization: Bearer OAUTH_token" \
-H "Content-Type: application/json" \
-H "X-EBAY-C-MARKETPLACE-ID: EBAY_US" \
-d '{
    "lineItemInputs": [
        {
            "quantity": 1,
            "itemId": "v1|1**********4|0"
        },
        {
            "quantity": 1,
            "itemId": "v1|1**********5|0"
        },
        {
            "quantity": 1,
            "itemId": "v1|1**********6|0"
        }
    ]
}'

オークション商品への代理入札（Proxy Bid）

curl -X POST "https://api.ebay.com/buy/offer/v1_beta/bidding/v1|2**********2|0/place_proxy_bid" \
-H "Authorization: Bearer OAUTH_token" \
-H "Content-Type: application/json" \
-H "X-EBAY-C-MARKETPLACE-ID: EBAY_US" \
-d '{
    "maxAmount": {
        "currency": "USD",
        "value": "100.00"
    }
}'

エラーハンドリング

Order APIを使用してショッピングカートに商品を追加する場合、またはOffer APIを通じて代理入札を行う場合、その商品のitemIdがX-EBAY-C-MARKETPLACE-IDヘッダーで指定されたマーケットプレイスに属していることを確認してください。商品が指定のマーケットプレイスに属していない場合、エラーが発生します。
希望数量が利用可能数量を超えているためにinitiateCheckoutSessionまたはinitiateGuestCheckoutSessionメソッドが失敗する場合は、Browse APIのgetItemメソッドを使用して出品の最新数量を確認し、リクエスト数量がこの量を超えていないことを確認してください。
placeProxyBidを通じて代理入札を行おうとした際に無効な入札エラーが発生した場合、入札が以下の基準を満たしているか確認してください：
- currency（通貨）の値が、出品マーケットプレイスで使用されている通貨と一致していること。
- 最大入札額がオークションの即決価格（Buy It Now Price）より高くないこと。必要に応じて、getItemを使用してオークション出品の即決価格（price）を確認してください。
- 最大入札額がオークションの現在の入札価格または最低入札要件を下回っていないこと。必要に応じて、getBiddingを使用してオークション商品の現在の入札価格（currentPrice）を確認してください。
- 最大入札額が初期の最大入札額よりも低くないこと。placeProxyBidメソッドを使用して最大入札額を下げることはできません。必要に応じて、getBiddingを使用してオークション商品の現在の最大入札額（maxAmount）を取得してください。

ベストプラクティス

Order API v2のゲストチェックアウトメソッドを使用する開発者は、Checkout with eBayウィジェットを統合する必要があります。このウィジェットを使用すると、ゲストはサイトを離れることなく商品の支払いができます。Checkout with eBayの実装に関する詳細については、購入統合ガイドの「Checkout with eBayボタンの統合」を参照してください。
Offer APIを通じて代理入札を行う場合、バイヤーはオークションに勝利した場合にその商品を購入することに同意したことになります。このメソッドを使用して代理で入札を行う際は、この点を必ずバイヤーに通知してください。
initiateCheckoutSessionまたはinitiateGuestCheckoutSessionメソッドは、チェックアウトセッションに対してeBayが生成したcheckoutSessionId値を返します。この値は、他のチェックアウトメソッドのURIパラメータとして使用されます。現時点ではプログラムでこの値を再取得する方法がないため、必ずこの値を保存してください。
initiateCheckoutSessionまたはinitiateGuestCheckoutSessionメソッドは、受け入れ可能な支払い方法、利用可能な配送オプション、注文に使用される配送先住所など、チェックアウトセッションに関するさまざまな情報を返します。必要に応じてこれらの情報を変更するAPIが存在するため、この情報を保存しておくこと（またはgetGuestCheckoutSessionを使用してこの情報を取得すること）を検討してください。