AuthorizeOnBillingAgreement

Reserves a specified amount against the payment methods stored in the billing agreement.

Description

The AuthorizeOnBillingAgreement operation reserves a specified amount against the payment methods stored in the billing agreement. 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 authorization 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 authorization expires and a notification is sent to you if you have set up Instant Payment Notifications (IPNs). 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.

Note: This is a convenience operation that creates and confirms an Order Reference object, requests an authorization, and then closes the order reference.

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.

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
AmazonBillingAgreementId Yes xs:string The billing agreement identifier.

This value is retrieved from the Amazon Button, AddressBook, or Wallet widgets.
AuthorizationReferenceId Yes xs:string The identifier for this authorization transaction that you specify. This identifier must be unique for all your authorization transactions.

We recommend that you use only the following characters:
  • lowercase a-z,
  • uppercase A-Z,
  • numbers 0-9,
  • dash (-)
  • underscore (_)
Maximum: 32 characters
AuthorizationAmount Yes Price Represents the amount to be authorized.
SellerAuthorizationNote No xs:string A description for the transaction that is shown in emails to the buyer.

Maximum: 255 characters
TransactionTimeout No xs:nonNegativeInteger The number of minutes after which the authorization is automatically closed and you cannot capture funds against the authorization.

Valid values: Zero or integral values in multiples of five (5, 10, 15, etc.)

Minimum: 0

Maximum: 1440

Default: 1440

A value of zero always returns a synchronous Open or Declined status. A non-zero value always returns a Pending status, and you will receive the final processing status by Instant Payment Notification (IPN).
CaptureNow No xs:boolean Indicates whether to directly capture the amount specified by the AuthorizationAmount request parameter against an order reference (without needing to call Capture and without waiting until the order ships). The captured amount is disbursed to your account in the next disbursement cycle.

Allowed values:
  • true-The specified amount is directly captured. You do not need to call the Capture operation.
  • false-You must call the Capture operation to capture the funds specified in this authorization.
Default: false
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
SellerNote No xs:string Represents a description of the order that is shown in emails to the buyer.

Maximum: 1024 characters
PlatformId No xs:string Represents the SellerId of the Solution Provider that developed the ecommerce platform.

This value is used only by solution providers, for whom it is required. It should not be provided by merchants creating their own custom integration. Do not specify the SellerId of the merchant for this request parameter.

If you are a merchant, do not enter a PlatformId.

Type: xs:string
SellerOrderAttributes No SellerOrderAttributes Provides more context about an order that is represented by an Order Reference object.
InheritShippingAddress No xs:boolean Specifies whether to inherit the shipping address details from the object represented by the Id request parameter.

Default: false

Note: Set this value to true if the order is shipping physical products.

Response elements

Element name Description
AuthorizationDetails Encapsulates details about the Authorization object including the status, amount captured, and fee charged.

Type: AuthorizationDetails
AmazonOrderReferenceId The order reference identifier.

Type: xs:string

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=AKIAJKYFSJU7PEXAMPLE
&Action=AuthorizeOnBillingAgreement
&AmazonBillingAgreementId=C01-1234567-1234567
&AuthorizationAmount.Amount=10
&AuthorizationAmount.CurrencyCode=USD
&AuthorizationReferenceId=test_authorize_1
&InheritShippingAddress=true
&MWSAuthToken=amzn.mws.4ea38b7b-f563-7709-4bae-87aeaEXAMPLE
&SellerAuthorizationNote=For November Order
&SellerId=YOUR_SELLER_ID_HERE
&SellerOrderAttributes.CustomInformation=Example Information
&SellerOrderAttributes.SellerOrderId=testSellerOrderId
&SellerOrderAttributes.StoreName=testStore
&SignatureMethod=HmacSHA256
&SignatureVersion=2
&Timestamp=2012-10-03T19%3A01%3A11Z
&TransactionTimeout=60
&Version=2013-01-01
&Signature=WlQ708aqyHXMkoUBk69Hjxj8qdh3aDcqpY71hVgEXAMPLE

Sample response


<AuthorizeOnBillingAgreementResponse
  xmlns="https://mws.amazonservices.com/
        schema/OffAmazonPayments_Sandbox/2013-01-01">
<AuthorizeOnBillingAgreementResult>
  <AuthorizationDetails>
    <AmazonAuthorizationId>C01-1234567-1234567-A006334</AmazonAuthorizationId>
    <AuthorizationReferenceId>AuthReference4</AuthorizationReferenceId>
    <SellerAuthorizationNote>ForNovemberOrder</SellerAuthorizationNote>
    <AuthorizationAmount>
      <Amount>20.00</Amount>
      <CurrencyCode>USD</CurrencyCode>
    </AuthorizationAmount>
    <CapturedAmount>
      <Amount>0</Amount>
      <CurrencyCode>USD</CurrencyCode>
    </CapturedAmount>
    <AuthorizationFee>
       <Amount>0.00</Amount>
      <CurrencyCode>USD</CurrencyCode>
    </AuthorizationFee>
	<SoftDecline>true</SoftDecline>
	<AuthorizationStatus>
      <LastUpdateTimestamp>2013-12-05T00:21:19Z</LastUpdateTimestamp>
      <State>Pending</State>
    </AuthorizationStatus>
    <CreationTimestamp>2013-12-01T00:21:19Z</CreationTimestamp>
    <ExpirationTimestamp>2014-01-01T00:21:19Z</ExpirationTimestamp>
    <CaptureNow>false</CaptureNow>
  </AuthorizationDetails>
<AmazonOrderReferenceId>S01-1234569-1234568</AmazonOrderReferenceId>
</AuthorizeOnBillingAgreementResult>
<ResponseMetadata>
  <RequestId>2649e9a4-9a1e-4097-8ce5-bcbc307e5eb8</RequestId>
</ResponseMetadata>
</AuthorizeOnBillingAgreementResponse>

See also