fahoby

Amazon Marketplace Web Service
Off-Amazon Payments API Section
Reference (Version 2013-01-01)

2 Amazon Marketplace Web Service Off-Amazon Payments API Section Reference (Version 2013-01-01) 2
Amazon Marketplace Web Service Off-Amazon Payments API Section Reference (Version 2013-01-01) 2
Contents
Amazon Marketplace Web Service Off-Amazon Payments API Section Reference (Version
2013-01-01)...................................................................................................................................................... 6
What you should know about the Amazon MWS Off-Amazon Payments API section............................7
CreateOrderReferenceForId........................................................................................................................ 10
Description.................................................................................................................................................................................................10
Request parameters..................................................................................................................................................................................10
Response elements...................................................................................................................................................................................11
Examples................................................................................................................................................................................................... 11
Related topics............................................................................................................................................................................................12
GetBillingAgreementDetails........................................................................................................................ 13
Description.................................................................................................................................................................................................13
Examples................................................................................................................................................................................................... 14
Related topics............................................................................................................................................................................................15
SetBillingAgreementDetails.........................................................................................................................16
Description.................................................................................................................................................................................................16
Examples................................................................................................................................................................................................... 16
Related topics............................................................................................................................................................................................17
ConfirmBillingAgreement............................................................................................................................ 18
Description.................................................................................................................................................................................................18
Examples................................................................................................................................................................................................... 18
Related topics............................................................................................................................................................................................19
ValidateBillingAgreement............................................................................................................................ 20
Description.................................................................................................................................................................................................20
Examples................................................................................................................................................................................................... 21
Related topics............................................................................................................................................................................................21
AuthorizeOnBillingAgreement.................................................................................................................... 22
Description.................................................................................................................................................................................................22
Examples................................................................................................................................................................................................... 23
Related topics............................................................................................................................................................................................25
CloseBillingAgreement................................................................................................................................ 26
Description.................................................................................................................................................................................................26
Examples................................................................................................................................................................................................... 26

Related topics............................................................................................................................................................................................27
SetOrderReferenceDetails........................................................................................................................... 28
Description.................................................................................................................................................................................................28
Examples................................................................................................................................................................................................... 28
Related topics............................................................................................................................................................................................29
GetOrderReferenceDetails...........................................................................................................................30
Description.................................................................................................................................................................................................30
Examples................................................................................................................................................................................................... 30
Related topics............................................................................................................................................................................................31
ConfirmOrderReference...............................................................................................................................32
Description.................................................................................................................................................................................................32
Examples................................................................................................................................................................................................... 32
Related topics............................................................................................................................................................................................33
CancelOrderReference.................................................................................................................................34
Description.................................................................................................................................................................................................34
Examples................................................................................................................................................................................................... 34
Related topics............................................................................................................................................................................................35
CloseOrderReference...................................................................................................................................36
Description.................................................................................................................................................................................................36
Examples................................................................................................................................................................................................... 36
Related topics............................................................................................................................................................................................37
Authorize....................................................................................................................................................... 38
Description.................................................................................................................................................................................................38
Examples................................................................................................................................................................................................... 39
Related topics............................................................................................................................................................................................40
GetAuthorizationDetails...............................................................................................................................41
Description.................................................................................................................................................................................................41
Examples................................................................................................................................................................................................... 41
Related topics............................................................................................................................................................................................42
Capture.......................................................................................................................................................... 43
Description.................................................................................................................................................................................................43
Examples................................................................................................................................................................................................... 44
Related topics............................................................................................................................................................................................45
GetCaptureDetails........................................................................................................................................ 46

Description.................................................................................................................................................................................................46
Related topics............................................................................................................................................................................................46
CloseAuthorization.......................................................................................................................................47
Description.................................................................................................................................................................................................47
Examples................................................................................................................................................................................................... 47
Related topics............................................................................................................................................................................................48
Refund........................................................................................................................................................... 49
Description.................................................................................................................................................................................................49
Examples................................................................................................................................................................................................... 50
Related topics............................................................................................................................................................................................51
GetRefundDetails..........................................................................................................................................52
Description.................................................................................................................................................................................................52
Related topics............................................................................................................................................................................................52
GetServiceStatus..........................................................................................................................................53
Description.................................................................................................................................................................................................53
Examples................................................................................................................................................................................................... 53
Related topics............................................................................................................................................................................................54
Off-Amazon Payments Datatypes...............................................................................................................55
Address......................................................................................................................................................................................................55
AuthorizationDetails...................................................................................................................................................................................56
BillingAgreementAttributes........................................................................................................................................................................ 58
BillingAgreementDetails.............................................................................................................................................................................58
BillingAgreementLimits.............................................................................................................................................................................. 60
BillingAgreementStatus............................................................................................................................................................................. 60
Buyer......................................................................................................................................................................................................... 61
CaptureDetails........................................................................................................................................................................................... 61
Constraint.................................................................................................................................................................................................. 62
Destination.................................................................................................................................................................................................62
OrderReferenceAttributes..........................................................................................................................................................................63
OrderReferenceDetails.............................................................................................................................................................................. 63
OrderReferenceStatus...............................................................................................................................................................................65
OrderTotal..................................................................................................................................................................................................65
Price...........................................................................................................................................................................................................66
RefundDetails............................................................................................................................................................................................ 66
SellerBillingAgreementAttributes............................................................................................................................................................... 67
SellerOrderAttributes................................................................................................................................................................................. 67
Status.........................................................................................................................................................................................................68
Billing Agreement Constraints................................................................................................................... 70
Billing Agreement States and Reason Codes.......................................................................................... 71
Order Reference Constraints......................................................................................................................73

