Gracias por tu visita. Esta página solo está disponible en inglés.

Charge

A Charge represents a single payment transaction. Use a Charge to either authorize an amount and capture it later, or authorize and capture payment immediately.

Depending on the integration pattern, you can either create a Charge using a valid Charge Permission, or create it as a result of a successful Checkout Session. A successful Charge will move from Authorized to CaptureInitiated to Completed state. The Authorized state may be preceded by a Pending state if you set canHandlePendingAuthorization to true, or payment was captured more than 7 days after authorization. See asynchronous processing for more information. An unsuccessful Charge will move to a Declined state if payment was declined, and move to a Canceled state if the Charge is explicitly canceled, or the Charge expires after 30 days in the Authorized state.

Supported operations:

  • Create Charge - POST https://pay-api.amazon.com/:environment/:version/charges/
  • Get Charge - GET https://pay-api.amazon.com/:environment/:version/charges/:chargeId
  • Capture - POST https://pay-api.amazon.com/:environment/:version/charges/:chargeId/capture
  • Cancel Charge - DELETE https://pay-api.amazon.com/:environment/:version/charges/:chargeId/cancel
  • Create Charge - POST https://pay-api.amazon.eu/:environment/:version/charges/
  • Get Charge - GET https://pay-api.amazon.eu/:environment/:version/charges/:chargeId
  • Capture - POST https://pay-api.amazon.eu/:environment/:version/charges/:chargeId/capture
  • Cancel Charge - DELETE https://pay-api.amazon.eu/:environment/:version/charges/:chargeId/cancel
  • Create Charge - POST https://pay-api.amazon.jp/:environment/:version/charges/
  • Get Charge - GET https://pay-api.amazon.jp/:environment/:version/charges/:chargeId
  • Capture - POST https://pay-api.amazon.jp/:environment/:version/charges/:chargeId/capture
  • Cancel Charge - DELETE https://pay-api.amazon.jp/:environment/:version/charges/:chargeId/cancel

Charge object

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
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, if CaptureNow is set to true. Do not set this value if CaptureNow is set to false

The soft descriptor sent to the payment processor is: "AMZ* <soft descriptor specified here>"

Max length: 16 characters
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 merchant can handle pending response

See asynchronous processing for more information
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

statusDetail

Type: statusDetail
State of the Charge object
convertedAmount

Type: price
The amount captured in disbursement currency. This is calculated using: chargeAmount/conversionRate

See multi-currency integration for more info
conversionRate

Type: double
The rate used to calculate convertedAmount

See multi-currency integration for more info
releaseEnvironment

Type: string
The environment the Charge object was created in (either Sandbox or Live)

Type: price

Parameter
Description
amount

Type: string
Transaction amount
currencyCode

Type: string
Transaction currency code in ISO 4217 format

Example: USD

Type: providerMetadata

Parameter
Description
providerReferenceId

Type: string
Payment service provider (PSP)-provided order identifier

Only PSPs should use these fields

Type: statusDetail

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

States and reason codes

State
Description
Reason code
AuthorizationInitiated
Charge is in a pending state. See asynchronous processing for more information

Allowed operation(s):
GET Charge
DELETE Charge
StopShipmentAtypicalAuth - There are signs of unusual activity that indicate you shouldn’t proceed with fulfilment.
Authorized
Charge was successfully authorized

Allowed operation(s):
GET Charge
POST Capture
DELETE Charge
StopShipmentAtypicalAuth - There are signs of unusual activity that indicate you shouldn’t proceed with fulfilment.
CaptureInitated
Charge capture processing, will move to either Captured or Declined state depending on outcome

Allowed operation(s):
GET Charge
StopShipmentAtypicalAuth - There are signs of unusual activity that indicate you shouldn’t proceed with fulfilment.
Captured
Charge was successfully captured

Allowed operation(s):
GET Charge
POST Refund
StopShipmentAtypicalAuth - There are signs of unusual activity that indicate you shouldn’t proceed with fulfilment.
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. You can specify the reason for the closure in the CancellationReason request parameter

