m ws off amazon payment sap i reference

Amazon Marketplace Web ServiceOff-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 (Version2013-01-01)...................................................................................................................................................... 5

What you should know about the Amazon MWS Off-Amazon Payments API section............................6Throttling......................................................................................................................................................................................................8

SetOrderReferenceDetails............................................................................................................................. 9Description...................................................................................................................................................................................................9Request parameters....................................................................................................................................................................................9Response elements.....................................................................................................................................................................................9Examples..................................................................................................................................................................................................... 9Related topics............................................................................................................................................................................................10

GetOrderReferenceDetails...........................................................................................................................11Description.................................................................................................................................................................................................11Request parameters..................................................................................................................................................................................11Response elements...................................................................................................................................................................................11Examples................................................................................................................................................................................................... 11Related topics............................................................................................................................................................................................12

ConfirmOrderReference...............................................................................................................................13Description.................................................................................................................................................................................................13Request parameters..................................................................................................................................................................................13Response elements...................................................................................................................................................................................13Examples................................................................................................................................................................................................... 13Related topics............................................................................................................................................................................................14

CancelOrderReference.................................................................................................................................15Description.................................................................................................................................................................................................15Request parameters..................................................................................................................................................................................15Response elements...................................................................................................................................................................................15Examples................................................................................................................................................................................................... 15Related topics............................................................................................................................................................................................16

CloseOrderReference...................................................................................................................................17Description.................................................................................................................................................................................................17Request parameters..................................................................................................................................................................................17Response elements...................................................................................................................................................................................17Examples................................................................................................................................................................................................... 17Related topics............................................................................................................................................................................................18

Authorize....................................................................................................................................................... 19Description.................................................................................................................................................................................................19Request parameters..................................................................................................................................................................................19Response elements...................................................................................................................................................................................20Examples................................................................................................................................................................................................... 20Related topics............................................................................................................................................................................................21

GetAuthorizationDetails...............................................................................................................................22Description.................................................................................................................................................................................................22Request parameters..................................................................................................................................................................................22Response elements...................................................................................................................................................................................22



Examples................................................................................................................................................................................................... 22Related topics............................................................................................................................................................................................23

Capture.......................................................................................................................................................... 24Description.................................................................................................................................................................................................24Request parameters..................................................................................................................................................................................24Response elements...................................................................................................................................................................................25Examples................................................................................................................................................................................................... 25Related topics............................................................................................................................................................................................25

GetCaptureDetails........................................................................................................................................ 26Description.................................................................................................................................................................................................26Request parameters..................................................................................................................................................................................26Response elements...................................................................................................................................................................................26Related topics............................................................................................................................................................................................26

CloseAuthorization.......................................................................................................................................27Description.................................................................................................................................................................................................27Request parameters..................................................................................................................................................................................27Response elements...................................................................................................................................................................................27Examples................................................................................................................................................................................................... 27Related topics............................................................................................................................................................................................28

Refund........................................................................................................................................................... 29Description.................................................................................................................................................................................................29Request parameters..................................................................................................................................................................................29Response elements...................................................................................................................................................................................30Examples................................................................................................................................................................................................... 30Related topics............................................................................................................................................................................................31

GetRefundDetails..........................................................................................................................................32Description.................................................................................................................................................................................................32Request parameters..................................................................................................................................................................................32Response elements...................................................................................................................................................................................32Related topics............................................................................................................................................................................................32

GetServiceStatus.......................................................................................................................................... 33Description.................................................................................................................................................................................................33Request parameters..................................................................................................................................................................................33Response elements...................................................................................................................................................................................33Examples................................................................................................................................................................................................... 33Related topics............................................................................................................................................................................................34

Off-Amazon Payments Datatypes...............................................................................................................35Address......................................................................................................................................................................................................35AuthorizationDetails...................................................................................................................................................................................36Buyer......................................................................................................................................................................................................... 38CaptureDetails........................................................................................................................................................................................... 38Constraint.................................................................................................................................................................................................. 39Destination.................................................................................................................................................................................................39OrderReferenceAttributes..........................................................................................................................................................................40OrderReferenceDetails.............................................................................................................................................................................. 40OrderReferenceStatus...............................................................................................................................................................................41OrderTotal..................................................................................................................................................................................................42Price...........................................................................................................................................................................................................42RefundDetails............................................................................................................................................................................................ 43SellerOrderAttributes................................................................................................................................................................................. 44Status.........................................................................................................................................................................................................44

Order Reference Constraints......................................................................................................................46



Order Reference States and Reason Codes............................................................................................. 47

Authorization States and Reason Codes.................................................................................................. 49

Capture States and Reason Codes............................................................................................................51

Refund States and Reason Codes.............................................................................................................52

Error codes................................................................................................................................................... 53

Client library updates.................................................................................................................................. 55



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 trademarksare the property of their respective owners.

Last updated: 2014-03-11



What you should know about the AmazonMWS Off-Amazon Payments API section

OverviewThe Off-Amazon Payments API section helps you to process payments for purchases made by buyers on your websiteusing the Login and Pay with Amazon service. This API section enables you to programmatically retrieve shipping andpayment information provided by the buyer from their Amazon account. It allows you to authorize, capture, and refundpayments, enabling a variety of payments scenarios.

Note: The Off-Amazon Payments API section is only applicable to payments made through the Login and Paywith Amazon service offered by Amazon Payments. You cannot use this API section to process payments forAmazon 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 limited representation of an order, hereafter referred to as an order reference or OrderReference 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 after 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 andPay with Amazon Integration Guide. The "Getting started" section will walk you through a complete purchase frombeginning to end.

