Authorize
Reserves a specified amount against the payment methods stored in the order reference.
Description
The Authorize operation reserves a specified amount against the payment methods stored in the order reference. To charge the payment methods, you must either set the CaptureNow request parameter to true or call the Capture operation after you call this operation. An authorisation is only valid for a particular time period, which is specified in the response of the operation. At the end of the time period, the authorisation expires and a notification is sent to you if you have set up Instant Payment Notifications. For more information about Instant Payment Notifications, see Instant Payment Notification (IPN) in the Amazon Pay and Login with Amazon integration guide. You can also query the details about an authorization by calling the GetAuthorizationDetails operation.
This operation has a maximum request quota of 10 and a restore rate of one request every second in the production environment. It has a maximum request quota of two and a restore rate of one request every two seconds in the sandbox environment. For definitions of throttling terminology and for a complete explanation of throttling, see Throttling: Limits to how often you can submit requests in the Amazon MWS Developer Guide.
This API call is idempotent. If called multiple times, with unchanged parameters (including AuthorizationReferenceId), the same result is produced.
Request parameters
For more information about the request parameters that are required for all Amazon MWS operations, see Required request parameters in the Amazon MWS Developer Guide.
| Parameter name | Required | Type | Description |
| AmazonOrderReferenceId | Yes | xs:string |
The order reference identifier.
This value is retrieved from the Amazon Button widget after the buyer has successfully authenticated with Amazon. |
| AuthorizationReferenceId | Yes | xs:string |
This identifier is defined by you and must be unique for every single API request, unless you plan to leverage the API idempotency.
Use only the following characters:
|
| AuthorizationAmount | Yes | Price |
Represents the amount to be authorised. Maximum value (for USD, GBP, EUR):
150000 |
| SellerAuthorizationNote | No | xs:string |
A description for the transaction that is shown in emails to the buyer. Appears only when CaptureNow is set to true.
Maximum: 255 characters |
| TransactionTimeout | No |
xs:non
negative Integer |
The maximum number of minutes allocated for the Authorize operation call to be processed, after which the authorisation is automatically declined and you cannot capture funds against the authorisation.
Note: In asynchronous mode, the Authorize operation always returns the State as Pending. The authorisation remains in this state until it is processed by Amazon. The processing time varies and can be a minute or more. After processing is complete, Amazon notifies you of the final processing status. For more information, see Instant Payment Notification (IPN) in the Amazon Pay and Login with Amazon integration guide. Valid values: Zero or integer values in multiples of five (5, 10, 15, etc.). Set the value to zero for synchronous mode. Set the value to greater than zero for asynchronous mode. TransactionTimeout values in synchronous mode:
|
| CaptureNow | No | xs:boolean |
Indicates whether to directly capture a specified amount against an order reference (without needing to call Capture and without waiting until the order ships). If set to true, specify the SellerAuthorizationNote. The captured amount is disbursed to your account in the next disbursement cycle.
Note: The Amazon Pay policy states that you charge your buyer when you fulfill the items in the order. You should not collect funds before fulfilling the order. Allowed values:
|
| SoftDescriptor | No | xs:string |
The description to be shown on the buyer's payment instrument statement if CaptureNow is set to true. The soft descriptor sent to the payment processor is: "AMZ* <soft descriptor specified here>".
Default: "AMZ*<SELLER_NAME> pay.amazon.com" Maximum: 16 characters |
Response elements
| Element name | Description |
| AuthorizationDetails |
Encapsulates details about the Authorisation object including the status, amount captured, and fee charged.
Type: AuthorizationDetails |
Examples
Sample query request
POST /OffAmazonPayments/2013-01-01 HTTP/1.1
Content-Type: x-www-form-urlencoded
Host: mws.amazonservices.com
User-Agent: <Your User Agent Header>
AWSAccessKeyId=AKIAFBM3LG5JEEXAMPLE
&Action=Authorize
&AmazonOrderReferenceId=P01-1234567-1234567
&AuthorizationAmount.Amount=94.50
&AuthorizationAmount.CurrencyCode=EUR
&AuthorizationReferenceId=test_authorize_1
&SellerAuthorizationNote=Lorem ipsum
&SellerId=YOUR_SELLER_ID_HERE
&SignatureMethod=HmacSHA256
&SignatureVersion=2
&Timestamp=2012-10-03T19:01:11Z
&TransactionTimeout=1440
&Version=2013-01-01
&Signature=WlQ708aqyHXMkoUBk69Hjxj8qdh3aDcqpY71hVgEXAMPLE
Sample response
<AuthorizeResponse xmlns=" https://mws.amazonservices.com/schema/
OffAmazonPayments/2013-01-01">
<AuthorizeResult>
<AuthorizationDetails>
<AmazonAuthorizationId>
P01-1234567-1234567-0000001
</AmazonAuthorizationId>
<AuthorizationReferenceId>test_authorize_1</AuthorizationReferenceId>
<SellerAuthorizationNote>Lorem ipsum</SellerAuthorizationNote>
<AuthorizationAmount>
<CurrencyCode>EUR</CurrencyCode>
<Amount>94.50</Amount>
</AuthorizationAmount>
<AuthorizationFee>
<CurrencyCode>EUR</CurrencyCode>
<Amount>0</Amount>
</AuthorizationFee>
<SoftDecline>true</SoftDecline>
<AuthorizationStatus>
<State>Pending</State>
<LastUpdateTimestamp>2012-11-03T19:10:16Z</LastUpdateTimestamp>
</AuthorizationStatus>
<CreationTimestamp>2012-11-02T19:10:16Z</CreationTimestamp>
<ExpirationTimestamp>2012-12-02T19:10:16Z</ExpirationTimestamp>
</AuthorizationDetails>
</AuthorizeResult>
<ResponseMetadata>
<RequestId>b4ab4bc3-c9ea-44f0-9a3d-67cccef565c6</RequestId>
</ResponseMetadata>
</AuthorizeResponse>