Charge Permission

Charge Permissionオブジェクトは、購入者との請求の同意を表します。 OneTime, Recurring または PaymentMethodOnFile のCharge Permissionオブジェクトをリクエストできます。

OneTimeの Charge Permissionを使用して Charge PermissionがChargeable状態のときに、注文金額までを売上請求できます。理由コードを確認して、Charge PermissionがNon-Chargeable状態の場合に請求できない理由を特定する必要があります。OneTimeのCharge Permissionは、 total order amountが売上請求された、キャンセルされた、または180日後に期限が切れた後、Closed 状態に移行します。

RecurringのCharge Permissionを使用して、Charge PermissionがChargeable状態にある間、継続的に購入者に請求することができます。Charge PermissionがNon-Chargeable状態の場合は理由コードを確認して、できない理由を特定する必要があります。Recurringの Charge Permissionはキャンセルされた、または有効期限が切れた後、Closed 状態に移行します。

PaymentMethodOnFileのCharge Permissionを使用して、Charge PermissionがChargeable状態にある間、継続的に購入者に請求することができます。Charge PermissionがNon-Chargeable状態の場合は理由コードを確認して、できない理由を特定する必要があります。PaymentMethodOnFileの Charge Permissionはキャンセルされた後、Closed 状態に移行します。

いずれかのCharge Permissionタイプを使用して、購入者名、購入者のメールアドレス、配送先住所など、注文を完了するために必要な関連する決済の詳細を取得できます。OneTimeの Charge Permissionでは作成された後最初の30日間のみ購入者の詳細情報を取得できることに注意してください。Recurring のCharge PermissionではCharge PermissionがOpen状態か、Charge PermissionがCloseされた後の30日間、購入者の詳細を取得することができます。

サポートされている操作:


Charge Permission オブジェクト

パラメータ
説明
chargePermissionId

Type: string
Charge Permission識別子

この値は、Checkout Session completed 時に返された値です
chargePermissionType

Type: string
要求されたCharge Permissionのtype

サポートされている値:
  • 'OneTime' - Charge Permissionは1回の注文にのみ使用できます
  • 'Recurring' - Recurring注文にはCharge Permissionを継続課金に使用できます
  • 'PaymentMethodOnFile' - PaymentMethodOnFile注文にはCharge Permissionを任意のタイミングの課金に使用できます
デフォルト値: ' OneTime"
recurringMetadata

Type: recurringMetadata
Recurringの Charge Permission使用方法に関するメタデータ。 Amazon Payは、この情報を使用して、Charge Permissionの有効期限を計算し、購入者と連絡を取ります。

事業者の請求タイミングで購入者に請求するためにCreate Chargeを実行することは事業者責任であることに注意してください。
limits

Type: limits
Charge Permissionトランザクションの制限
releaseEnvironment

Type: string
Amazon Pay環境

可能な値:live, sandbox
buyer

Type: buyer
一意のID、名前、メールアドレスなど、購入者に関する詳細
shippingAddress

Type: 住所
購入者が選択した配送先住所
billingAddress

Type: 住所
購入者が選択したお支払い方法の請求先住所
paymentPreferences

Type: list < paymentPreference >
Amazon Payが提供する購入者が選択したお支払い方法
merchantMetadata

Type: merchantMetadata
販売者が提供する注文の詳細
platformId

Type: string
ソリューションプロバイダー(SP)の事業者ID

SPのみがこのフィールドを使用する必要があります
creationTimestamp

Type: dateTime
Charge Permssionが作成されたISO8601形式でのUTC日時
expirationTimestamp

Type: dateTime
Charge Permissionが期限切れになるISO8601形式でのUTC日時

OneTime のCharge Permissionは confirmed後、180日で有効期限が切れます

デフォルトでは、Recurringの Charge Permissionは13ヶ月で期限が切れます。charge を作成すると有効期限が13か月にリセットされます。 recurringMetadata.Frequencyが13か月を超える請求サイクルに設定されている場合、有効期限はrecurringMetadata.Frequencyの値に1か月を加えた値に延長された値になります。

PaymentMethodOnFileのChargePermissionの場合は有効期限は設定されません。
statusDetails

