📈

【Shopify.dev和訳】Admin API/GraphQL reference/Shopify Payments

2021/10/02に公開

この記事について

この記事は、Admin API/GraphQL reference/Shopify Paymentsの記事を和訳したものです。

記事内で使用する画像は、公式ドキュメント内の画像を引用して使用させていただいております。

Shopify アプリのご紹介

Shopify アプリである、「商品ページ発売予告アプリ | リテリア Coming Soon」は、商品ページを買えない状態のまま、発売日時の予告をすることができるアプリです。Shopify で Coming Soon 機能を実現することができます。

https://apps.shopify.com/shopify-application-314?locale=ja&from=daniel

Shopify アプリである、「らくらく日本語フォント設定|リテリア Font Picker」は、ノーコードで日本語フォントを使用できるアプリです。日本語フォントを導入することでブランドを演出することができます。

https://apps.shopify.com/font-picker-1?locale=ja&from=daniel

Overview

Shopify Payments API

Shopify Payments API を使用すると、次のリソースを使用して、マーチャントの ShopifyPayments アカウントに関する情報にアクセスできます。


Shopify PaymentsAPI のバージョン管理

REST API は、リクエストのAcceptヘッダーにある MIME タイプを介してスキーマのバージョン管理を提供します。初期タイプはapplication/vnd.shopifypayments.v1+jsonです。デフォルトでは、すべての JSON リクエストは最新バージョンの API を受け取ります。ライアントは、Acceptヘッダーで必要なバージョンを指定する必要があります。

新しいバージョンは、下位互換性のない変更に対してのみ導入されます。たとえば、新しいプロパティを追加しても下位互換性があると見なされ、新しいバージョンは導入されません。


Shopify PaymentsAPI 応答のページ付け

アイテムのコレクションを返すリクエストはページ付けされます。各コレクションのレスポンスには、ページをトラバースするための 1 つまたは複数のハイパーメディアリンク関係を持つLinkヘッダーが含まれています。パラメータは変更される可能性があるため、クライアントはこれらの提供された URL を使用してコレクションを横断し、独自の URL を作成しないことをお勧めします。

relプロパティは次の値を持つことができます。

  • next:結果のすぐ次のページのリンク関係。
  • prev:結果の直前のページのリンク関係。

OBJECTS

OrderDisputeSummary(Object)

注文に関する紛争の重要な詳細の要約。


Fields

id (ID!)
グローバル一意の識別子。

initiatedAsDisputeType!

苦情が開始されたタイプ。

statusDisputeStatus!

苦情の現状。


OrderDisputeSummary を返すタイプ


実装


サンプル

Query
# 注文に対する苦情のIDを取得する
{
  order(id:"gid://shopify/Order/1248358563862") {
    disputes {
      id
    }
  }
}
Response
{
  "data": {
    "order": {
      "disputes": []
    }
  },
  "extensions": {
    "cost": {
      "requestedQueryCost": 2,
      "actualQueryCost": 2,
      "throttleStatus": {
        "maximumAvailable": 1000,
        "currentlyAvailable": 998,
        "restoreRate": 50
      }
    }
  }
}
Query
# 注文に対する苦情のタイプを取得
{
  order(id:"gid://shopify/Order/1248358563862") {
    disputes {
      initiatedAs
    }
  }
}
Response
{
  "data": {
    "order": {
      "disputes": []
    }
  },
  "extensions": {
    "cost": {
      "requestedQueryCost": 2,
      "actualQueryCost": 2,
      "throttleStatus": {
        "maximumAvailable": 1000,
        "currentlyAvailable": 998,
        "restoreRate": 50
      }
    }
  }
}
Query
# 注文に対する苦情のステータスを取得
{
  order(id:"gid://shopify/Order/1248358563862") {
    disputes {
      status
    }
  }
}
Response
{
  "data": {
    "order": {
      "disputes": []
    }
  },
  "extensions": {
    "cost": {
      "requestedQueryCost": 2,
      "actualQueryCost": 2,
      "throttleStatus": {
        "maximumAvailable": 1000,
        "currentlyAvailable": 998,
        "restoreRate": 50
      }
    }
  }
}