TerminologyThe following table defines terminology for this API section:

Term Description

Order Reference An order reference, or Order Reference object, is a limitedrepresentation of the sellers order. Its primary purpose is to track thefollowing:

The parties involved in the purchase (the buyer and the seller)

The payment method

The estimated purchase amount

Shipping information (optional).

The order reference also serves as an approval by the buyer to the sellerfor charging a specified amount. The seller can execute transactionsagainst the order reference using the operations in this API section.

Authorization An authorization, or Authorization object, tracks the availabilityof funds and secures them for future payment against the paymentinstrument(s) stored in the order reference.

Capture A capture, or Capture object, tracks the movement of funds previouslysecured by authorization from the buyers payment instrument(s) to thesellers account.



Term Description

Refund A refund, or Refund object, tracks the movement of previously capturedfunds from the sellers account to the buyers payment instrument(s).

Transaction A transaction is a generic term that is used for all the types of paymentevents against an order reference. This includes authorizations, captures,refunds, A-to-z Claims, charge backs, fees, and other miscellaneoustransactions.

EndpointsAll 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/

OperationsThe Off-Amazon Payments API section contains the following operations:

Operation Description

SetOrderReferenceDetails Sets order reference details such as the order total and a description forthe 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 requiredinformation 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 orderreference.

Authorize Reserves a specified amount against the payment method(s) stored inthe order reference.

GetAuthorizationDetails Returns the status of a particular authorization and the total amountcaptured on the authorization.

Capture Captures funds from an authorized payment instrument.

GetCaptureDetails Returns the status of a particular capture and the total amount refundedon the capture.

CloseAuthorization Closes an authorization.

Refund Refunds a previously captured amount.

GetRefundDetails Returns the status of a particular refund.



ThrottlingDescribes Amazon MWS throttling concepts.

The following table explains Amazon MWS throttling concepts:

Name Description

Request quota The number of requests that you can submit at one time withoutthrottling. The request quota decreases with every request you submit.The request quota increases at the restore rate. Requests are calculatedfor each Amazon seller account and Amazon MWS developer accountpair.

Restore rate The rate at which your request quota increases over time, up to themaximum request quota.

Maximum request quota The maximum size that the request quota can reach.

The documentation for each operation in the Off-Amazon Payments API section lists the maximum request quota andrestore rate for that operation.

For a complete explanation of throttling, see "Throttling: Limits to how often you can submit requests" in the AmazonMWS Developer Guide.



SetOrderReferenceDetailsSets order reference details such as the order total and a description for the order.

DescriptionCall the SetOrderReferenceDetails operation to specify order details such as the amount of the order, a descriptionof the order, and other order attributes.

This operation has a maximum request quota of 10 and a restore rate of one request every second in the productionenvironment. It has a maximum request quota of two and a restore rate of one request every two seconds in the sandboxenvironment. For definitions of throttling terminology, see Throttling.

Request parametersFor more information about the request parameters that are required for all Amazon MWS operations, see "Requiredrequest parameters" in the Amazon MWS Developer Guide.

Name Description Required Valid Values

AmazonOrderReferenceId The order reference identifier retrievedfrom the Amazon Button widget.

Type: xs:string

Yes This value is retrieved from theAmazon Button widget after the buyerhas successfully authenticated withAmazon.

OrderReferenceAttributes The seller-specified attributes of theorder reference.

Type: OrderReferenceAttributes

Yes

Response elementsName Description

OrderReferenceDetails Encapsulates details about the Order Reference object and its currentstate.

Type: OrderReferenceDetails

Examples

Example query request

https://mws.amazonservices.com/OffAmazonPayments/2013-01-01?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&SellerId=YOUR_SELLER_ID_HERE&SignatureMethod=HmacSHA256&SignatureVersion=2



&Timestamp=2012-11-05T19%3A01%3A11Z&Version=2013-01-01&Signature=2RPzkOgQmDybUjk0dA54maCEXAMPLE

Example response

P01-1234567-1234567 106 USD 5678-23 Lorem ipsum 2012-11-05T20:21:19Z 2013-05-07T23:21:19Z Draft Physical New York NY 10101-9876 US Live

f42df4b1-8047-11df-8d5c-bf56a38ef3b4

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

GetOrderReferenceDetails

ConfirmOrderReference

CancelOrderReference

CloseOrderReference



GetOrderReferenceDetailsReturns details about the Order Reference object and its current state.

DescriptionThe GetOrderReferenceDetails operation returns details about the Order Reference object and its current state. AnOrder Reference object provides the following details about an order:

Buyer Amount Description Destination (optional) Seller order attributes (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 productionenvironment. It has a maximum request quota of five and a restore rate of one request every second in the sandboxenvironment. For definitions of throttling terminology, see Throttling.



AmazonOrderReferenceId The order reference identifier.

Type: xs:string


AddressConsentToken The buyer address consent token.

Type: xs:string

No This value is retrieved from theAmazon Button widget after the buyerhas successfully authenticated withAmazon.


OrderReferenceDetails Encapsulates details about the Order Reference object and its currentstate.

Type: OrderReferenceDetails

Examples


https://mws.amazonservices.com/OffAmazonPayments/2013-01-01?AWSAccessKeyId=AKIAJKYFSJU7PEXAMPLE&Action=GetOrderReferenceDetails&AddressConsentToken=IQEBLzAtAhUAjagYW4Jrgw84pCaaIDjrKoEhZXsEXAMPLE



&AmazonOrderReferenceId=P01-1234567-1234567&SellerId=YOUR_SELLER_ID_HERE&SignatureMethod=HmacSHA256&SignatureVersion=2&Timestamp=2012-11-05T19%3A01%3A11Z&Version=2013-01-01&Signature=CLZOdtJGjAo81IxaLoE7af6HqK0EXAMPLE

Example response

P01-1234567-1234567 2012-11-05T20:21:19Z 2013-05-07T23:21:19Z Draft Physical New York NY 10101-9876 US Live 5f20169b-7ab2-11df-bcef-d35615e2b044


SetOrderReferenceDetails



CloseOrderReference



ConfirmOrderReferenceConfirms that the order reference is free of constraints and all required information has been set on the order reference.

DescriptionCall the ConfirmOrderReference operation after the order reference is free of constraints and all required informationhas been set on the order reference. After you call this operation, the order reference is set to the Open state and youcan submit authorizations against the order reference.

After you successfully call this operation, you should call the GetOrderReferenceDetails operation to get theremaining 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.





Type: xs:string


Response elementsThis operation only returns the standard response elements.

Examples


https://mws.amazonservices.com/OffAmazonPayments/2013-01-01?AWSAccessKeyId=AKIAJKYFSJU7PEXAMPLE&Action=ConfirmOrderReference&AmazonOrderReferenceId=P01-1234567-1234567&SellerId=YOUR_SELLER_ID_HERE&SignatureMethod=HmacSHA256&SignatureVersion=2&Timestamp=2012-10-03T19%3A01%3A11Z&Version=2013-01-01&Signature=CLZOdtJGjAo81IxaLoE7af6HqK0EXAMPLE



Example response

f42df4b1-8047-11df-8d5c-bf56a38ef3b4





CloseOrderReference



CancelOrderReferenceCancels a previously confirmed order reference.

DescriptionCall the CancelOrderReference operation to cancel a previously confirmed order reference. You can only cancelan Order Reference object if there are no Completed, Closed, or Pending captures against it. If you cancel an orderreference, all authorizations associated with this order reference are also closed.

After you call this operation, the order reference is moved into the Canceled state.





Type: xs:string


CancelationReason Describes the reason for the cancelation.

Type: xs:string

No Maximum: 1024 characters


Examples


https://mws.amazonservices.com/OffAmazonPayments/2013-01-01?AWSAccessKeyId=AKIAJKYFSJU7PEXAMPLE&Action=CancelOrderReference&AmazonOrderReferenceId=P01-1234567-1234567&SellerId=YOUR_SELLER_ID_HERE&SignatureMethod=HmacSHA256&SignatureVersion=2&Timestamp=2012-12-19T19%3A01%3A11Z&Version=2013-01-01&Signature=CLZOdtJGjAo81IxaLoE7af6HqK0EXAMPLE



Example response

5f20169b-7ab2-11df-bcef-d35615e2b044





CloseOrderReference



CloseOrderReferenceConfirms that an order reference has been fulfilled (fully or partially) and that you do not expect to create any newauthorizations on this order reference.

DescriptionCall 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 stillcapture funds against open authorizations on the order reference.

After you call this operation, the order reference is moved into the Closed state.




AmazonOrderReferenceId The ID of the order reference for whichthe details are being requested.

Type: xs:string


ClosureReason Describes the reason for closing theorder reference.

Type: xs:string



Examples


https://mws.amazonservices.com/OffAmazonPayments/2013-01-01?AWSAccessKeyId=AKIAJKYFSJU7PEXAMPLE&Action=CloseOrderReference&AmazonOrderReferenceId=P01-1234567-1234567&SellerId=YOUR_SELLER_ID_HERE&SignatureMethod=HmacSHA256&SignatureVersion=2&Timestamp=2012-12-19T19%3A01%3A11Z&Version=2013-01-01&Signature=CLZOdtJGjAo81IxaLoE7af6HqK0EXAMPLE



Example response

5f20169b-7ab2-11df-bcef-d35615e2b044








AuthorizeReserves a specified amount against the payment method(s) stored in the order reference.

DescriptionThe 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 Captureoperation after you call this operation. An authorization is only valid for a particular time period, which is specifiedin the response of the operation. At the end of the time period, the authorization expires and a notification is sent toyou 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 theGetAuthorizationDetails operation.





Type: xs:string


AuthorizationReferenceId The identifier for this authorizationtransaction that you specify. Thisidentifier must be unique for all yourauthorization transactions.

Type: xs:string

Yes Amazon recommends that you use onlythe following characters: lowercase a-z,uppercase A-Z, dash (-), or underscore(_).

Maximum: 32 characters

AuthorizationAmount Represents the amount to be authorized.

Type: Price

Yes

SellerAuthorizationNote A description for the transaction that isdisplayed in emails to the buyer.

Type: xs:string


TransactionTimeout The number of minutes after whichthe authorization will automaticallybe closed and you will not be able tocapture funds against the authorization.

Note: The Authorizeoperation always returnsthe State as Pending. Theauthorization remains in thisstate until it is processed byAmazon. The processingtime varies and can bea minute or more. Afterprocessing is complete,Amazon will notify you ofthe final processing status.For more information, see

No Zero or integral values in multiplesof five (5, 10, 15, etc.). Set the valueto zero for synchronous mode. Setthe value to greater than zero forasynchronous mode.

TransactionTimeout values insynchronous mode:

Must be 0

TransactionTimeout values inasynchronous mode:

Minimum: 5 Maximum: 1440 Default: 1440



Name Description Required Valid Values"Synchronizing your systemswith Amazon Payments"in the Login and Pay withAmazon Integration Guide.

Type: xs:nonNegativeInteger

CaptureNow Indicates whether to directly capturea specified amount against an orderreference (without needing to callCapture and without waiting until theorder ships). The captured amount isdisbursed to your account in the nextdisbursement cycle.

Note: The AmazonPayments policy states thatyou charge your buyer whenyou fulfill the items in theorder. You should not collectfunds prior to fulfilling theorder.

Type: xs:boolean

No CaptureNow values:

true: The specified amount isdirectly captured. You do not needto call the Capture operation.

false: You must call the Captureoperation to capture the fundsspecified in this authorization.

Default: false

SoftDescriptor The description to be shown on thebuyers payment instrument statementif CaptureNow is set to true. The softdescriptor sent to the payment processoris: AMZ* .

Type: xs:string

No Default: AMZ*amzn.com/pmts WA



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

Type: AuthorizationDetails

Examples


https://mws.amazonservices.com/OffAmazonPayments/2013-01-01?AWSAccessKeyId=AKIAFBM3LG5JEEXAMPLE&Action=Authorize&AmazonOrderReferenceId=P01-1234567-1234567&AuthorizationAmount.Amount=94.50&AuthorizationAmount.CurrencyCode=USD&AuthorizationReferenceId=test_authorize_1&SellerAuthorizationNote=Lorem%20ipsum&SellerId=YOUR_SELLER_ID_HERE&SignatureMethod=HmacSHA256&SignatureVersion=2&Timestamp=2012-10-03T19%3A01%3A11Z&TransactionTimeout=60&Version=2013-01-01&Signature=WlQ708aqyHXMkoUBk69Hjxj8qdh3aDcqpY71hVgEXAMPLE



Example response

P01-1234567-1234567-0000001 test_authorize_1 Lorem ipsum USD 94.50 USD 0 Pending 2012-11-03T19:10:16Z 2012-11-02T19:10:16Z 2012-12-02T19:10:16Z b4ab4bc3-c9ea-44f0-9a3d-67cccef565c6


GetAuthorizationDetails

CloseAuthorization



GetAuthorizationDetailsReturns the status of a particular authorization and the total amount captured on the authorization.

DescriptionCall the GetAuthorizationDetails operation to query the status of a particular authorization and to retrieveinformation about the total amount captured on the authorization. If you received a Pending status when you called theAuthorize operation, you can call this operation to get the current status.




AmazonAuthorizationId The authorization identifier that wasgenerated by Amazon in the earlier callto Authorize.

Type: xs:string

Yes


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

Type: AuthorizationDetails

Examples


https://mws.amazonservices.com/OffAmazonPayments/2013-01-01?AWSAccessKeyId=AKIAFBM3LG5JEEXAMPLE&Action=GetAuthorizationDetails&AmazonAuthorizationId=P01-1234567-1234567-0000001&SellerId=YOUR_SELLER_ID_HERE&SignatureMethod=HmacSHA256&SignatureVersion=2&Timestamp=2012-11-05T19%3A01%3A11Z&Version=2013-01-01&Signature=WlQ708aqyHXMkoUBk69Hjxj8qdh3aDcqpY71hVgEXAMPLE



Example response

P01-1234567-1234567-0000001 test_authorize_1 Lorem ipsum USD 94.50 USD 0 Open 2012-12-10T19%3A01%3A11Z 2012-12-10T19%3A01%3A11Z 2013-01-10T19:10:16Z b4ab4bc3-c9ea-44f0-9a3d-67cccef565c6


Authorize

CloseAuthorization



CaptureCaptures funds from an authorized payment instrument.

DescriptionCall the Capture operation to capture funds from an authorized payment instrument. To successfully capturea payment, you must call this operation on an Authorization object before it expires, as specified by theExpirationTimestamp returned in response of the Authorize operation call. You must specify a capture amount, andthe amount cannot exceed the original amount that was authorized.

You can query the status of a capture request by calling the GetCaptureDetails operation.





Type: xs:string

Yes

CaptureReferenceId The identifier for this capturetransaction that you specify. Thisidentifier must be unique for all yourcapture transactions.

Type: xs:string



CaptureAmount The amount to capture in thistransaction.

This amount cannot exceed the originalamount that was authorized less anypreviously captured amount on thisauthorization.

Type: Price

Yes

SellerCaptureNote A description for the capture transactionthat is displayed in emails to the buyer.

Type: xs:string


SoftDescriptor The description to be shown on thebuyers payment instrument statement.The soft descriptor sent to the paymentprocessor is: AMZ* .

Type: xs:string






CaptureDetails Encapsulates details about the Capture object and its status.

Type: CaptureDetails

Examples


https://mws.amazonservices.com/OffAmazonPayments/2013-01-01?AWSAccessKeyId=AKIAFBM3LG5JEEXAMPLE&Action=Capture&AmazonAuthorizationId=P01-1234567-1234567-0000001&CaptureAmount.Amount=94.50&CaptureAmount.CurrencyCode=USD&CaptureReferenceId=test_capture_1&SellerCaptureNote=Lorem%20ipsum&SellerId=YOUR_SELLER_ID_HERE&SignatureMethod=HmacSHA256&SignatureVersion=2&Timestamp=2012-11-05T19%3A01%3A11Z&Version=2013-01-01&Signature=WlQ708aqyHXMkoUBk69Hjxj8qdh3aDcqpY71hVgEXAMPLE

Example response

P01-1234567-1234567-0000002 test_capture_1 Lorem ipsum USD 94.50 Completed 2012-11-03T19:10:16Z 2012-11-03T19:10:16Z b4ab4bc3-c9ea-44f0-9a3d-67cccef565c6


GetCaptureDetails



GetCaptureDetailsReturns the status of a particular capture and the total amount refunded on the capture.

DescriptionCall the GetCaptureDetails operation to query the status of a particular capture and to retrieve information about thetotal amount refunded on the capture. If you received a Pending status when you called the Capture operation, youcan call this operation to get the current status.




AmazonCaptureId The capture identifier that wasgenerated by Amazon on the earlier callto Capture.

Type: xs:string

Yes


CaptureDetails Encapsulates details about the Capture object and its status.

Type: CaptureDetails


Capture



CloseAuthorizationCloses an authorization.

DescriptionCall the CloseAuthorization operation to close an authorization after the total amount of the authorization has beencaptured.





Type: xs:string

Yes

ClosureReason A description for the closure that isdisplayed in emails to the buyer.

Type: xs:string



Examples


https://mws.amazonservices.com/OffAmazonPayments/2013-01-01?AWSAccessKeyId=AKIAFBM3LG5JEEXAMPLE&Action=CloseAuthorization&AmazonAuthorizationId=P01-1234567-1234567-0000001&ClosureReason=Closing%20the%20auhorization%20transaction&SellerId=YOUR_SELLER_ID_HERE&SignatureMethod=HmacSHA256&SignatureVersion=2&Timestamp=2012-12-17T19%3A01%3A11Z&Version=2013-01-01&Signature=WlQ708aqyHXMkoUBk69Hjxj8qdh3aDcqpY71hVgEXAMPLE



Example response

a9aedsd6-a10y-11t8-9a3d-67gggwd565c6


Authorize

GetAuthorizationDetails



RefundRefunds a previously captured amount.

DescriptionCall the Refund operation to refund a previously captured amount. A refund can only be requested on a capture if therefund amount does not exceed the following amounts:

In the US: up to 15% or $75 (whichever is less) above the captured amount. In the UK: up to 15% or 75 (whichever is less) above the captured amount. In Germany: up to 15% or 75 (whichever is less) above the captured amount.

You call the GetRefundDetails operation to query the status of a refund.




AmazonCaptureId The capture identifier that wasgenerated by Amazon in the earlier callto Capture.

Type: xs:string

Yes

RefundReferenceId The identifier for this refund transactionthat you specify. This identifier must beunique for all your refund transactions.

Type: xs:string



RefundAmount The amount to refund.

This amount cannot exceed:

In the US: the lesser of 15% or $75above the captured amount less theamount already refunded on thecapture.

In the UK: the lesser of 15% or 75above the captured amount for theCapture object.

In Germany: the lesser of 15% or75 above the captured amount forthe Capture object.

Type: Price

Yes

SellerRefundNote A description for the refund that isdisplayed in emails to the buyer.

Type: xs:string


SoftDescriptor The description to be shown on thebuyers payment instrument statement.The soft descriptor sent to the payment




Name Description Required Valid Valuesprocessor is: AMZ* .

Type: xs:string



RefundDetails Encapsulates details about the Refund object and its status.

Type: RefundDetails

Examples


https://mws.amazonservices.com/OffAmazonPayments/2013-01-01?AWSAccessKeyId=AKIAFBM3LG5JEEXAMPLE&Action=Refund&AmazonCaptureId=P01-1234567-1234567-0000002&RefundAmount.Amount=94.50&RefundAmount.CurrencyCode=USD&RefundReferenceId=test_refund_1&SellerRefundNote=Lorem%20ipsum&SellerId=YOUR_SELLER_ID_HERE&SignatureMethod=HmacSHA256&SignatureVersion=2&Timestamp=2012-11-05T19%3A01%3A11Z&Version=2013-01-01&Signature=WlQ708aqyHXMkoUBk69Hjxj8qdh3aDcqpY71hVgEXAMPLE

Example response

P01-1234567-1234567-0000003 test_refund_1 Lorem ipsum SellerInitiated USD 94.50 USD 0 Completed 2012-11-07T19:10:16Z 2012-11-05T19:10:16Z



b4ab4bc3-c9ea-44f0-9a3d-67cccef565c6


GetRefundDetails



GetRefundDetailsReturns the status of a particular refund.

DescriptionCall the GetRefundDetails operation to query the status of a particular refund. If you received a Pending status whenyou called the Refund operation, you can call this operation to get the current status.




AmazonRefundId The Amazon-generated identifier forthis refund transaction.

Type: xs:string

Yes


RefundDetails Encapsulates details about the Refund object and its status.

Type: RefundDetails


Refund



GetServiceStatusReturns the operational status of the Off-Amazon Payments API section.

DescriptionThe GetServiceStatus operation returns the operational status of the Off-Amazon Payments API section of AmazonMarketplace Web Service (Amazon MWS). Status values are GREEN, GREEN_I, YELLOW, and RED.

The GetServiceStatus operation has a maximum request quota of two requests and a restore rate of one requestevery five minutes. For definitions of throttling terminology, see Throttling.

Request parametersThe GetServiceStatus operation only accepts the required request parameters. For more information about therequest parameters that are required for all Amazon MWS operations, see "Required request parameters" in theAmazon MWS Developer Guide.


Status The following list shows possible values returned by the GetServiceStatus operation:

GREEN The service is operating normally.

GREEN_I The service is operating normally. Additional information is provided.

YELLOW The service is experiencing higher than normal error rates or is operatingwith degraded performance. Additional information may be provided.

RED The service is unavailable or experiencing extremely high error rates.Additional information may be provided.

Type: xs:string

Timestamp Indicates the time at which the operational status was evaluated.

Type: xs:dateTime

MessageId An Amazon-defined message identifier.

Type: xs:string

Messages The parent element of one or more Message elements.

Message The operational status message.

The parent element of the following child elements (both child elements are type: xs:string):

Locale Text

Examples


https://mws.amazonservices.com/OffAmazonPayments/2013-01-01?AWSAccessKeyId=AKIAEEXAMPLENGQCJLSA&Action=GetServiceStatus



&SellerId=A135KKEKWF1J56&SignatureMethod=HmacSHA256&SignatureVersion=2&Timestamp=2013-07-25T18%3A17%3A45Z&Version=2013-01-01&Signature=neUupEXAMPLEwJEJGnBfBGa2UpTSIZW3JMnVUYLsM4w%3D

Example response

GREEN 2013-07-25T18:17:45.167Z 082c41fd-2f6b-4616-a518-7db14EXAMPLE




Off-Amazon Payments DatatypesThe following datatypes are used in the request parameters and response elements of the Amazon Marketplace WebService (Amazon MWS) Off-Amazon Payments API section:

Datatype Description

Address Postal address information.

AuthorizationDetails Encapsulates details about an Authorization object including the status, amount captured, and feecharged.

Buyer The name, e-mail address, and phone number of the buyer.

CaptureDetails Encapsulates details about a Capture object and its status.

Constraint Indicates mandatory information that is missing or incorrect in an Order Reference object.

Destination Represents the address selected by the buyer through the AddressBook widget.

OrderReferenceAttributes The seller-specified attributes of an Order Reference object.

OrderReferenceDetails Encapsulates details about an Order Reference object and its current state.

OrderReferenceStatus Indicates the current status of an Order Reference object.

OrderTotal The total amount of an order represented by an Order Reference object.

Price Currency type and amount.

RefundDetails Encapsulates details about a Refund object and its status.

SellerOrderAttributes Provides more context about an order that is represented by an Order Reference object.

Status Indicates the current status of an Authorization object, a Capture object, or a Refund object.

AddressPostal address information.

Datatype contentThe following table shows the elements of the Address datatype:

Name Description

Name The name or business name. Required.


Type: xs:string

AddressLine1 The street address information. At lease one of AddressLine1,AddressLine2, or AddressLine3 is required.


Type: xs:string

AddressLine2 Additional street address information, if required. At lease one ofAddressLine1, AddressLine2, or AddressLine3 is required.


Type: xs:string



Name Description

AddressLine3 Additional street address information, if required. At lease one ofAddressLine1, AddressLine2, or AddressLine3 is required.


Type: xs:string

City The city. Required.


Type: xs:string

County The county. Optional.


Type: xs:string

District The district. Optional.


Type: xs:string

StateOrRegion The state or region. This element is free text and can be either a 2-character code, fully spelled out, or abbreviated. Required.

Note: This response element is only returned in the US.


Type: xs:string

PostalCode The postal code. Required.


Type: xs:string

CountryCode The country code, in ISO 3166 format. Required.

Type: xs:string

Phone The phone number. Required.

Type: xs:string

AuthorizationDetailsEncapsulates details about an Authorization object including the status, amount captured, and fee charged.

Datatype contentThe following table shows the elements of the AuthorizationDetails datatype:

Name Description

AmazonAuthorizationId The Amazon-generated identifier for this authorization transaction.

Type: xs:string

AuthorizationReferenceId The identifier for this authorization transaction that you specify.Maximum: 32 characters.



Name Description

Type: xs:string

SellerAuthorizationNote A description for the authorization transaction that is displayed inemails to the buyer.

Type: xs:string

AuthorizationAmount The amount to be authorized.

Type: Price

CapturedAmount The total amount that has been captured on this authorization.

Type: Price

AuthorizationFee The fee that was charged by Amazon for this authorization.

Type: Price

IdList A list of AmazonCaptureId identifiers that have been requested on thisAuthorization object.

This list is empty if you have not requested any captures on thisauthorization.

Type: List of Type: xs:string

CreationTimestamp The time at which the authorization was created. In ISO 8601 format.

Type: xs:dateTime

ExpirationTimestamp The time when the authorization expires and no further captures can berequested against the authorization. In ISO 8601 format.

Type: xs:dateTime

AuthorizationStatus Describes the current status of the authorization.

Note: The Authorize operation always returns the Stateas Pending. The authorization remains in this state until it isprocessed by Amazon. The processing time varies and canbe a minute or more. After processing is complete, Amazonwill notify you of the final processing status. For moreinformation, see "Synchronizing your systems with AmazonPayments" in the Login and Pay with Amazon IntegrationGuide.

For more information about the State and ReasonCode responseelements, see Authorization States and Reason Codes.

Type: Status

CaptureNow Indicates whether you specified a direct capture against the orderreference. The captured amount will disbursed to your account in thenext disbursement cycle.

CaptureNow values:

true: The specified amount was directly captured. You do not needto call the Capture operation.

false: You must call the Capture operation to capture the fundsspecified in this authorization.

Default: false

Type: xs:boolean



Name Description

SoftDescriptor The description to be shown on the buyers payment instrumentstatement if CaptureNow was set to true. Maximum: 16 characters.

Type: xs:string

BuyerThe name, e-mail address, and phone number of the buyer.

Datatype contentThe following table shows the elements of the Buyer datatype:

Name Description

Name The name of the buyer. Required.

Type: xs:string

Email The e-mail address of the buyer. Required.

Type: xs:string

Phone The phone number of the buyer. Required.

Type: xs:string

CaptureDetailsEncapsulates details about a Capture object and its status.

Datatype contentThe following table shows the elements of the CaptureDetails datatype:

Name Description

AmazonCaptureId The Amazon-generated identifier for this capture.

Type: xs:string

CaptureReferenceId The identifier for this capture that you specify. Maximum: 32characters.

Type: xs:string

SellerCaptureNote A description for the capture that is displayed in emails to the buyer.Maximum: 255 characters.

Type: xs:string

CaptureAmount The amount to be captured.

Type: Price

RefundedAmount The total amount that has been refunded on this capture.

Type: Price

CaptureFee The fee that was charged by Amazon for this capture.



Name Description

Type: Price

IdList A list of AmazonRefundId identifiers that have been requested on thisCapture object.

This list is empty if you have not requested any refunds on this capture.

Type: List of Type: xs:string

CreationTimestamp The time at which the capture was created. In ISO 8601 format.

Type: xs:dateTime

CaptureStatus Represents the current status of the capture.

For more information about the State and ReasonCode responseelements, see Capture States and Reason Codes.

Type: Status

SoftDescriptor The description to be shown on the buyers payment instrumentstatement. Maximum: 16 characters.

Type: xs:string

ConstraintIndicates mandatory information that is missing or incorrect in an Order Reference object.

Datatype contentThe following table shows the elements of the Constraint datatype:

Name Description

ConstraintID The identifier of the constraint. For more information, see OrderReference Constraints.

Type: xs:string

Description The description of the constraint. For more information, see OrderReference Constraints.

Type: xs:string

DestinationRepresents the address selected by the buyer through the AddressBook widget.

Datatype contentThe following table shows the elements of the Destination datatype:

Name Description

DestinationType DestinationType values:

Physical

Type: xs:string



Name Description

PhysicalDestination The address of the destination.

Type: Address

OrderReferenceAttributesThe seller-specified attributes of an Order Reference object.

Datatype contentThe following table shows the elements of the OrderReferenceAttributes datatype:

Name Description Required Valid Valiues

OrderTotal Specifies the total amount of the orderrepresented by this order reference.

Type: OrderTotal

Yes

PlatformId Represents the unique identifier of theseller's platform.

Type: xs:string

No The encrypted SellerId for the accountthat is associated with the platform orplugin being used by the seller.

SellerNote Represents a description of the orderthat is displayed in emails to the buyer.

Type: xs:string


SellerOrderAttributes Provides more context about theorder that is represented by this orderreference.

Type: SellerOrderAttributes

No

OrderReferenceDetailsEncapsulates details about an Order Reference object and its current state.

Datatype contentThe following table shows the elements of the OrderReferenceDetails datatype:

Name Description

AmazonOrderReferenceId The order reference identifier retrieved from the Amazon Buttonwidget.

Type: xs:string

Buyer Provides details about the buyer. This information will only be returnedafter you confirm the order reference.

Type: Buyer

OrderTotal Represents the total amount for this Order Reference object. Thisresponse element is not returned if you have not set it by calling theSetOrderReferenceDetails operation.

Type: OrderTotal



Name Description

SellerNote Represents a description of the order that is displayed in emails to thebuyer. This response element is not returned if you have not set it bycalling the SetOrderReferenceDetails operation. Maximum: 1024characters.

Type: xs:string

Destination Represents the address selected by the buyer through the AddressBookwidget.

Complete buyer information will only be returned after youhave confirmed the order reference. Until then, only the City,StateOrRegion, PostalCode, and CountryCode elements are returned.

Type: Destination

ReleaseEnvironment Indicates if the order is for a Live (Production) or Sandbox environment.

Type: xs:string

SellerOrderAttributes Provides more context about the order represented by this orderreference. This response element is not returned if you have not set it bycalling the SetOrderReferenceDetails operation.

Type: SellerOrderAttributes

OrderReferenceStatus Indicates the current status of the order reference.

For more information about the State and ReasonCode responseelements, see Order Reference States and Reason Codes.

Type: OrderReferenceStatus

Constraints A list of constraints that indicates mandatory information that ismissing or incorrect. The presence of constraints indicates that the orderreference is not ready to be confirmed and cannot be used for paymentoperations.

For more information, see Order Reference Constraints.

Type: List of Constraint

CreationTimestamp The date and time, in UTC, when the order reference was created. InISO 8601 format.

Type: xs:dateTime

ExpirationTimestamp The date and time, in UTC, when the order reference will expire andwill no longer be valid for authorization requests. In ISO 8601 format.

Note: An order reference (if confirmed) expires 180 daysafter it is created. It will be canceled by Amazon if it is notconfirmed within three hours of its creation.

Type: xs:dateTime

OrderReferenceStatusIndicates the current status of an Order Reference object.

Datatype contentThe following table shows the elements of the OrderReferenceStatus datatype:



Name Description

State Indicates the state that the Order Reference object is in. For moreinformation, see Order Reference States and Reason Codes.

Type: xs:string

LastUpdateTimestamp A timestamp that indicates the time when the order reference state waslast updated. In ISO 8601 format. Optional if the order reference is inthe Draft state.

Type: xs:dateTime

ReasonCode Optional if the order reference is in the Draft state. For moreinformation, see Order Reference States and Reason Codes.

Type: xs:string

ReasonDescription An optional description of the order reference status.

Type: xs:string

OrderTotalThe total amount of an order represented by an Order Reference object.

Datatype contentThe following table shows the elements of the OrderTotal datatype:


CurrencyCode Three-digit currency code. In ISO 4217format.

Type: xs:string

Yes The currency code is formatted basedon the ISO 4217 standard. The numberof decimal places must be appropriatefor the currency code specified. Aperiod is the only valid decimalseparator for the amount value.

Amount The currency amount.

Type: xs:string

Yes

PriceCurrency type and amount.

Datatype contentThe following table shows the elements of the Price datatype:


CurrencyCode Three-digit currency code. In ISO 4217format.

Type: xs:string

Yes The currency code is formatted basedon the ISO 4217 standard. The numberof decimal places must be appropriatefor the currency code specified. Aperiod is the only valid decimalseparator for the amount value.




Amount The currency amount.

Type: xs:string

Yes Minimum: 1 character

RefundDetailsEncapsulates details about a Refund object and its status.

Datatype contentThe following table shows the elements of the RefundDetails datatype:

Name Description

AmazonRefundId The Amazon-generated identifier for this refund transaction.

Type: xs:string

RefundReferenceId The identifier for this refund transaction that you specify. Maximum: 32characters.

Type: xs:string

SellerRefundNote A description for the refund that is displayed in emails to the buyer.Maximum: 255 characters.

Type: xs:string

RefundType Indicates the refund type.

RefundType values:

SellerInitiated

Type: xs:string

RefundAmount The amount requested for the refund.

Type: Price

FeeRefunded The capture fee that has been refunded.

Type: Price

CreationTimestamp The time at which the refund was created. In ISO 8601 format.

Type: xs:dateTime

RefundStatus Represents the status of the refund request.

Note: The Refund operation always returns the State asPending. The Refund object remains in this state until it isprocessed by Amazon. The refund processing time varies andcan be several hours. After processing is complete, Amazonwill notify you of the final processing status. For moreinformation, see "Synchronizing your systems with AmazonPayments" in the Login and Pay with Amazon IntegrationGuide.

For more information about the State and ReasonCode responseelements, see Refund States and Reason Codes.

Type: Status



Name Description

SoftDescriptor The description to be shown on the buyers payment instrumentstatement. Maximum: 16 characters.

Type: xs:string

SellerOrderAttributesProvides more context about an order that is represented by an Order Reference object.

Datatype contentThe following table shows the elements of the SellerOrderAttributes datatype:


SellerOrderId The seller-specified identifier of thisorder. This is displayed to the buyer intheir e-mails and transaction history onthe Amazon Payments website.

Type: xs:string

No Amazon recommends that you use onlythe following characters: lowercase a-z,uppercase A-Z, dash (-), or underscore(_).

StoreName The identifier of the store from wherethe order was placed. This overrides thedefault value in Seller Central underSettings > Account Settings. It isdisplayed to the buyer in their emailsand transaction history on the AmazonPayments website.

Type: xs:string

No

CustomInformation Any additional information you wish toinclude with this order reference.

Type: xs:string

No

StatusIndicates the current status of an Authorization object, a Capture object, or a Refund object.

Datatype contentThe following table shows the elements of the Status datatype:

Name Description

State Indicates the state that the Authorization object, Capture object, orRefund object is in. For more information, see Authorization States andReason Codes, Capture States and Reason Codes, or Refund States andReason Codes.

State values:

Pending

Open

Declined

Closed



Name Description

Completed

Type: xs:string

LastUpdateTimestamp A timestamp that indicates the time when the authorization, capture, orrefund state was last updated. In ISO 8601 format.

Type: xs:dateTime

ReasonCode The reason the Authorization object, Capture object, or Refund object isin the current state. For more information, see Authorization States andReason Codes, Capture States and Reason Codes, or Refund States andReason Codes.

Type: xs:string

ReasonDescription An optional description of the authorization, capture, or refund status.Maximum: 255 characters.

Type: xs:string



Order Reference ConstraintsAn Order Reference object is only eligible for payment authorization and capture after you confirm the order referenceby calling the ConfirmOrderReference operation. The ConfirmOrderReference operation call will succeed only ifthere are no constraints on the Order Reference object. Constraints indicate that important order reference informationis either missing or invalid.

You can take corrective actions to fix the order reference and remove the constraints before calling theConfirmOrderReference operation. The following table lists the constraints and corrective action you must take toremove the constraint:

ConstraintId Description Corrective Action

ShippingAddressNotSet The buyer has not selected a shipping addressfrom the Amazon AddressBook widget.

Display the Amazon AddressBook widget tothe buyer to collect shipping information.

PaymentPlanNotSet The buyer has not set a payment method for thegiven order reference.

Display the Amazon Wallet widget to thebuyer to collect payment information.

AmountNotSet You have not set the amount for the orderreference.

Call the SetOrderReferenceDetailsoperation and specify the order amount in theOrderTotal request parameter.

PaymentMethodNotAllowed The payment method selected by the buyer isnot allowed for this order reference.

Display the Amazon Wallet widget andrequest the buyer to select a different paymentmethod.



Order Reference States and Reason CodesThe following diagram depicts the state transition of an Order Reference object:

The following table describes each state that an order reference can be in, the allowed operations on a state, and thereasons why an Order Reference object can end up in a state:

State Description Allowed Operations Reason Codes

Draft An Order Reference object isin the Draft state prior to bebeing confirmed by callingthe ConfirmOrderReferenceoperation.




Open An Order Reference objectmoves to the Open state afterit is confirmed by calling theConfirmOrderReferenceoperation. Authorizations can onlybe requested on an order referencethat is in the Open state.


CancelOrderReference (only ifthere are no Pending, Completed,or Closed captures against theOrder Reference object)

CloseOrderReference

Authorize

Suspended An Order Reference object moves

m ws off amazon payment sap i reference

Documents

amazon mws

related topics