Type: statusDetails
Charge Permissionオブジェクトの状態
presentmentCurrency

Type: string
購入者へ請求するISO4217形式での通貨。例:JPY

詳細については、複数通貨のインテグレーションを参照してください

Type: limits

パラメータ
説明
amountLimit

Type: price
Charge Permissionを使用して請求できる合計金額。RecurringのCharge Permissionオブジェクトの場合、この値は、当月中に請求できる合計金額です。
amountBalance

Type: price
Charge Permissionを使用して請求できる残りの残高。RecurringのCharge Permissionオブジェクトの場合、これは当月中に請求できる残りの金額です。

Type: recurringMetadata

パラメータ
説明
frequency

Type: frequency
RecurringのCharge Permissionを使用して購入者に請求される頻度。アドホックな料金が予想される場合でも、frequencyを指定する必要があります。

可能な組み合わせ:
  • Year:1-3
  • Month:1-36
  • Week:1-57
  • Day:1-1095
amount

Type: price
Recurringのサイクルごとに購入者される金額。金額が変動する場合はnullに設定。

Type: frequency

パラメータ
説明
unit

Type: string
各請求サイクルの頻度単位。複数のサブスクリプションの場合、最短の請求サイクルのfrequency unitを指定します。詳細については、 支払い頻度が不定期の場合の処理を参照してください。

サポートされている値: 'Year', 'Month', 'Week', 'Day', 'Variable'
value

Type: string
請求サイクルごとのfrequency単位の数。たとえば、週毎を指定するには、 unitを'Week'に設定し、 valueを1に設定します。Variable unitを使用している場合は、 valueを0に設定する必要があります。

Type: price

パラメータ
説明
amount

Type: string
取引金額
currencyCode

Type: string
ISO4217形式の取引通貨コード

例:JPY

Type: buyer

パラメータ
説明
BuyerId

Type: string
一意のAmazon Pay購入者ID

最大長:42文字/バイト
name

Type: string
購入者の名前

最大長:50文字/バイト
email

Type: string
購入者のメールアドレス

最大長:64文字/バイト
phoneNumber

Type: string
購入者のデフォルトの請求先住所の電話番号

最大長:20文字/バイト
primeMembershipTypes

Type: list<primeMembershipType>
購入者のプライム会員リスト。この値の一般利用はできません。

Type: paymentPreference

パラメータ
説明
PaymentDescriptor

Type: string
購入者が選択したお支払い方法の説明

当項目には必ずnullが設定されます。

Type: address

パラメータ
説明
name

Type: string
アドレスの名前

最大長:50文字/バイト
addressLine1

Type: string
アドレスの最初の行

最大長:180文字/バイト
addressLine2

Type: string
アドレスの2行目

最大長:60文字/バイト
addressLine3

Type: string
アドレスの3行目

最大長:60文字/バイト
city

Type: string
アドレスの市区町村

最大長:50文字/バイト

日本では利用できません。
county

Type: string
アドレスの国

最大長:50文字/バイト

日本では利用できません。
district

Type: string
アドレスの地域

最大長:50文字/バイト

日本では利用できません。
stateOrRegion

Type: string
アドレスの州または行政区:
  • USおよびCAの住所-応答は常に2文字のコードになります
  • 他のすべての国 - この要素はフリーテキストであり、2文字のコード、完全なスペル、または省略形のいずれかです。日本では都道府県名として利用します。※購入者の入力次第で「東京」「Tokyo-to」などの文字が返却されることもあります
最大長:50文字/バイト
postalCode

Type: string
アドレスの郵便番号

最大長:20文字/バイト
countryCode

Type: string
ISO3166形式のアドレスの国コード

最大長:3文字/バイト
phoneNumber

Type: string
電話番号

最大長:20文字/バイト

Type: merchantMetadata

パラメータ
説明
merchantReferenceId

Type: string
事業者オーダー識別子。事業者オーダーIDは、Amazon Payウェブサイト購入者とのコミュニケーションおよび購入者の取引履歴で共有されます。

最大長:256文字/バイト
merchantStoreName