ShopifyPaymentsBankAccount(Object)

支払いを受け取ることができる銀行口座。


接続

payoutsShopifyPaymentsPayoutConnection!
アカウントと銀行口座の間で行われた現在および以前のすべての支払い。

引数 説明
after ( String ) 指定されたカーソルの後に続く要素を返します。
before ( String ) 指定されたカーソルの前にある要素を返します。
first ( Int ) リストから最初のn個の要素までを返します。
last ( Int ) リストから最後のn個までの要素を返します。
reverse ( Boolean ) 基になるリストの順序を逆にします。
デフォルト値:false
transactionType ( ShopifyPaymentsPayoutTransactionType ) 支払いの方向をフィルタリングします。

Fields

accountNumber (String!)
銀行口座の口座番号。

accountNumberLastDigitsString!
アカウント番号の最後の桁(残りは編集されます)。

bankName (String)
銀行の名前。

country (CountryCode!)
銀行の国。

createdAt (DateTime!)
銀行口座が作成された日付。

currency (CurrencyCode!)
銀行口座の通貨。

id (ID!)
グローバル一意の識別子。

routingNumber (String!)
銀行口座の銀行コード。

status (ShopifyPaymentsBankAccountStatus!)
銀行口座のステータス。


ShopifyPaymentsBankAccount を返すタイプ


実装

複数の ShopifyPaymentsBankAccounts を介してページングするための自動生成されたタイプ。


Fields

edges ([ShopifyPaymentsBankAccountEdge!]!)
エッジのリスト。

pageInfo (PageInfo!)
ページ付けを支援するための情報。

ページ付け中に 1 つの ShopifyPaymentsBankAccount とカーソルを保持する自動生成されたタイプ。


Fields

cursor (String!)
ページ付けで使用するカーソル。

node (ShopifyPaymentsBankAccount!)
ShopifyPaymentsBankAccountEdge の最後にあるアイテム。


ShopifyPaymentsBankAccountEdge を返すタイプ


サンプル

Query
# 最初の10個の銀行口座のIDを取得します
{
  shopifyPaymentsAccount {
    bankAccounts(first:10) {
      edges {
        node {
          id
        }
      }
    }
  }
}
Response
{
  "data": {
    "shopifyPaymentsAccount": {
      "bankAccounts": {
        "edges": []
      }
    }
  },
  "extensions": {
    "cost": {
      "requestedQueryCost": 13,
      "actualQueryCost": 3,
      "throttleStatus": {
        "maximumAvailable": 1000,
        "currentlyAvailable": 997,
        "restoreRate": 50
      }
    }
  }
}

ShopifyPaymentsDefaultChargeStatementDescriptor(Object)

支払いアカウントの料金記述子。


Fields

default (String)
デフォルトの料金明細記述子。

prefix (String!)
ステートメント記述子のプレフィックス。


実装


ShopifyPaymentsDispute(Object)

買い手が金融機関への請求の正当性に疑問を呈した場合、苦情が発生します。


Fields

amount (MoneyV2!)
カード所有者が異議を唱えた合計金額。

evidenceDueBy (Date)
証拠提出の締め切り。

evidenceSentOn (Date)
証拠が送信された日付。証拠がまだ送信されていない場合は null を返します。

finalizedOn (Date)
この苦情が解決された日付。苦情がまだ解決されていない場合は null を返します。

id (ID!)
グローバル一意の識別子。

initiatedAt (DateTime!)
この苦情が開始された日付。