Order Reference States and Reason Codes............................................................................................. 74
Authorization States and Reason Codes.................................................................................................. 76
Capture States and Reason Codes............................................................................................................78
Refund States and Reason Codes.............................................................................................................79
Error codes................................................................................................................................................... 80
Client library updates.................................................................................................................................. 82

Amazon Marketplace Web Service Off-
Amazon Payments API Section Reference
(Version 2013-01-01)
Copyright © 2013-2014 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.
Last updated: 2014-12-15

What you should know about the Amazon
MWS Off-Amazon Payments API section
Overview
The Off-Amazon Payments API section helps you to process payments for purchases made by buyers on your website
using the Login and Pay with Amazon service. This API section enables you to programmatically retrieve shipping and
payment information provided by the buyer from their Amazon account. It allows you to authorize, capture, and refund
payments, enabling a variety of payments scenarios.
Note: The Off-Amazon Payments API section is only applicable to payments made through the Login and Pay
with Amazon service offered by Amazon Payments. You cannot use this API section to process payments for
Amazon Marketplace, Amazon Webstore, or Checkout by Amazon.
Using the Off-Amazon Payments API section of Amazon Marketplace Web Service (Amazon MWS), you can:
• Create and manage a billing agreement to secure the buyer's permission to charge their selected payment method on
a recurring basis without requiring their permission each time. You typically do not need a billing agreement if your
buyers will visit your site each time they place an order or if you do not need to enable automatic payments. With a
billing agreement, you can:
• Obtain the shipping information from the buyer so that you can calculate shipping charges and tax for automatic
payments.
• Obtain information about the amount that you are allowed to charge a buyer each month using Amazon
Payments.
• Set the description and other optional information about the automatic payment.
• Confirm the billing agreement after the buyer has signed up for automatic payments on your site.
• Close the billing agreement if you or the buyer want to terminate the automatic payment relationship.
• Create and manage a limited representation of an order, hereafter referred to as an order reference or Order
Reference object, through the Login and Pay with Amazon service. With an order reference, you can:
• Obtain shipping information from the buyer so you can calculate shipping charges and tax.
• Set the amount, description, and other optional information for the order.
• Confirm the order once the buyer has finished placing an order on your website.
• Cancel the order at the request of either the buyer or yourself.
• Close the order after it has been processed and completed.
• Programmatically authorize, capture, and refund money for purchases made by the buyer at your website.
For more information about integrating your website with the Login and Pay with Amazon product, see the Login and
Pay with Amazon Integration Guide. The "Getting started" section will walk you through a complete purchase from
beginning to end.
Terminology
The following table defines terminology for this API section:
Term Description
Billing Agreement A billing agreement, or Billing Agreement object, tracks the
buyer’s preferred payment method, preferred shipping address, and
authorization for automatic payments. A billing agreement can have an
indefinite lifetime and support an indefinite number of purchases.
Order Reference An order reference, or Order Reference object, is a record of each
purchase made by the buyer. It tracks the payment method, shipping

Term Description
address, and the amount that the buyer agreed to pay for that purchase.
For each automatic payment, an order reference is created from the
shipping and payment information stored in the billing agreement. An
order reference is valid for 180 days and applies to only one purchase.
You may have up to 10 authorizations on an order reference.
Authorization An authorization, or Authorization object, tracks the availability
of funds and secures them for future payment against the payment
instrument(s) stored in the order reference.
Capture A capture, or Capture object, tracks the movement of funds previously
secured by authorization from the buyer’s payment instrument(s) to the
seller’s account.
Refund A refund, or Refund object, tracks the movement of previously captured
funds from the seller’s account to the buyer’s payment instrument(s).
Transaction A transaction is a generic term that is used for all the types of payment
events against an order reference. This includes authorizations, captures,
refunds, A-to-z Claims, charge backs, fees, and other miscellaneous
transactions.
Endpoints
All API calls to the Off-Amazon Payments API section service should be submitted to the following endpoints:
• Germany (DE) and United Kingdom (UK):
• Production: https://mws-eu.amazonservices.com/OffAmazonPayments/2013-01-01/
• Sandbox: https://mws-eu.amazonservices.com/OffAmazonPayments_Sandbox/2013-01-01/
• United States (US):
• Production: https://mws.amazonservices.com/OffAmazonPayments/2013-01-01/
• Sandbox: https://mws.amazonservices.com/OffAmazonPayments_Sandbox/2013-01-01/
Operations
The Off-Amazon Payments API section contains the following operations:
Operation Description
CreateOrderReferenceForId Creates an order reference for the given object.
GetBillingAgreementDetails Returns details about the Billing Agreement object and its current state.
SetBillingAgreementDetails Sets billing agreement details such as a description of the agreement and
other information about the seller.
ConfirmBillingAgreement Confirms that the billing agreement is free of constraints and all
required information has been set on the billing agreement.
ValidateBillingAgreement Validates the status of the BillingAgreement object and the payment
method associated with it.
AuthorizeOnBillingAgreement Reserves a specified amount against the payment method(s) stored in
the billing agreement.
CloseBillingAgreement Confirms that you want to terminate the billing agreement with the
buyer and that you do not expect to create any new order references or
authorizations on this billing agreement.