Type: string
事業者名。このパラメータを設定すると、セラーセントラル(USEUJP)で構成されたデフォルト値が上書きされます。MerchantStoreNameは、 Amazon Payウェブサイト購入者とのコミュニケーションおよび購入者の取引履歴で共有されます

最大長:50文字/バイト
noteToBuyer

Type: string
購入者とのコミュニケーションで共有される注文の説明

購入者や取引に関する機密データを保存しないでください(例えば、政府発行の身分証明書、銀行口座番号、クレジットカード番号などが含まれますが、これらに限定されません)

最大長:255文字/バイト
customInformation

Type: string
注文のカスタム情報。このデータは、購入者とのコミュニケーションでは共有されません

購入者や取引に関する機密データを保存しないでください(例えば、政府発行の身分証明書、銀行口座番号、クレジットカード番号などが含まれますが、これらに限定されません)

最大長:4096文字/バイト

Type: statusDetails

パラメータ
説明
state

Type: string
現在のオブジェクトの状態
reasons

Type: list<reason>
現在の状態の理由リスト
lastUpdatedTimestamp

Type: dateTime
stateが最後に更新されたISO8601形式でのUTC日時

Type: reason

パラメータ
説明
reasonCode

Type: string
現在のstateの理由コード
reasonDescription

Type: string
Charge Permissionstateのオプションの説明

状態と理由コード

状態
説明
理由コード
Chargeable
Charge Permissionにconstraintsがなく、購入者への請求に使用できる状態

許可された処理:
GET Charge Permission
UPDATE Charge Permission
DELETE Charge Permission
-
NonChargeable
Charge Permissionにconstraintsがあり、購入者への請求に使用できない状態

許可された処理:
GET Charge Permission
UPDATE Charge Permission
DELETE Charge Permission
PaymentMethodInvalid - 請求は拒否されました。OneTimeの場合は、購入者に支払い方法の更新を依頼してください。Recuringの場合は、こちらの手順に従ってください。

PaymentMethodDeleted - 購入者が選択した支払い方法を削除しました

BillingAddressDeleted
- 購入者が選択した支払い方法の請求先住所を削除しました

PaymentMethodExpired - 選択した支払い方法の有効期限が切れています

PaymentMethodNotAllowed - 購入者が選択したお支払い方法は、このCharge Permissionのために許可されていません

PaymentMethodNotSet - 請求許可に関連付けられた支払い方法はありません

TransactionAmountExceeded-このCharge Permissionの限度額に達したか超えました

TransactionCountExceeded - このCharge Permissionのトランザクション数の限界に達したか、超えました

MFAFailed - 購入者はトランザクションを確認しませんでした。購入者が取引上の金額を確認しない限り、Chargeを開始することができません
Closed
Charge PermissionがCloseされたか、有効期限が切れています

許可された処理:
GET Charge Permission
UPDATE Charge Permission (OneTimeのみ)
DELETE Charge Permission
MerchantClosed - Complete Checkout Sessionを実行していなかったので Charge PermissionがCloseされた、もしくは Close Charge Permission呼び出して Closeされました

BuyerClosed
- 購入者によりCharge PermissionをCloseされました

AmazonCanceled
- Amazonは請求Charge PermissionをCloseしました

AmazonClosed - amountBalanceが残っていないため、AmazonはCharge PermissionをCloseしました

Expired - Charge Permissionは180日後に期限切れになりました

オペレーション

Get Charge Permission

Charge Permissionの詳細を取得して、このCharge Permissionを使用して購入者に請求できるかどうかを判断します。 この操作を使用して、チェックアウトが成功した後、購入者の詳細と配送先住所を取得することもできます。 詳細情報は Charge Permissionが作成されてから30日間のみ取得できます。

リクエスト

リクエストパラメータ

名前
ロケーション
説明
chargePermissionId
(必須)

Type: string
Path Parameter
Charge Permission識別子

レスポンス

処理が成功した場合、 HTTP 200 ステータスコードを返します。