legacyResourceId (UnsignedInt64!
REST 管理 API の対応するリソースの ID。

order (Order)
苦情の下にある請求を含む注文。

reasonDetails (ShopifyPaymentsDisputeReasonDetails!)
苦情の理由。

status (DisputeStatus!)
苦情の現状。

type (DisputeType!)
この苦情がまだ調査段階にあるのか、それともチャージバックになっているのかを示します。


ShopifyPaymentsDispute を返すタイプ


実装

複数の ShopifyPaymentsDisputes を介してページングするための自動生成されたタイプ。


Fields

edges ([ShopifyPaymentsDisputeEdge!]!)
エッジのリスト。

pageInfo (PageInfo!)
ページ付けを支援するための情報。

ページ付け中に 1 つの ShopifyPaymentsBankAccount とカーソルを保持する自動生成されたタイプ。


Fields

cursor (String!)
ページ付けで使用するカーソル。

node (ShopifyPaymentsDispute!)
ShopifyPaymentsBankAccountEdge の最後にあるアイテム。


ShopifyPaymentsDisputeEdge を返すタイプ


サンプル

Query
# 始めの10個の苦情のIDを取得
{
  shopifyPaymentsAccount {
    disputes(first:10) {
      edges {
        node {
          id
        }
      }
    }
  }
}
Response
{
  "data": {
    "shopifyPaymentsAccount": {
      "disputes": {
        "edges": []
      }
    }
  },
  "extensions": {
    "cost": {
      "requestedQueryCost": 13,
      "actualQueryCost": 3,
      "throttleStatus": {
        "maximumAvailable": 1000,
        "currentlyAvailable": 997,
        "restoreRate": 50
      }
    }
  }
}

ShopifyPaymentsDisputeReasonDetails(Object)

苦情の理由に関する詳細。


Fields

networkReasonCode (String)
支払いネットワークによって提供される生のコード。

reason (ShopifyPaymentsDisputeReason!)
カード所有者の銀行から提供された苦情の理由。


ShopifyPaymentsDisputeReasonDetails を返すタイプ


ShopifyPaymentsFraudSettings (Object)

支払いアカウントの不正設定。


Fields

declineChargeOnAvsFailure (Boolean!)
AVS に障害が発生した場合は、請求を拒否します。

declineChargeOnCvcFailure (Boolean!)
CVC に障害が発生した場合は、請求を拒否します。


ShopifyPaymentsFraudSettings を返すタイプ


ShopifyPaymentsJpChargeStatementDescriptor(Object)

日本の支払いアカウントの料金記述子。


Fields

default (String)
デフォルトの料金明細記述子。

kana (String)
かなの請求明細記述子。

kanji (String)
漢字の料金明細記述子。

prefix (String!)
ステートメント記述子のプレフィックス。


実装


ShopifyPaymentsMerchantCategoryCode(Object)

MerchantCategoryCode(MCC)は、小売金融サービス用に ISO 18245 にリストされている 4 桁の番号であり、提供する商品またはサービスのタイプによってビジネスを分類するために使用されます。


Fields

category (String!)
MCC のカテゴリー。

categoryLabel (String!)
MCC のカテゴリラベル。

code (Int!)
ISO18245 にリストされている 4 桁の番号。

id (Int!)
MCC の ID。

subcategoryLabel (String!)
MCC のサブカテゴリラベル。


ShopifyPaymentsMerchantCategoryCode を返すタイプ


ShopifyPaymentsNotificationSettings(Object)

アカウントの通知設定。


Fields

payouts (Boolean!)
新しい支払いが送信されたとき、または支払いが失敗したときに電子メール通知を受信します。


ShopifyPaymentsNotificationSettings を返すタイプ


ShopifyPaymentsPayout(Object)

支払いは、マーチャントの ShopifyPayments 残高と銀行口座の間のお金の移動を表します。


Fields

bankAccount (ShopifyPaymentsBankAccount)
支払いの銀行口座。

id (ID!)
グローバル一意の識別子。

issuedAt (DateTime!)
支払いが発行された正確な時刻。支払いには、現時点で利用可能な残高取引のみが含まれます。

legacyResourceId (UnsignedInt64!)
REST 管理 API の対応するリソースの ID。

net (MoneyV2!)
支払いの合計金額と通貨。

status (ShopifyPaymentsPayoutStatus!)
支払いの転送ステータス。

summary (ShopifyPaymentsPayoutSummary!)
支払いの概要。

transactionType (ShopifyPaymentsPayoutTransactionType!)
支払いの方向。


ShopifyPaymentsPayout を返すタイプ


実装


非推奨のフィールド

表示/非表示
  • gross (MoneyV2!)
    支払いの合計金額と通貨。

複数の ShopifyPaymentsPayouts を介してページングするための自動生成されたタイプ。


Fields

edges ([ShopifyPaymentsPayoutEdge!]!)
エッジのリスト。

pageInfo (PageInfo!)
ページ付けを支援するための情報。

ページ付け中に 1 つの ShopifyPaymentsPayout とカーソルを保持する自動生成タイプ。


Fields

cursor (String!)
ページ付けで使用するカーソル。

node (ShopifyPaymentsPayout!)
ShopifyPaymentsPayoutEdge の最後にあるアイテム。


ShopifyPaymentsPayoutEdge を返すタイプ


サンプル

Query
# 最初の10回の支払いのIDを取得
{
  shopifyPaymentsAccount {
    payouts(first:10) {
      edges {
        node {
          id
        }
      }
    }
  }
}
Response
{
  "data": {
    "shopifyPaymentsAccount": {
      "payouts": {
        "edges": []
      }
    }
  },
  "extensions": {
    "cost": {
      "requestedQueryCost": 13,
      "actualQueryCost": 3,
      "throttleStatus": {
        "maximumAvailable": 1000,
        "currentlyAvailable": 997,
        "restoreRate": 50
      }
    }
  }
}

ShopifyPaymentsPayoutSchedule(Object)

支払いアカウントの支払いスケジュール。


Fields

interval (ShopifyPaymentsPayoutInterval!)
接続された銀行口座に支払いが送られる間隔。

monthlyAnchor (Int)
月毎の資金が支払われる日。

値は、1 日から 31 日までの任意の日にすることができます。支払い間隔が月単位に設定されている場合、この値が使用されます。月の 29 日から 31 日の間に予定されている支払いは、短い月の最終日に支払われます。

weeklyAnchor (DayOfTheWeek)
資金が支払われ曜日。

値は、月曜から金曜までの任意の曜日を指定できます。支払い間隔が週単位に設定されている場合、この値が使用されます。


ShopifyPaymentsPayoutSchedule を返すタイプ


ShopifyPaymentsPayoutSummary(Object)

支払いに関連するさまざまなタイプのトランザクションのそれぞれの合計料金と総額の内訳。


Fields

adjustmentsFee (MoneyV2!)
苦情を含むすべての調整の合計料金。

adjustmentsGross (MoneyV2!)
紛争を含むすべての調整の総額。

chargesFee (MoneyV2!)
すべての料金の合計料金。

chargesGross (MoneyV2!)
すべての料金の合計総額。

refundsFee (MoneyV2!)
すべての払い戻しの合計料金。

refundsFeeGross (MoneyV2!)
すべての払い戻しの総額。

reservedFundsFee (MoneyV2!)
すべての予約済み資金の合計手数料。

reservedFundsGross (MoneyV2!)
すべての予約済み資金の合計総額。

retriedPayoutsFee (MoneyV2!)
再試行されたすべての支払いの合計料金。

retriedPayoutsGross (MoneyV2!)
再試行されたすべての支払いの合計総額。


ShopifyPaymentsPayoutSummary を返すタイプ


ShopifyPaymentsVerification (Object)

アカウントの各サブジェクト(個人)には、検証状態に関する情報を提供する検証オブジェクトがあります。


Fields

id (ID!)
グローバル一意の識別子。

status (ShopifyPaymentsVerificationStatus!)
検証のステータス。

subject (ShopifyPaymentsVerificationSubject!)
確認が必要な対象/個人。


ShopifyPaymentsVerification を返すタイプ


実装

サンプル

Query
# Shopify支払いアカウントに関連付けられている検証IDを取得
{
  shopifyPaymentsAccount {
    verifications {
      id
    }
  }
}
Response
{
  "data": {
    "shopifyPaymentsAccount": {
      "verifications": [
        {
          "id": "gid://shopify/ShopifyPaymentsVerification/8926756886"
        },
        {
          "id": "gid://shopify/ShopifyPaymentsVerification/14272331798"
        },
        {
          "id": "gid://shopify/ShopifyPaymentsVerification/14272364566"
        }
      ]
    }
  },
  "extensions": {
    "cost": {
      "requestedQueryCost": 2,
      "actualQueryCost": 2,
      "throttleStatus": {
        "maximumAvailable": 1000,
        "currentlyAvailable": 998,
        "restoreRate": 50
      }
    }
  }
}
Query
# 各検証のステータスを取得
{
  shopifyPaymentsAccount {
    verifications {
      id
      status
    }
  }
}
Response
{
  "data": {
    "shopifyPaymentsAccount": {
      "verifications": [
        {
          "id": "gid://shopify/ShopifyPaymentsVerification/8926756886",
          "status": "UNVERIFIED"
        },
        {
          "id": "gid://shopify/ShopifyPaymentsVerification/14272331798",
          "status": "UNVERIFIED"
        },
        {
          "id": "gid://shopify/ShopifyPaymentsVerification/14272364566",
          "status": "UNVERIFIED"
        }
      ]
    }
  },
  "extensions": {
    "cost": {
      "requestedQueryCost": 2,
      "actualQueryCost": 2,
      "throttleStatus": {
        "maximumAvailable": 1000,
        "currentlyAvailable": 998,
        "restoreRate": 50
      }
    }
  }
}

ShopifyPaymentsVerificationDocument(Object)

個人を確認するために使用できるドキュメント。


Fields

backRequired (Boolean!)
ドキュメントの裏側が必要な場合は True。

frontRequired (Boolean!)
ドキュメントの表側が必要な場合は True。

type (ShopifyPaymentsVerificationDocumentType!)
検証に使用できるドキュメントのタイプ。


ShopifyPaymentsVerificationDocument を返すタイプ


ShopifyPaymentsVerificationSubject(Object)

検証対象は、検証が必要な個人を表します。


Fields

familyName (String!)
確認する個人の名前。

givenName (String!)
確認する個人の名。


ShopifyPaymentsVerificationSubject を返すタイプ

INTERFACES

ShopifyPaymentsChargeStatementDescriptor(Interface)

支払いアカウントの料金記述子。


Fields

default (String)
デフォルトの料金明細記述子。

prefix (String!)
ステートメント記述子のプレフィックス。


ShopifyPaymentsChargeStatementDescriptor を実装するタイプ

ENUMS

DayOfTheWeek(Enum)

月曜日から日曜日までの曜日。


Values

FRIDAY
金曜日。

MONDAY
月曜日。

SATURDAY
土曜日。

SUNDAY
日曜日。

THURSDAY
木曜日。

TUESDAY
火曜日。

WEDNESDAY
水曜日。


DayOfTheWeek を返すタイプ


DisputeStatus(Enum)

苦情の可能性のあるステータス。


Values

ACCEPTED
CHARGE_REFUNDED
LOST
NEEDS_RESPONSE
UNDER_REVIEW
WON


DisputeStatus を返すタイプ


DisputeType(Enum)

苦情の可能性のあるタイプ。


Values

CHARGEBACK
論争はチャージバックに変わった。

INQUIRY
苦情は調査段階にあります。


DisputeType を返すタイプ


ShopifyPaymentsBankAccountStatus(Enum)

銀行口座のステータス。


Values

ERRORED
銀行口座への支払いに失敗しました。

NEW
アクティビティがなく、検証されていない銀行口座。

VALIDATED
銀行口座が存在すると判断されました。

VERIFIED
銀行口座の検証は成功しました。


ShopifyPaymentsBankAccountStatus を返すタイプ


ShopifyPaymentsDisputeReason(Enum)

カード所有者の銀行から提供された苦情の理由。


Values

BANK_CANNOT_PROCESS
顧客の銀行は請求を処理できません。

CREDIT_NOT_PROCESSED
顧客は、購入した製品が返品されたか、取引がキャンセルされたと主張していますが、あなたはまだ返金またはクレジットを提供していません。

CUSTOMER_INITIATED
顧客が苦情を開始しました。支払いに苦情が出た理由の詳細については、顧客にお問い合わせください。

DEBIT_NOT_AUTHORIZED
顧客の銀行では、引き落としが承認されていないため、手続きができません。

DUPLICATE
顧客は、同じ製品またはサービスに対して複数回請求さ ​​ れたと主張しています。

FRAUDULENT
カード所有者は、支払いを承認しなかったと主張しています。

GENERAL
他の種類に分類されない苦情であるため、支払いに苦情が出た理由については、お客様に詳細について問い合わせる必要があります。

INCORRECT_ACCOUNT_DETAILS
購入に関連付けられている顧客アカウントが正しくありません。

INSUFFICIENT_FUNDS
顧客の銀行口座の資金が不足しています。

PRODUCT_NOT_RECEIVED
顧客は、購入した製品またはサービスを受け取っていないと主張しています。

PRODUCT_UNACCEPTABLE
製品またはサービスを受け取りましたが、欠陥があるか、損傷しているか、説明どおりではありませんでした。

SUBSCRIPTION_CANCELLED
顧客は、サブスクリプションがキャンセルされた後も引き続き請求されていると主張しています。

UNRECOGNIZED
顧客は、カードの明細書に記載されている支払いを認識していません。


ShopifyPaymentsDisputeReason を返すタイプ


ShopifyPaymentsPayoutInterval (Enum)

接続された銀行口座に支払いが送られる間隔。


Values

DAILY
毎日。

MANUAL
支払いは自動的には行われません。

MONTHLY
毎月、monthlyAnchor で指定された日に。

WEEKLY
毎週、weeklyAnchor で指定された曜日。


ShopifyPaymentsPayoutInterval を返すタイプ


ShopifyPaymentsPayoutStatus(Enum)

支払いの転送ステータス。


Values

CANCELED
支払いは Shopify によってキャンセルされました。

FAILED
銀行は支払いを拒否しました。

IN_TRANSIT
支払いは銀行に提出されました。

PAID
支払いは銀行に正常に預け入れられました。

SCHEDULED
支払いが作成され、トランザクションが割り当てられていますが、まだ銀行に送信されていません。


ShopifyPaymentsPayoutTransactionType(Enum)

支払いの可能なトランザクションタイプ。


Values

DEPOSIT
預金で支払います。

WITHDRAWAL
引き出して支払います。


ShopifyPaymentsPayoutTransactionType を返すタイプ


ShopifyPaymentsVerificationDocumentType(Enum)

可能な検証ドキュメントの種類。


Values

DRIVERS_LICENSE
対象の運転免許証。

GOVERNMENT_IDENTIFICATION
対象の政府の身分証明書。

PASSPORT
対象のパスポート。


ShopifyPaymentsVerificationDocumentType を返すタイプ


ShopifyPaymentsVerificationStatus(Enum)

検証のステータス。


Values

PENDING
検証リクエストは送信されましたが、まだ応答がありません。

UNVERIFIED
検証はまだ行われていません。

VERIFIED
検証が完了しました。


ShopifyPaymentsVerificationStatus を返すタイプ

Shopify アプリのご紹介

Shopify アプリである、「商品ページ発売予告アプリ | リテリア Coming Soon」は、商品ページを買えない状態のまま、発売日時の予告をすることができるアプリです。Shopify で Coming Soon 機能を実現することができます。

https://apps.shopify.com/shopify-application-314?locale=ja&from=daniel

Shopify アプリである、「らくらく日本語フォント設定|リテリア Font Picker」は、ノーコードで日本語フォントを使用できるアプリです。日本語フォントを導入することでブランドを演出することができます。

https://apps.shopify.com/font-picker-1?locale=ja&from=daniel

Discussion

ログインするとコメントできます