Operation Description
SetOrderReferenceDetails Sets order reference details such as the order total and a description for
the order.
GetOrderReferenceDetails Returns details about the Order Reference object and its current state.
ConfirmOrderReference Confirms that the order reference is free of constraints and all required
information has been set on the order reference.
CancelOrderReference Cancels a previously confirmed order reference.
CloseOrderReference Confirms that an order reference has been fulfilled (fully or partially)
and that you do not expect to create any new authorizations on this order
reference.
Authorize Reserves a specified amount against the payment method(s) stored in
the order reference.
GetAuthorizationDetails Returns the status of a particular authorization and the total amount
captured on the authorization.
Capture Captures funds from an authorized payment instrument.
GetCaptureDetails Returns the status of a particular capture and the total amount refunded
on the capture.
CloseAuthorization Closes an authorization.
Refund Refunds a previously captured amount.
GetRefundDetails Returns the status of a particular refund.

CreateOrderReferenceForId
Creates an order reference for the given object.
Description
The CreateOrderReferenceForId operation is used to create an Order Reference object from the object represented
by the Id and IdType request parameters.
For order references created from a Billing Agreement object, only one order reference can be created while the billing
agreement is in the Draft state. Any number of order references can be created once the billing agreement is in the
Open state. The buyer, shipping address, and payment method for the order reference are populated from the billing
agreement. To create an Order Reference object in the Confirmed state, set the ConfirmNow request parameter to
true.
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.
Name Description Required Valid values
Id The identifier of the object to be used to
create an order reference.
Type: xs:string
Yes Currently, the only accepted value is a
billing agreement identifier. This value
is retrieved from the Amazon Button,
AddressBook, or Wallet widgets.
IdType The type of the object represented by
the Id request parameter.
Type: xs:string
Yes IdType values:
• BillingAgreement - Specifies that
Id is a Billing Agreement identifier.
InheritShippingAddress Specifies whether to inherit the
shipping address details from the object
represented by the Id request parameter.
Type: xs:boolean
No Default: true
ConfirmNow Indicates whether to directly confirm
the requested order reference.
Type: xs:boolean
No ConfirmNow values:
• true - The order reference
is directly confirmed. You
do not need to call the
ConfirmOrderReference
operation.
• false - You must call the
operation to confirm the order
reference.
Default: false
OrderReferenceAttributes The seller-specified attributes of the
order reference.
Type: OrderReferenceAttributes
Required only if
ConfirmNow is
true.

Response elements
Name Description
OrderReferenceDetails Encapsulates details about the Order Reference object and its current
state.
Type: OrderReferenceDetails
Examples
Example 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=CreateOrderReferenceForId
&Id=C01-1234567-1234567
&IdType=BillingAgreement
&MWSAuthToken=amzn.mws.4ea38b7b-f563-7709-4bae-87aeaEXAMPLE
&SellerId=YOUR_SELLER_ID_HERE
&SignatureMethod=HmacSHA256
&SignatureVersion=2
&Timestamp=2012-10-03T19%3A01%3A11Z
&Version=2013-01-01
&Signature=WlQ708aqyHXMkoUBk69Hjxj8qdh3aDcqpY71hVgEXAMPLE
Example response
<CreateOrderReferenceForIdResponse
xmlns="http://mws.amazonservices.com/
schema/OffAmazonPayments_Sandbox/2013-01-01">
<CreateOrderReferenceForIdResult>
<OrderReferenceDetails>
<AmazonOrderReferenceId>S01-1234567-1234567</AmazonOrderReferenceId>
<CreationTimestamp>2013-12-05T00:21:19Z</CreationTimestamp>
<ExpirationTimestamp>2014-05-05T00:21:19Z</ExpirationTimestamp>
<OrderReferenceStatus>
<State>Draft</State>
</OrderReferenceStatus>
<Destination>
<DestinationType>Physical</DestinationType>
<PhysicalDestination>
<City>New York</City>
<StateOrRegion>NY</StateOrRegion>
<PostalCode>10101-9876</PostalCode>
<CountryCode>US</CountryCode>
</PhysicalDestination>
</Destination>
<ReleaseEnvironment>Live</ReleaseEnvironment>
</OrderReferenceDetails>
</CreateOrderReferenceForIdResult>
<ResponseMetadata>
<RequestId>5f20169b-7ab2-11df-bcef-d35615e2b044</RequestId>
</ResponseMetadata>
</CreateOrderReferenceForIdResponse>

Related topics
What you should know about the Amazon MWS Off-Amazon Payments API section