{
    "chargePermissionId": "chargePermission-1",
    "chargePermissionReferenceId": null,
    "buyer":{
        "buyerId": "buyerId",
        "name": "name-1",
        "email": "name@amazon.com",
        "phoneNumber": "800-000-0000",
        "primeMembershipTypes": null
    },
    "releaseEnvironment": "Live",
    "shippingAddress":{  // Null for PayOnly product type
        "name": "Work",
        "addressLine1": "440 Terry Ave",
        "addressLine2": "",
        "addressLine3": "",
        "city": "Seattle",
        "county": "King",
        "district": "Seattle",
        "stateOrRegion": "WA",
        "postalCode": "98121",
        "countryCode": "US",
        "phoneNumber": "800-000-0000"
    },
    "billingAddress":{
        "name": "Work",
        "addressLine1": "440 Terry Ave",
        "addressLine2": "",
        "addressLine3": "",
        "city": "Seattle",
        "county": "King",
        "district": "Seattle",
        "stateOrRegion": "WA",
        "postalCode": "98121",
        "countryCode": "US",
        "phoneNumber": "800-000-0000"
    },
    "paymentPreferences":[{
        "paymentDescriptor": null
    }],
    "statusDetails":{
        "state": "Chargeable",
        "reasons":null,
        "lastUpdatedTimestamp": "20190714T155300Z"
    },
    "creationTimestamp": "20190714T155300Z",
    "expirationTimestamp": "20190715T155300Z",
    "merchantMetadata":{
        "merchantReferenceId": "123-77-876", 
        "merchantStoreName": "AmazonTestStoreFront",
        "noteToBuyer": "merchantNoteForBuyer",
        "customInformation": "This is custom information"
    },
    "platformId": "SPId",
    "limits": {
        "amountLimit": {
            "amount": "14.00",
            "currencyCode": "USD"
        },
        "amountBalance": {
            "amount": "14.00",
            "currencyCode": "USD"
        }
    },
    "presentmentCurrency": "USD"
}

エラーコード

その他エラーはこちらを参照してください。

Update Charge Permission

Charge Permissionの注文メタデータを更新します。一部の値は購入者と共有される場合があります。詳細については、購入者とのコミュニケーションをご覧ください。Recurringの詳細が変更された場合は、 recurringMetadataを更新することもできます。

リクエスト

リクエストボディ

{
    "merchantMetadata": {
        "merchantReferenceId": "32-41-323141-32",
        "merchantStoreName": "AmazonTestStoreFront",
        "noteToBuyer": "Some Note to buyer",
        "customInformation": ""    
     }  
}

リクエストパラメータ

名前
ロケーション
説明
chargePermissionId
(必須)

Type: string
Path Parameter
Charge Permission識別子
recurringMetadata

Type: recurringMetadata
Body
recurringCharge Permissionの使用方法に関するメタデータ。 Amazon Payはこの情報を、Charge Permissionの有効期限の計算と購入者通知のみに使用します。

請求サイクルごとに購入者に請求するためにCreate Chargeを実行するのは事業者責任であることに注意してください
merchantMetadata

Type: merchantMetadata
Body
販売者が提供する注文の詳細

変更可否: チェックアウト後に情報を更新するをご参照下さい。

レスポンス

処理が成功した場合、 HTTP 200 ステータスコードを返します。

{
    "chargePermissionId": "chargePermission-1",
    "chargePermissionReferenceId": null,
    "buyer": {
        "buyerId": "buyerId",
        "name": "name-1",
        "email": "name@amazon.com",
        "phoneNumber": "800-000-0000",
        "primeMembershipTypes": null
    },
    "releaseEnvironment": "Live",
    "shippingAddress": {  // Null for PayOnly product type
        "name": "Work",
        "addressLine1": "440 Terry Ave",
        "addressLine2": "",
        "addressLine3": "",
        "city": "Seattle",
        "county": "King",
        "district": "Seattle",
        "stateOrRegion": "WA",
        "postalCode": "98121",
        "countryCode": "US",
        "phoneNumber": "800-000-0000"
    },
    "billingAddress": {
        "name": "Work",
        "addressLine1": "440 Terry Ave",
        "addressLine2": "",
        "addressLine3": "",
        "city": "Seattle",
        "county": "King",
        "district": "Seattle",
        "stateOrRegion": "WA",
        "postalCode": "98121",
        "countryCode": "US",
        "phoneNumber": "800-000-0000"
    },
    "paymentPreferences": [
    {
        "paymentDescriptor": null
    }],
    "statusDetails": {
        "state": "Chargeable",
        "reasons": null,
        "lastUpdatedTimestamp": "20190714T155300Z"
    },
    "creationTimestamp": "20190714T155300Z",
    "expirationTimestamp": "20190715T155300Z",
    "merchantMetadata": {
        "merchantReferenceId": "123-77-876", 
        "merchantStoreName": "AmazonTestStoreFront",
        "noteToBuyer": "merchantNoteForBuyer",
        "customInformation": "This is custom information"  
    },
    "platformId": "SPId",
    "limits": {
        "amountLimit": {
            "amount": "14.00",
            "currencyCode": "USD"
        },
        "amountBalance": {
            "amount": "14.00",
            "currencyCode": "USD"
        }
    },
    "presentmentCurrency": "USD"
}

