| Parameter
|
Description
|
| chargeId Type: string |
Charge identifier This value is returned at the end of a completed Checkout Session or you can create a new charge from a Charge Permission in a Chargeable state |
| chargePermissionId Type: string |
Charge Permission identifier
|
| chargeAmount Type: price |
Represents the amount to be charged/authorized Maximum value: US: $150,000 UK: £150,000 Germany: €150,000 Japan: ¥10,000,000 |
| captureAmount Type: price |
The total amount that has been captured using this Charge
|
| refundedAmount Type: price |
The total amount that has been refunded using this Charge
|
| softDescriptor Type: string |
Description shown on the buyer payment instrument statement. You can only use this parameter if CaptureNow is set to trueDo not store sensitive data about the buyer or the transaction in this field. Sensitive data includes, but is not limited to: government-issued identification, bank account numbers, or credit card numbers The soft descriptor sent to the payment processor is: "AMZ* <soft descriptor specified here>" Default: "AMZ*<SELLER_NAME> pay.amazon.com" Max length: 16 characters/bytes |
| captureNow Type: boolean |
Boolean that indicates whether or not Charge should be captured immediately after a successful authorization Default: false |
| canHandlePendingAuthorization Type: boolean |
Boolean that indicates whether or not merchant can handle pending response If set to false, you will receive a response within a maximum of 15 seconds in US, EU, and UK regions or 30 seconds in JP region. If set to true, Amazon Pay will process the authorization asynchronously and you will receive a response within 24 hours. See asynchronous processing for more info |
| providerMetadata Type: providerMetadata |
Payment service provider (PSP)-provided order details Only PSPs should use these fields |
| creationTimestamp Type: dateTime |
UTC date and time when the Charge was created in ISO 8601 format
|
| expirationTimestamp Type: dateTime |
UTC date and time when the Charge will expire in ISO 8601 format |
| merchantMetadata Type: merchantMetadata |
Merchant-provided order details. You can only set this parameter for Charges created using recurring Charge Permission objects
|
| statusDetails Type: statusDetails |
State of the Charge object
|
| convertedAmount Type: price |
The amount captured in disbursement currency. This is calculated using: chargeAmount/conversionRateSee multi-currency integration for more info |
| conversionRate Type: double |
The rate used to calculate convertedAmountSee multi-currency integration for more info |
| releaseEnvironment Type: string |
The environment the Charge object was created in (either Sandbox or Live)
|
| chargeInitiator Type: string |
Represents who initiated the charge.
Supported values: 'CITU', 'MITU', 'CITR', 'MITR' CITU: A customer-initiated unscheduled transaction is a transaction where the customer is present and provides their payment credentials. This can be through a terminal in-store, or online through a checkout experience. The customer-initiated transaction is the proof that the customer and merchant entered into a relationship and that the payment credential presented was in fact a validly presented payment instrument. MITU: A merchant-initiated unscheduled transaction is a transaction where the customer is not present and is conducted without any additional cardholder validation. In all cases, a merchant-initiated transaction must refer to a customer’s original interaction where a customer and merchant have entered into an agreement for a recurring product or service or an automated billing or unscheduled transactions etc. There are many different kinds of merchant-initiated transactions. Examples include:
MITR: A merchant-initiated transaction for a recurring transaction. Use this for all subsequent recurring charges, regardless of how the first recurring charge was initiated. |
| channel Type: string |
Represents the channel of the charge.
Supported values: 'Web', 'Phone', 'App', 'Alexa', 'PointOfSale', 'Firetv', 'Offline' When to use these channels:
|
| Parameter
|
Description
|
| amount Type: string |
Transaction amount
|
| currencyCode Type: string |
Transaction currency code in ISO 4217 format Example: USD |
| Parameter
|
Description
|
| providerReferenceId Type: string |
Payment service provider (PSP)-provided order identifier Only PSPs should use these fields |
| Parameter
|
Description
|
| merchantReferenceId Type: string |
External merchant order identifier. The merchant order identifier is shared in buyer communication and in the buyer transaction history on the Amazon Pay website Max length: 256 characters/bytes |
| merchantStoreName Type: string |
Merchant store name. Setting this parameter will override the default value configured in Seller Central (US, EU, JP). The store name is shared in buyer communication and in the buyer transaction history on the Amazon Pay website Max length: 50 characters/bytes |
| noteToBuyer Type: string |
Description of the order that is shared in buyer communication Do not store sensitive data about the buyer or the transaction in this field. Sensitive data includes, but is not limited to: government-issued identification, bank account numbers, or credit card numbers Max length: 255 characters/bytes |
| customInformation Type: string |
Custom information for the order. This data is not shared in any buyer communication Do not store sensitive data about the buyer or the transaction in this field. Sensitive data includes, but is not limited to: government-issued identification, bank account numbers, or credit card numbers Max length: 4,096 characters/bytes |
| Parameter
|
Description
|
| state Type: string |
Current object state
|
| reasonCode Type: string |
Reason code for current state
|
| reasonDescription Type: string |
An optional description of the Charge state
|
| lastUpdatedTimestamp Type: dateTime |
UTC date and time when the state was last updated in ISO 8601 format
|
| State
|
Description
|
Reason code
|
| AuthorizationInitiated
|
Charge is in a pending state. See asynchronous processing for more information Allowed operation(s): GET Charge DELETE Charge |
-
|
| Authorized
|
Charge was successfully authorized Allowed operation(s): GET Charge POST Capture DELETE Charge |
-
|
| CaptureInitiated
|
Charge capture processing, will move to either Captured or Declined state depending on outcome Allowed operation(s): GET Charge |
-
|
| Captured
|
Charge was successfully captured Allowed operation(s): GET Charge POST Refund |
-
|
| Canceled
|
Charge was canceled by Amazon or by the merchant Allowed operation(s): GET Charge |
ExpiredUnused - The Charge has been in the Authorized state for 30 days without being captured AmazonCanceled - Amazon canceled the Charge MerchantCanceled - You canceled the Charge using the Cancel Charge operation or the Charge was closed because you did not call Complete Checkout Session ChargePermissionCanceled - You canceled the Charge Permission used to create the Charge using the Cancel Charge Permission operation with cancelPendingCharges set to trueBuyerCanceled - The buyer canceled the Charge |
| Declined
|
The authorization or capture was declined Allowed operation(s): GET Charge |
SoftDeclined - Charge was soft declined. Retry attempts may or may not be successful. If repeated retry attempts are unsuccessful, please contact the buyer and have them choose a different payment instrument HardDeclined - Charge was hard declined. Retry attempts will not succeed. Please contact the buyer and have them choose a different payment instrument AmazonRejected - Charge was declined by Amazon. The associated Charge Permission will also be canceled ProcessingFailure - Amazon could not process the Charge because of an internal processing error. You should retry the charge only if the Charge Permission is in the Chargeable state TransactionTimedOut - If you set canHandlePendingAuthorization to false, the Charge was declined because Amazon Pay did not have enough time to process the authorization. Please contact the buyer and have them choose another payment method. If you frequently encounter this decline, consider setting canHandlePendingAuthorization to true If you set canHandlePendingAuthorization to true, the Charge was declined because Amazon Pay was unable to determine the validity of the order. Please contact the buyer and have them choose another payment method. See asynchronous processing for more information
|
| Name
|
Location
|
Description
|
| x-amz-pay-idempotency-key (required) Type: string |
Header
|
Idempotency key to safely retry requests
|
| chargePermissionId (required) Type: string |
Body
|
Charge Permission identifier
|
| chargeAmount (required) Type: price |
Body
|
Transaction amount
|
| chargeInitiator (required) Type: string |
Body
|
Represents who initiated the charge.
Supported values: 'CITU', 'MITU', 'CITR', 'MITR' CITU: A customer-initiated unscheduled transaction is a transaction where the customer is present and provides their payment credentials. This can be through a terminal in-store, or online through a checkout experience. The customer-initiated transaction is the proof that the customer and merchant entered into a relationship and that the payment credential presented was in fact a validly presented payment instrument. MITU: A merchant-initiated unscheduled transaction is a transaction where the customer is not present and is conducted without any additional cardholder validation. In all cases, a merchant-initiated transaction must refer to a customer’s original interaction where a customer and merchant have entered into an agreement for a recurring product or service or an automated billing or unscheduled transactions etc. There are many different kinds of merchant-initiated transactions. Examples include:
MITR: A merchant-initiated transaction for a recurring transaction. Use this for all subsequent recurring charges, regardless of how the first recurring charge was initiated. * Only required for ChargePermissionType of PaymentMethodOnFile
|
| channel Type: string |
Body
|
Represents the channel of the charge.
Supported values: 'Web', 'Phone', 'App', 'Alexa', 'PointOfSale', 'Firetv', 'Offline' When to use these channels:
|
| captureNow Type: boolean |
Body
|
Boolean that indicates whether or not Charge should be captured immediately after a successful authorization Default: false |
| softDescriptor Type: string |
Body
|
Description shown on the buyer payment instrument statement, if CaptureNow is set to true. Do not set this value if CaptureNow is set to falseThe soft descriptor sent to the payment processor is: "AMZ* <soft descriptor specified here>" The soft descriptor sent to the payment processor is: "AMZ* <soft descriptor specified here>" Default: "AMZ*<SELLER_NAME> pay.amazon.com" Max length: 16 characters/bytes |
| canHandlePendingAuthorization Type: boolean |
Body
|
Boolean that indicates whether or not merchant can handle pending response If set to false, you will receive a response within a maximum of 15 seconds in US, EU, and UK regions or 30 seconds in JP region. If set to true, Amazon Pay will process the authorization asynchronously and you will receive a response within 24 hours. See asynchronous processing for more info |
| merchantMetadata Type: merchantMetadata |
Body
|
Merchant-provided order details. You can only set this parameter for Charges created using recurring Charge Permission objects
|
| providerMetadata Type: providerMetadata |
Body
|
Payment service provider (PSP)-provided order details Only PSPs should use these fields |
| HTTP status code
|
Reason code
|
Description
|
| 400 BAD_REQUEST
|
TransactionAmountExceeded
|
You've exceeded the monthly maximum charge amount allowed for a recurring Charge Permission.
|
| 400 BAD_REQUEST
|
PeriodicAmountExceeded
|
You've exceeded the monthly maximum charge amount allowed for a recurring Charge Permission. The limit per buyer resets every calendar month, see monthly recurring charge limits for more info
|
| 422 UNPROCESSABLE_ENTITY
|
InvalidChargePermissionStatus
|
You tried to call an operation on a ChargePermission object that is in a state where that operation cannot be called
|
| 422 UNPROCESSABLE_ENTITY
|
SoftDeclined
|
Charge was soft declined. Retry attempts may or may not be successful. If repeated retry attempts are unsuccessful, contact the buyer and have them choose a different payment instrument
|
| 422 UNPROCESSABLE_ENTITY
|
HardDeclined
|
Charge was hard declined. Retry attemps will not succeed. Please contact the buyer and have them choose a different payment instrument
|
| 422 UNPROCESSABLE_ENTITY
|
TransactionCountExceeded
|
You've exceeded the maximum limit of 1 successfully captured Charge per Charge Permission
|
| 422 UNPROCESSABLE_ENTITY
|
PaymentMethodNotAllowed
|
The payment method selected by the buyer is not allowed for this Charge
|
| 422 UNPROCESSABLE_ENTITY
|
AmazonRejected
|
Charge was declined by Amazon. The associated Charge Permission will also be canceled
|
| 422 UNPROCESSABLE_ENTITY
|
MFANotCompleted
|
Multi-factor authentication (MFA) is required to be complete by the buyer for this transaction to process
|
| 422 UNPROCESSABLE_ENTITY
|
TransactionTimedOut
|
If you set canHandlePendingAuthorization to false, the Charge was declined because Amazon Pay did not have enough time to process the authorization. Contact the buyer and have them choose another payment method. If you frequently encounter this decline, consider setting canHandlePendingAuthorization to trueIf you set canHandlePendingAuthorization to true, the Charge was declined because Amazon Pay was unable to determine the validity of the order. Contact the buyer and have them choose another payment method. See asynchronous processing for more information
|
| 425 TOO_EARLY
|
TransactionInProgress
|
A duplicate request was sent with the same idempotency key or a concurrent request was made on the same resource while the original request is still being processed. Wait for the SLA to complete (15 seconds for US, EU, and UK regions; 30 seconds for JP region) before retrying, or check the status of your original request.
|
| 500 INTERNAL_SERVER_ERROR
|
ProcessingFailure
|
Amazon could not process the Charge because of an internal processing error. You should retry the charge only if the Charge Permission is in the Chargeable state
|
| Name
|
Location
|
Description
|
| chargeId (required) Type: string |
Path Parameter
|
Charge identifier
|
| Name
|
Location
|
Description
|
| x-amz-pay-idempotency-key (required) Type: string |
Header
|
Idempotency key to safely retry requests
|
| chargeId (required) Type: string |
Path Parameter
|
Charge identifier
|
| captureAmount (required) Type: price |
Body
|
Amount to capture
|
| softDescriptor Type: string |
Body
|
Description shown on the buyer's payment instrument statement. The soft descriptor sent to the payment processor is: "AMZ* <soft descriptor specified here>" The soft descriptor sent to the payment processor is: "AMZ* <soft descriptor specified here>" Default: "AMZ*<SELLER_NAME> pay.amazon.com" Max length: 16 characters/bytes |
| HTTP status code
|
Reason code
|
Description
|
| 400 BAD_REQUEST
|
TransactionAmountExceeded
|
You've exceeded the maximum capture amount allowed for this Charge
|
| 422 UNPROCESSABLE_ENTITY
|
TransactionCountExceeded
|
You've exceeded the maximum limit of 1 successfully captured Charge, per Charge Permission
|
| 422 UNPROCESSABLE_ENTITY
|
InvalidChargePermissionStatus
|
You tried to call an operation on a Charge Permission that is in a state where that operation cannot be called
|
| 422 UNPROCESSABLE_ENTITY
|
InvalidChargeStatus
|
You tried to call an operation on a Charge that is in a state where that operation cannot be called
|
| 422 UNPROCESSABLE_ENTITY
|
AmazonRejected
|
Charge was declined by Amazon. The associated Charge Permission will also be canceled
|
| 500 INTERNAL_SERVER_ERROR
|
ProcessingFailure
|
Amazon could not process the Charge because of an internal processing error. You should retry the Charge only if the Charge Permission is in the Chargeable state
|
| Name
|
Location
|
Description
|
| chargeId (required) Type: string |
Path Parameter
|
Charge identifier
|
| cancellationReason Type: string |
Body
|
Merchant-provided reason for canceling Charge Max length: 255 characters/bytes |
| HTTP status code
|
Reason code
|
Description
|
| 422 UNPROCESSABLE_ENTITY
|
InvalidChargePermissionStatus
|
You tried to call an operation on a Charge Permission that is in a state where that operation cannot be called
|
| 422 UNPROCESSABLE_ENTITY
|
InvalidChargeStatus
|
You tried to call an operation on a Charge that is in a state where that operation cannot be called
|