GetBillingAgreementDetails
Returns details about the Billing Agreement object and its current state.
Description
The GetBillingAgreementDetails operation returns details about the Billing Agreement object and its current state.
A Billing Agreement object provides details about the following:
• Buyer
• Description
• Destination (optional)
• Seller billing agreement details (optional)
• List of constraints (optional)
This operation has a maximum request quota of 20 and a restore rate of two requests every second in the production
environment. It has a maximum request quota of five and a restore rate of one request every second in the sandbox
Request parameters
AmazonBillingAgreementId The billing agreement identifier.
Type: xs:string
Yes This value is retrieved from the Amazon
Button, AddressBook, or Wallet
widgets.
AddressConsentToken The buyer address consent
token. You must provide a valid
AddressConsentToken if you want
to get the full shipping address before
the billing agreement is confirmed.
Otherwise you will only receive
the city, state, postal code, and
country before you confirm the billing
agreement.
Type: xs:string
No This value is retrieved from the
Amazon Button widget after the buyer
has successfully authenticated with
Amazon.
Response elements
Name Description
BillingAgreementDetails Encapsulates details about the Billing Agreement object and its current
state.
Type: BillingAgreementDetails

Examples
&Action=GetBillingAgreementDetails
&AmazonBillingAgreementId=C01-8824045-7416542
&SignatureVersion=2
&Timestamp=2013-12-11T10%3A38%3A44.000Z
&Version=2013-01-01
&Signature=gP11oEBaaiQdASWsLDyid18Wn%2BB%2FKZQQtKgpHCtEXAMPLE
Example response
<GetBillingAgreementDetailsResponse
xmlns="https://mws.amazonservices.com/
<GetBillingAgreementDetailsResult>
<BillingAgreementDetails>
<AmazonBillingAgreementId>C01-8824045-7416542</AmazonBillingAgreementId>
<Constraints>
<ConstraintID>BuyerConsentNotSet</ConstraintID>
<Description>
Buyer has not given consent for this Billing Agreement.
</Description>
</Constraints>
<Destination>
<City>Seattle</City>
<PostalCode>98104</PostalCode>
<StateOrRegion>WA</StateOrRegion>
</Destination>
<BillingAgreementLimits>
<AmountLimitPerTimePeriod>
<CurrencyCode>USD</CurrencyCode>
<Amount>500</Amount>
</AmountLimitPerTimePeriod>
<TimePeriodStartDate>2013-12-01T00:00:00Z</TimePeriodStartDate>
<TimePeriodEndDate>2014-01-01T00:00:00Z</TimePeriodEndDate>
<CurrentRemainingBalance>
<Amount>94.50</Amount>
</CurrentRemainingBalance>
</BillingAgreementLimits>
<BillingAgreementStatus>
</BillingAgreementStatus>
<ReleaseEnvironment>Sandbox</ReleaseEnvironment>

</BillingAgreementDetails>
</GetBillingAgreementDetailsResult>
<ResponseMetadata>
<RequestId>4a08624e-fffa-4fe7-bc19-ef9330c42f6a</RequestId>
</ResponseMetadata>
</GetBillingAgreementDetailsResponse>
Related topics

SetBillingAgreementDetails
Sets billing agreement details such as a description of the agreement and other information about the seller.
Description
Call the SetBillingAgreementDetails operation to specify billing agreement details such as a description of the
agreement and other information about the seller.
Request parameters
Type: xs:string
widgets.
BillingAgreementAttributes The seller-specified attributes of the
billing agreement.
Type: BillingAgreementAttributes
Yes
Response elements
Name Description
BillingAgreementDetails Encapsulates details about the Billing Agreement object and its current
state.
Type: BillingAgreementDetails
Examples
&Action=SetBillingAgreementDetails
&BillingAgreementAttributes.PlatformId=PLATFORM_ID_HERE
&BillingAgreementAttributes.SellerNote=APPROVE%20LITE%20APPROVE%20HEAVY
&BillingAgreementAttributes.SellerBillingAgreementAttributes
.CustomInformation=Example%20Customer%20Info

&BillingAgreementAttributes.SellerBillingAgreementAttributes
.StoreName=Test%20Store%20Name
&SignatureVersion=2
&Timestamp=2013-12-11T10%3A57%3A18.000Z
&Version=2013-01-01
&Signature=Z0ZVgWu0ICF4FLxt1mTjyK%2BjdYG6Kmm8JxLTfsQEXAMPLE
Example response
<SetBillingAgreementDetailsResponse
<SetBillingAgreementDetailsResult>
<BillingAgreementDetails>
<AmazonBillingAgreementId>C01-8824045-7416542</AmazonBillingAgreementId>
<Destination>
<City>Seattle</City>
<PostalCode>98104</PostalCode>
<StateOrRegion>WA</StateOrRegion>
</Destination>
<BillingAgreementConsent>true</BillingAgreementConsent>
<BillingAgreementLimits>
<AmountLimitPerTimePeriod>
</AmountLimitPerTimePeriod>
<TimePeriodStartDate>2013-12-01T00:00:00Z</TimePeriodStartDate>
<TimePeriodEndDate>2013-12-23T23:59:59Z</TimePeriodEndDate>
<CurrentRemainingBalance>
</CurrentRemainingBalance>
</BillingAgreementLimits>
<ReleaseEnvironment>Sandbox</ReleaseEnvironment>
<SellerNote>APPROVE LITE APPROVE HEAVY</SellerNote>
<SellerBillingAgreementAttributes>
<CustomInformation>Example Customer Info</CustomInformation>
<StoreName>Test Store Name</StoreName>
</SellerBillingAgreementAttributes>
</BillingAgreementDetails>
</SetBillingAgreementDetailsResult>
<ResponseMetadata>
<RequestId>bab23c81-f7c9-4d1a-b76b-fbcec07e47f5</RequestId>
</ResponseMetadata>
</SetBillingAgreementDetailsResponse>
Related topics