ChargePermissionCanceled - You have canceled the ChargePermission by calling Cancel ChargePermission operation with cancelPendingCharges set to true

BuyerCanceled - 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

Operations

Create Charge

You can create a Charge to authorize payment, if you have a Charge Permission in a Chargeable state. You can optionally capture payment immediately by setting captureNow to true. The response for Create Charge will include a Charge ID. This is the only time this value will ever be returned, so you must store the ID in order to capture payment, Get Charge details, or Create Refund at a later date. If the request fails, you should reengage the buyer and ask them to go through checkout again.

Request

curl "https://pay-api.amazon.com/:environment/:version/charges/" \
-X POST
-H "x-amz-pay-idempotency-key: AVLo5tI10BHgEk2jEXAMPLEKEY"
-H "authorization: Px2e5oHhQZ88vVhc0DO%2FsShHj8MDDg%3DEXAMPLESIGNATURE"
-d @request_body

Request body

{
    "chargePermissionId": "P21-1111111-1111111",
    "chargeAmount": {
        "amount": "14.00",
        "currencyCode": "USD"
    },
    "captureNow": true, // default is false
    "softDescriptor": "Descriptor",
    "canHandlePendingAuthorization": false //default is false
}

Request parameters

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
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 false

The soft descriptor sent to the payment processor is: "AMZ* <soft descriptor specified here>"

Max length: 16 characters
canHandlePendingAuthorization

Type: boolean
Body
Boolean that indicates whether or not merchant can handle pending response.

See asynchronous processing for more information
providerMetadata

Type: providerMetadata
Body
Payment service provider (PSP)-provided order details

Only PSPs should use these fields

Response

Returns HTTP 201 (Created) status if the operation was successful. Subsequent retry attempts using the same Idempotency Key may return a HTTP 200 (OK) status if a new resource is not created.

{
     "chargeId": "P21-1111111-1111111-C111111",
     "chargePermissionId": "P21-1111111-1111111",
     "chargeAmount": {
         "amount": "14.00",
         "currencyCode": "USD"
     },
     "captureAmount": {
         "amount": "14.00",
         "currencyCode": "USD"
     },
     "refundedAmount": {
         "amount": "0.00",
         "currencyCode": "USD"
     },
     "convertedAmount": "14.00",
     "conversionRate": "1.00",
     "softDescriptor": "Descriptor",
     "providerMetadata": {
         "providerReferenceId": null
     },
     "statusDetail": {
         "state": "Captured",
         "reasonCode":null,
         "reasonDescription": null,
         "lastUpdatedTimestamp": "20190714T155300Z"
     },
     "creationTimestamp": "20190714T155300Z",
     "expirationTimestamp": "20190715T155300Z"
}

Error codes

HTTP status code
Reason code
Description
400 BAD_REQUEST
TransactionAmountExceeded
You've exceeded the maximum charge amount allowed for the Charge Permission
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 true

If 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
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

Generic errors can be found here.

Get Charge

Get Charge details such as charge amount and authorization state. Use this operation to determine if authorization or capture was successful.

Request

curl "https://pay-api.amazon.com/:environment/:version/charges/:chargeId"
-H "authorization: Px2e5oHhQZ88vVhc0DO%2FsShHj8MDDg%3DEXAMPLESIGNATURE"
-X GET 

Request parameters

Name
Location
Description
chargeId
(required)

Type: string
Path Parameter
Charge identifier

Response

Returns HTTP 200 (OK) status if the operation was successful.

{
     "chargeId": "P21-1111111-1111111-C111111",
     "chargePermissionId": "P21-1111111-1111111",
     "chargeAmount": {
         "amount": "14.00",
         "currencyCode": "USD"
     },
     "captureAmount": {
         "amount": "14.00",
         "currencyCode": "USD"
     },
     "refundedAmount": {
         "amount": "0.00",
         "currencyCode": "USD"
     },
     "convertedAmount": "14.00",
     "conversionRate": "1.00",
     "softDescriptor": "Descriptor",
     "providerMetadata": {
         "providerReferenceId": null
     },
     "statusDetail":{
         "state": "Captured",
         "reasonCode": null,
         "reasonDescription": null,
         "lastUpdatedTimestamp": "20190714T155300Z"
     },
     "creationTimestamp": "20190714T155300Z",
     "expirationTimestamp": "20190715T155300Z"
}

