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> amzn.com/pmts”

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: true

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


Copyright © 2009-2018 Amazon.com, Inc. or its affiliates. Amazon and Amazon.com are registered trademarks of Amazon.com, Inc. or its affiliates. All other trademarks are the property of their respective owners.