ConfirmBillingAgreement
Confirms that the billing agreement is free of constraints and all required information has been set on the billing
agreement.
Description
Call the ConfirmBillingAgreement operation once the billing agreement is free of constraints, indicating
that all required information has been set on the billing agreement. On successful completion of the
ConfirmBillingAgreement call, the billing agreement moves to the Open state.
You cannot modify the billing agreement once it is confirmed. However, the buyer can still update the shipping address
and payment method associated with the billing agreement.
AuthorizeOnBillingAgreement requests are only accepted on a billing agreement when it is in Open state. You can
create multiple order references by calling the CreateOrderReferenceForId operation when the billing agreement is
in the Open state.
Request parameters
Type: xs:string
widgets.
Response elements
This operation only returns the standard response elements.
Examples
&Action=ConfirmBillingAgreement

&SignatureVersion=2
&Timestamp=2013-12-11T11%3A37%3A19.000Z
&Version=2013-01-01
&Signature=ET6V00R4fr2inSDky4olLrlS1XrQfdrV9Bj%2BiWeEXAMPLE
Example response
<ConfirmBillingAgreementResponse
<ResponseMetadata>
<RequestId>2649e9a4-9a1e-4097-8ce5-bcbc307e5eb8</RequestId>
</ResponseMetadata>
</ConfirmBillingAgreementResponse>
Related topics

ValidateBillingAgreement
Validates the status of the BillingAgreement object and the payment method associated with it.
Description
Call the ValidateBillingAgreement operation once the billing agreement moves to the Open state (that is, after
a successful call to the ConfirmBillingAgreement operation). This operation validates the status of the billing
agreement and the validity of the payment method associated with the billing agreement.
Request parameters
Type: xs:string
widgets.
Response elements
Name Description
ValidationResult ValidationResult values:
• Success - Indicates that the validation succeeded.
• Failure - Indicates that the validation failed.
Type: xs:string
FailureReasonCode Describes the reason for the ValidationResult failure.
FailureReasonCode values:
• InvalidPaymentMethod - The payment method associated with the
billing agreement is invalid.
• ValidationTimedOut - The validation timed out and could not be
completed.
Returned only if ValidationResult is Failure.
Type: xs:string
BillingAgreementStatus Indicates the current status of the billing agreement.
Type: BillingAgreementStatus

Examples
&Action=ValidateBillingAgreement
&SignatureVersion=2
&Timestamp=2013-12-11T10%3A38%3A44.000Z
&Version=2013-01-01
&Signature=gP11oEBaaiQdASWsLDyid18Wn%2BB%2FKZQQtKgpHCtEXAMPLE
Example response
<ValidateBillingAgreementResponse
<ValidateBillingAgreementResult>
<ValidationResult>Failure</ValidationResult>
<FailureReasonCode>InvalidPaymentMethod</FailureReasonCode>
<LastUpdateTimestamp>2013-12-05T00:21:19Z</LastUpdateTimestamp>
<State>Suspended</State>
<ReasonCode>InvalidPaymentMethod</ReasonCode>
<ReasonDescription>Payment method is not valid.</ReasonDescription>
</ValidateBillingAgreementResult>
<ResponseMetadata>
<RequestId>f42df4b1-8047-11df-8d5c-bf56a38ef3b4</RequestId>
</ResponseMetadata>
</ValidateBillingAgreementResponse>
Related topics

AuthorizeOnBillingAgreement
Reserves a specified amount against the payment method(s) stored in the billing agreement.
Description
The AuthorizeOnBillingAgreement operation reserves a specified amount against the payment method(s) stored
in the billing agreement. To charge the payment method(s), 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 "Synchronizing your systems with Amazon Payments" in the Login and Pay 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.
Request parameters
Type: xs:string
widgets.
AuthorizationReferenceId The identifier for this authorization
transaction that you specify. This
identifier must be unique for all your
authorization transactions.
Type: xs:string
Yes Amazon recommends that you use only
the following characters: lowercase a-z,
uppercase A-Z, numbers 0-9, dash (-),
or underscore (_).
Maximum: 32 characters
AuthorizationAmount Represents the amount to be authorized.
Type: Price
Yes
SellerAuthorizationNote A description for the transaction that is
displayed in emails to the buyer.
Type: xs:string
No Maximum: 255 characters
TransactionTimeout The number of minutes after which
the authorization will automatically
be closed and you will not be able to
capture funds against the authorization.
Type: xs:nonNegativeInteger
No 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 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.
Type: xs:boolean
No CaptureNow 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 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>”.
Type: xs:string
No Default: “AMZ*<SELLER_NAME>
amzn.com/pmts WA”
SellerNote Represents a description of the order
that is displayed in emails to the buyer.
Type: xs:string
PlatformId Represents the unique identifier of the
seller's platform.
Type: xs:string
No The encrypted SellerId for the account
that is associated with the platform or
plugin being used by the seller.
SellerOrderAttributes Provides more context about an
order that is represented by an Order
Reference object.
Type: SellerOrderAttributes
No
InheritShippingAddress Specifies whether to inherit the
shipping address details from the object
represented by the Id request parameter.
Type: xs:boolean
No Default: true
Response elements
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