エラーコード

HTTPステータスコード
理由コード
エラーの説明
422 UNPROCESSABLE_ENTITY
InvalidChargePermissionStatus
変更できない状態のCharge Permissionを変更しようとしました

その他エラーはこちらを参照してください。

Close Charge Permission

Closed 状態にCharge Permissionを遷移させます。 cancelPendingChargesをtrueに設定すると今後の請求はできず、保留中の請求はキャンセルされます。

リクエスト

リクエストボディ

{
    "closureReason": "No more charges required",
    "cancelPendingCharges": false
}

リクエストパラメータ

名前
ロケーション
説明
chargePermissionId
(必須)

Type: string
Path Parameter
Charge Permission識別子
closureReason

Type: string
Body
販売者が提供する請求Charge Permissionを閉じる理由

最大長: 255 characters/bytes
cancelPendingCharges

Type: boolean
Body
Trueに設定されている場合:
  • Captured状態ではない子Chargeオブジェクトはキャンセルされます
  • Charge Permissionの作成から5分以内にリクエストが行われた場合、AmazonPayの確認メールは抑制されます
デフォルト値:False

レスポンス

処理が成功した場合、 HTTP 200 ステータスコードを返します。

{
    "chargePermissionId": "chargePermission-1",
    "chargePermissionReferenceId": null,
    "buyer": {
        "buyerId": "buyerId",
        "name": "name-1",
        "email": "name@amazon.com",
        "phoneNumber": "800-000-0000",
        "primeMembershipTypes": null
    },
    "releaseEnvironment": "Live",
    "shippingAddress": {  // Null for PayOnly product type
        "name": "Work",
        "addressLine1": "440 Terry Ave",
        "addressLine2": "",
        "addressLine3": "",
        "city": "Seattle",
        "county": "King",
        "district": "Seattle",
        "stateOrRegion": "WA",
        "postalCode": "98121",
        "countryCode": "US",
        "phoneNumber": "800-000-0000"
    },
    "billingAddress": {
        "name": "Work",
        "addressLine1": "440 Terry Ave",
        "addressLine2": "",
        "addressLine3": "",
        "city": "Seattle",
        "county": "King",
        "district": "Seattle",
        "stateOrRegion": "WA",
        "postalCode": "98121",
        "countryCode": "US",
        "phoneNumber": "800-000-0000"
    },
    "paymentPreferences": [
    {
        "paymentDescriptor": null
    }],
    "statusDetails": {
        "state": "Closed",
        "reasons":
        [{
            "reasonCode": null,
            "reasonDescription": null
        }],
        "lastUpdatedTimestamp": "20190714T155300Z"
    },
    "creationTimestamp": "20190714T155300Z",
    "expirationTimestamp": "20190715T155300Z",
    "merchantMetadata":{
        "merchantReferenceId": "123-77-876", 
        "merchantStoreName": "AmazonTestStoreFront",
        "noteToBuyer": "merchantNoteForBuyer",
        "customInformation": "This is custom information" 
    },
    "platformId": "SPId",
    "limits": {
        "amountLimit": {
            "amount": "14.00",
            "currencyCode": "USD"
        },
        "amountBalance": {
            "amount": "14.00",
            "currencyCode": "USD"
        }
    },
    "presentmentCurrency": "USD"
}

エラーコード

その他エラーはこちらを参照してください。

関連トピック