Error codes

Generic errors can be found here.

Capture Charge

Capture payment on a Charge in the Authorized state. A successful Capture will move the Charge from Authorized to Captured state. The Captured state may be preceded by a temporary CaptureInitiated state if payment was captured more than 7 days after authorization. See asynchronous processing for more information. An unsuccessful Charge will move to a Declined state if payment was declined.

Request

curl "https://pay-api.amazon.com/:environment/:version/charges/:chargeId/capture" \
-X POST
-H "x-amz-pay-idempotency-key: AVLo5tI10BHgEk2jEXAMPLEKEY"
-H "authorization: Px2e5oHhQZ88vVhc0DO%2FsShHj8MDDg%3DEXAMPLESIGNATURE"
-d @request_body

Request Body

{
    "captureAmount": {
        "amount": "14.00",
        "currencyCode": "USD"
    },
    "softDescriptor": "Descriptor"
}

Request parameters

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>"

Max length: 16 characters

Response

Returns HTTP 200 (OK) status if the operation was successful.

{
     "chargeId": "P21-1111111-1111111-C111111",
     "chargePermissionId": "P21-1111111-1111111",
     "chargeAmount": {
         "amount": "14.00",
         "currencyCode": "USD"
     },
     "captureAmount": {
         "amount": "14.00",
         "currencyCode": "USD"
     },
     "refundedAmount": {
         "amount": "0.00",
         "currencyCode": "USD"
     },
     "convertedAmount": "14.00",
     "conversionRate": "1.00",
     "softDescriptor": "Descriptor",
     "providerMetadata": {
         "providerReferenceId": null
     },
     "statusDetail":{
         "state": "Captured",
         "reasonCode": null,
         "reasonDescription": null,
         "lastUpdatedTimestamp": "20190714T155300Z"
     },
     "creationTimestamp": "20190714T155300Z",
     "expirationTimestamp": "20190715T155300Z"
}

Error codes

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

Generic errors can be found here.

Cancel Charge

Moves Charge to Canceled state and releases any authorized payments. You can call this operation until Capture is initiated while Charge is in an AuthorizationInitiated or Authorized state.

Request

curl "https://pay-api.amazon.com/:environment/:version/charges/:chargeId/cancel" \
-X DELETE
-H "authorization: Px2e5oHhQZ88vVhc0DO%2FsShHj8MDDg%3DEXAMPLESIGNATURE"
-d @request_body

Request body

{
    "cancellationReason": "REASON DESCRIPTION"
}

Request parameters

Name
Location
Description
chargeId
(required)

Type: string
Path Parameter
Charge identifier
cancellationReason
(required)

Type: string
Body
Merchant-provided reason for canceling Charge

Response

Returns HTTP 200 (OK) status if the operation was successful.

{
     "chargeId": "P21-1111111-1111111-C111111",
     "chargePermissionId": "P21-1111111-1111111",
     "chargeAmount": {
         "amount": "14.00",
         "currencyCode": "USD"
     },
     "captureAmount": {
         "amount": "14.00",
         "currencyCode": "USD"
     },
     "refundedAmount": {
         "amount": "0.00",
         "currencyCode": "USD"
     },
     "convertedAmount": "14.00",
     "conversionRate": "1.00",
     "softDescriptor": "SOFT DESCRIPTOR",
     "providerMetadata": {
         "providerReferenceId": null
     },
     "statusDetail": {
         "state": "Canceled",
         "reasonCode": null,
         "reasonDescription": null,
         "lastUpdatedTimestamp": "20190714T155300Z"
     },
     "creationTimestamp": "20190714T155300Z",
     "expirationTimestamp": "20190715T155300Z"
}

Error codes

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

Generic errors can be found here.