&Action=AuthorizeOnBillingAgreement
&AuthorizationAmount.Amount=10
&AuthorizationAmount.CurrencyCode=USD
&AuthorizationReferenceId=test_authorize_1
&InheritShippingAddress=true
&SellerAuthorizationNote=For November Order
&SellerOrderAttributes.CustomInformation=Example Information
&SellerOrderAttributes.SellerOrderId=testSellerOrderId
&SellerOrderAttributes.StoreName=testStore
&SignatureVersion=2
&Timestamp=2012-10-03T19%3A01%3A11Z
&TransactionTimeout=60
&Version=2013-01-01
Example response
<AuthorizeOnBillingAgreementResponse
<AuthorizeOnBillingAgreementResult>
<AuthorizationDetails>
<AmazonAuthorizationId>C01-1234567-1234567-A006334</
AmazonAuthorizationId>
<AuthorizationReferenceId>AuthReference4</AuthorizationReferenceId>
<SellerAuthorizationNote>ForNovemberOrder</SellerAuthorizationNote>
<AuthorizationAmount>
</AuthorizationAmount>
<CapturedAmount>
<Amount>0</Amount>
</CapturedAmount>
<AuthorizationFee>
</AuthorizationFee>
<AuthorizationStatus>
<State>Pending</State>
</AuthorizationStatus>
<CaptureNow>false</CaptureNow>
</AuthorizationDetails>
<AmazonOrderReferenceId>S01-1234569-1234568</AmazonOrderReferenceId>
</AuthorizeOnBillingAgreementResult>
<ResponseMetadata>
</ResponseMetadata>
</AuthorizeOnBillingAgreementResponse>

Related topics

CloseBillingAgreement
Confirms that you want to terminate the billing agreement with the buyer and that you do not expect to create any new
order references or authorizations on this billing agreement.
Description
Call the CloseBillingAgreement operation on a previously confirmed billing agreement to indicate that you want
to terminate the billing agreement with the buyer and that you do not expect to create any new order references or
authorizations on this billing agreement. All open authorizations on the billing agreement can still be used to capture
funds.
After successfully calling this operation, the billing agreement moves to the Closed state.
Request parameters
Type: xs:string
widgets.
ClosureReason Describes the reason for closing the
billing agreement.
Type: xs:string
Response elements
Examples
&Action=CloseBillingAgreement
&ClosureReason=Closing%20OR%20for%20Test

&SignatureVersion=2
&Timestamp=2013-12-11T12%3A32%3A42.000Z
&Version=2013-01-01
&Signature=yrpMpoDfGLu567t611z27v4yJ8SURIVMKcy26sJEXAMPLE
Example response
<CloseBillingAgreementResponse
<ResponseMetadata>
</ResponseMetadata>
</CloseBillingAgreementResponse>
Related topics

SetOrderReferenceDetails
Sets order reference details such as the order total and a description for the order.
Description
Call the SetOrderReferenceDetails operation to specify order details such as the amount of the order, a description
of the order, and other order attributes.
Request parameters
Name Description Required Valid Values
AmazonOrderReferenceId The order reference identifier retrieved
from the Amazon Button widget.
Type: xs:string
Yes This value is retrieved from the
Amazon.
OrderReferenceAttributes The seller-specified attributes of the
order reference.
Type: OrderReferenceAttributes
Yes
Response elements
Name Description
state.
Examples
AWSAccessKeyId=0GS7553JW74RRM612K02EXAMPLE
&Action=SetOrderReferenceDetails
&AmazonOrderReferenceId=P01-1234567-1234567
&OrderReferenceAttributes.OrderTotal.Amount=106
&OrderReferenceAttributes.OrderTotal.CurrencyCode=USD

&OrderReferenceAttributes.PlatformId=PLATFORM_ID_HERE
&OrderReferenceAttributes.SellerNote=Lorem%20ipsum
&OrderReferenceAttributes.SellerOrderAttributes.SellerOrderId=5678-23
&SignatureVersion=2
&Timestamp=2012-11-05T19%3A01%3A11Z
&Version=2013-01-01
&Signature=2RPzkOgQmDybUjk0dA54maCEXAMPLE
Example response
<SetOrderReferenceDetailsResponse xmlns="https://mws.amazonservices.com/
schema/OffAmazonPayments/2013-01-01">
<SetOrderReferenceDetailsResult>
<AmazonOrderReferenceId>P01-1234567-1234567</AmazonOrderReferenceId>
<OrderTotal>
</OrderTotal>
<SellerOrderAttributes>
<SellerOrderId>5678-23</SellerOrderId>
</SellerOrderAttributes>
<SellerNote>Lorem ipsum</SellerNote>
<Destination>
</Destination>
</SetOrderReferenceDetailsResult>
<ResponseMetadata>
</ResponseMetadata>
</SetOrderReferenceDetailsResponse>
Related topics
GetOrderReferenceDetails
CancelOrderReference
CloseOrderReference

Returns details about the Order Reference object and its current state.
Description
The GetOrderReferenceDetails operation returns details about the Order Reference object and its current state. An
Order Reference object provides the following details about an order:
• Buyer
• Amount
• Description
• Destination (optional)
• Seller order attributes (optional)
• List of constraints (optional)
Request parameters
Type: xs:string
Amazon.
AddressConsentToken The buyer address consent token.
Type: xs:string
No This value is retrieved from the
Amazon.
Response elements
Name Description
state.
Examples

&Action=GetOrderReferenceDetails
&AddressConsentToken=IQEBLzAtAhUAjagYW4Jrgw84pCaaIDjrKoEhZXsEXAMPLE
&SignatureVersion=2
&Timestamp=2012-11-05T19%3A01%3A11Z
&Version=2013-01-01
&Signature=CLZOdtJGjAo81IxaLoE7af6HqK0EXAMPLE
Example response
<GetOrderReferenceDetailsResponse xmlns="http://mws.amazonservices.com/
<GetOrderReferenceDetailsResult>
<AmazonOrderReferenceId>P01-1234567-1234567</AmazonOrderReferenceId>
<Destination>
</Destination>
</GetOrderReferenceDetailsResult>
<ResponseMetadata>
</ResponseMetadata>
</GetOrderReferenceDetailsResponse>
Related topics
CloseOrderReference

Confirms that the order reference is free of constraints and all required information has been set on the order reference.
Description
Call the ConfirmOrderReference operation after the order reference is free of constraints and all required information
has been set on the order reference. After you call this operation, the order reference is set to the Open state and you
can submit authorizations against the order reference.
After you successfully call this operation, you should call the GetOrderReferenceDetails operation to get the
remaining buyer information such as name and shipping address. Before an order reference is confirmed, only the City,
StateOrRegion, PostalCode, and CountryCode elements are returned in the call to GetOrderReferenceDetails.
Note: You can only submit authorization requests when an order reference is in the Open state.
Request parameters
Type: xs:string
Amazon.
Response elements
Examples
&Action=ConfirmOrderReference

&SignatureVersion=2
&Timestamp=2012-10-03T19%3A01%3A11Z
&Version=2013-01-01
Example response
<ConfirmOrderReferenceResponse xmlns="https://mws.amazonservices.com/schema/
OffAmazonPayments/2013-01-01">
<ResponseMetadata>
</ResponseMetadata>
</ConfirmOrderReferenceResponse>
Related topics
CloseOrderReference

Cancels a previously confirmed order reference.
Description
Call the CancelOrderReference operation to cancel a previously confirmed order reference. You can only cancel
an Order Reference object if there are no Completed, Closed, or Pending captures against it. If you cancel an order
reference, all authorizations associated with this order reference are also closed.
After you call this operation, the order reference is moved into the Canceled state.
Request parameters
Type: xs:string
Amazon.
CancelationReason Describes the reason for the cancelation.
Type: xs:string
Response elements
Examples
&Action=CancelOrderReference
&SignatureVersion=2
&Timestamp=2012-12-19T19%3A01%3A11Z
&Version=2013-01-01

Example response
<CancelOrderReferenceResponse xmlns="https://mws.amazonservices.com/schema/
<ResponseMetadata>
</ResponseMetadata>
</CancelOrderReferenceResponse>
Related topics
CloseOrderReference

CloseOrderReference
Confirms that an order reference has been fulfilled (fully or partially) and that you do not expect to create any new
authorizations on this order reference.
Description
Call the CloseOrderReference operation to indicate that a previously confirmed order reference has been fulfilled
(fully or partially) and that you do not expect to create any new authorizations on this order reference. You can still
capture funds against open authorizations on the order reference.
After you call this operation, the order reference is moved into the Closed state.
Request parameters
AmazonOrderReferenceId The ID of the order reference for which
the details are being requested.
Type: xs:string
Amazon.
ClosureReason Describes the reason for closing the
order reference.
Type: xs:string
Response elements
Examples
&Action=CloseOrderReference
&SignatureVersion=2

&Timestamp=2012-12-19T19%3A01%3A11Z
&Version=2013-01-01
Example response
<CloseOrderReferenceResponse xmlns="http://mws.amazonservices.com/schema/
<ResponseMetadata>
</ResponseMetadata>
</CloseOrderReferenceResponse>
Related topics

Authorize
Reserves a specified amount against the payment method(s) stored in the order reference.
Description
The Authorize operation reserves a specified amount against the payment method(s) stored in the order reference.
To charge the payment method(s), 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. For more information about Instant Payment Notifications,
see the help section at Amazon Payments. You can also query the details about an authorization by calling the
GetAuthorizationDetails operation.
Request parameters
Type: xs:string
Amazon.
AuthorizationReferenceId The identifier for this authorization
transaction that you specify. This
identifier must be unique for all your
authorization transactions.
Type: xs:string
Yes Amazon recommends that you use only
the following characters: lowercase a-z,
uppercase A-Z, numbers 0-9, dash (-),
or underscore (_).
AuthorizationAmount Represents the amount to be authorized.
Type: Price
Yes Maximum:
• In the US: $150,000
• In the UK: £150,000
• In Germany: €150,000
SellerAuthorizationNote A description for the transaction that is
displayed in emails to the buyer.
Type: xs:string
TransactionTimeout The number of minutes after which
the authorization will automatically
be closed and you will not be able to
capture funds against the authorization.
Note: In asynchronous
mode, the Authorize
operation always returns
the State as Pending. The
authorization remains in this
state until it is processed by
Amazon. The processing
time varies and can be
No Zero or integral 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:
• Must be 0
TransactionTimeout values in
asynchronous mode:
• Minimum: 5

a minute or more. After
processing is complete,
Amazon will notify you of
the final processing status.
For more information, see
"Synchronizing your systems
with Amazon Payments"
in the Login and Pay with
Amazon Integration Guide.
Type: xs:nonNegativeInteger
• Maximum: 1440
• Default: 1440
CaptureNow Indicates whether to directly capture
a specified amount 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.
Note: The Amazon
Payments policy states that
you charge your buyer when
you fulfill the items in the
order. You should not collect
funds prior to fulfilling the
order.
Type: xs:boolean
No CaptureNow 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 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>”.
Type: xs:string
No Default: “AMZ*<SELLER_NAME>
amzn.com/pmts WA”
Response elements
Name Description
Examples
AWSAccessKeyId=AKIAFBM3LG5JEEXAMPLE
&Action=Authorize
&AuthorizationAmount.Amount=94.50
&AuthorizationAmount.CurrencyCode=USD
&AuthorizationReferenceId=test_authorize_1

&SellerAuthorizationNote=Lorem%20ipsum
&SignatureVersion=2
&Timestamp=2012-10-03T19%3A01%3A11Z
&TransactionTimeout=60
&Version=2013-01-01
Example response
<AuthorizeResponse xmlns=" https://mws.amazonservices.com/schema/
<AuthorizeResult>
<AmazonAuthorizationId>
P01-1234567-1234567-0000001
</AmazonAuthorizationId>
<AuthorizationReferenceId>test_authorize_1</AuthorizationReferenceId>
<SellerAuthorizationNote>Lorem ipsum</SellerAuthorizationNote>
<AuthorizationFee>
<Amount>0</Amount>
</AuthorizationFee>
<State>Pending</State>
</AuthorizationDetails>
</AuthorizeResult>
<ResponseMetadata>
<RequestId>b4ab4bc3-c9ea-44f0-9a3d-67cccef565c6</RequestId>
</ResponseMetadata>
</AuthorizeResponse>
Related topics
GetAuthorizationDetails
CloseAuthorization

GetAuthorizationDetails
Returns the status of a particular authorization and the total amount captured on the authorization.
Description
Call the GetAuthorizationDetails operation to query the status of a particular authorization and to retrieve
information about the total amount captured on the authorization. If you received a Pending status when you called the
Authorize operation, you can call this operation to get the current status.
Request parameters
AmazonAuthorizationId The authorization identifier that was
generated by Amazon in the earlier call
to Authorize.
Type: xs:string
Yes
Response elements
Name Description
Examples
AWSAccessKeyId=AKIAFBM3LG5JEEXAMPLE
&Action=GetAuthorizationDetails
&AmazonAuthorizationId=P01-1234567-1234567-0000001
&SignatureVersion=2
&Timestamp=2012-11-05T19%3A01%3A11Z

&Version=2013-01-01
Example response
<GetAuthorizationDetailsResponse xmlns=" https://mws.amazonservices.com/
<AmazonAuthorizationId>
P01-1234567-1234567-0000001
</AmazonAuthorizationId>
<AuthorizationReferenceId>test_authorize_1</AuthorizationReferenceId>
<SellerAuthorizationNote>Lorem ipsum</SellerAuthorizationNote>
<AuthorizationFee>
<Amount>0</Amount>
</AuthorizationFee>
<State>Open</State>
<LastUpdateTimestamp>2012-12-10T19%3A01%3A11Z</LastUpdateTimestamp>
<CreationTimestamp>2012-12-10T19%3A01%3A11Z</CreationTimestamp>
<ResponseMetadata>
<RequestId>b4ab4bc3-c9ea-44f0-9a3d-67cccef565c6</RequestId>
</ResponseMetadata>
</GetAuthorizationDetailsResponse>
Related topics
Authorize
CloseAuthorization

fahoby

Recommended

Recommended

More Related Content

Viewers also liked

Viewers also liked (12)

Similar to fahoby

Similar to fahoby (20)

fahoby