Reserve

Description

The Reserve operation reserves the total price of a purchase against the sender's payment instrument. To charge the payment instrument, you must subsequently issue a Settle request. A reserve authorization is only valid for 7 days. After that, Amazon FPS automatically cancels the transaction and notifies you.

	Note
	You can settle a reserved transaction only once.

The marketplace implementation of Reserve includes the recipient token ID, which identifies the recipient. You get this in the response from a marketplace Co-Branded service request (which you make when the recipient signs up on your web site for your marketplace services). The recipient token ID returned identifies the recipient and is required when you later move money from the sender to the recipient.

The Reserve parameters also specify the marketplace fee and who is charged for it (the caller or recipient). The marketplace fee is typically the fee charged by the caller to the recipient for the service of hosting the recipient's e-commerce store. The fee can be charged on a per-transaction basis and consists of a flat fee, a percentage of the transaction, or a combination of the two.

To cancel a reserved payment, send a Cancel request.

Request Parameters

Parameter	Description	Required
`CallerDescription`	Description of this transaction for the caller. Type: String Default: None Constraint: Max size = 160 characters Condition: If you use dynamic, soft descriptors, you must supply a caller description. For more information, see `DescriptorPolicy`.	No
`CallerReference`	A value you provide that uniquely identifies the request. For more information, see Important Values to Store in Your Database. Type: String Default: None Constraint: Max size = 128 characters	Yes
`ChargeFeeTo`	Specifies the participant paying the Amazon FPS fee in the transaction. The participant can only be a recipient or a caller. The following rules apply for specifying this parameter. If you are playing the role of a recipient and a caller, then set the value of this parameter to `recipient`. If you are playing the role of caller and facilitating the transaction between a sender and a recipient, where the recipient pays the fee, then the fee is collected from the funds that are received from the sender. If you (caller) are paying the fees, then the fee is collected from your account balance. Ensure that you have a sufficient account balance to cover for the fees. If your account has an insufficient account balance, Amazon FPS rejects the transaction. Type: String Default: None Valid values: `Recipient` \| `Caller`	No
`DescriptorPolicy`	Specifies the entity whose name and contact details would be displayed in the sender's credit card or bank account statement. Type: Descriptor Policy Default: None	No
`MarketplaceFixedFee`	Specifies the fee charged by the marketplace developer as a fixed amount of the transaction. The `MarketplaceFixedFee` is a separate fee from the Amazon Payments fee, which is paid by the caller or recipient. You can express the fixed fee as an amount, such as `10` to mean $10. If you charge a variable fee per transaction, use the MarketplaceVariableFee parameter. Type: Amount Default: If both the `MarketplaceFixedFee` and the `MarketplaceVariableFee` are unspecified, then the corresponding maximum values, if any, from the recipient token are used.	No
`MarketplaceVariableFee`	Specifies the fee charged by the marketplace developer as a percentage of the transaction. The `MarketplaceVariableFee` is a separate fee from the Amazon Payments fee and is paid by the recipient. You can express the variable fee as a decimal, such as `5` to mean 5%. If you charge a fixed amount per transaction, use the `MarketplaceFixedFee` parameter. Type: Decimal Default: None	No
`RecipientTokenId`	Specifies the recipient token used in the transaction. You obtain this value in response from the Co-Branded service Recipient Token API (for more information, see Recipient Token API). Type: String Default: None	Yes
`SenderDescription`	Description of this transaction for the sender. If you use dynamic soft descriptors, you must specify a value for the sender description. Type: String Default: None Constraint: Max size = 160 characters Condition: If you use dynamic soft descriptors, you must specify a value for the sender description. For more information, see `DescriptorPolicy`.	Conditional
`SenderTokenId`	Specifies the sender token to be used for this transaction. You obtain this value in a Co-Branded service response. Type: String Default: None	Yes
`TransactionAmount`	Transaction amount charged to the sender. To understand how to correctly specify the amount in a REST request, see the example request at the end of this topic. Type: Amount Default: None	Yes
`TransactionTimeoutInMins`	Specifies the number of minutes before the request times out. Use this parameter to specify a timeout value that is acceptable for your business. If Amazon FPS cannot complete the transaction in the time allotted, the transaction is marked as failed and you receive an IPN notification (if you are using IPN). Type: Integer (number of minutes) Default: 10080 (seven days)	No

You must also include parameters that are common to all requests. The common parameters are defaulted in SOAP calls but must be explicitly added in REST calls. For more information, see Common Request Parameters.

Response Elements

Element Description

Element	Description
`TransactionId`	Unique ID generated by Amazon FPS for this transaction. This element is returned if the transaction was accepted by Amazon FPS. If the transaction is a Refund request, this parameter will contain the id of the Refund transaction only. Type: String Size: 35 Bytes
`TransactionStatus`	Provides the status of the transaction. Type: TransactionStatus

TransactionId

Unique ID generated by Amazon FPS for this transaction. This element is returned if the transaction was accepted by Amazon FPS. If the transaction is a Refund request, this parameter will contain the id of the Refund transaction only.

Type: String

Size: 35 Bytes

TransactionStatus

Provides the status of the transaction.

Type: TransactionStatus

Responses also include elements common to all responses. For more information, see Common Response Elements.

Errors

This action can return the following errors:

Examples

Sample REST Request

https://fps.sandbox.amazonaws.com?
Action=Reserve
&AWSAccessKeyId=AKIAIIFXJCFIHITREP4Q
&CallerDescription=Reserve
&CallerReference=CallerReference05
&RecipientTokenId=254656Example83987
&SenderTokenId=553IPMACGAZ2J4N1L7BJ3UMNRFTQU4V9NT4RJCTVADDJKXQ6L1ZAKSIUNPIRTTI1
&Signature=JZ0eeVTM5LwbvziLdA%2FSMve7mgrEoTvTGZJ%2BpsgZkM0%3D
&SignatureMethod=HmacSHA256
&SignatureVersion=2
&Timestamp=2009-10-06T07%3A51%3A04.140Z
&TransactionAmount.CurrencyCode=USD
&TransactionAmount.Value=1
&Version=2008-09-17

Sample SOAP Request

<SOAP-ENV:Body wsu:Id="body" xmlns:wsu=
"http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
   <ns2:Reserve xmlns:ns2="http://fps.amazonaws.com/doc/2008-09-17/">
   <ns2:SenderTokenId>76PSX31MM77T81ExampleQVDNQPG5GFAK</ns2:SenderTokenId>
   <ns2:RecipientTokenId>6SC9UJ1VJEExampleBTBNUNEYUBJM1K</ns2:RecipientTokenId>
     <ns2:TransactionAmount>
       <ns2:CurrencyCode>USD</ns2:CurrencyCode>
       <ns2:Amount>1.10</ns2:Amount>
     </ns2:TransactionAmount>
     <ns2:CallerReference>
      ReferenceString????Qlrd12275864150791
     </ns2:CallerReference>
     <ns2:CallerDescription>
      DescriptionString-????UQAu12275864150791
     </ns2:CallerDescription>
     <ns2:SenderDescription>
      DescriptionString-????kbPT12275864150791
     </ns2:SenderDescription>
   </ns2:Reserve>
 </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Sample Response to REST Request

<ReserveResponse xmlns="http://fps.amazonaws.com/doc/2008-09-17/">
  <ReserveResult>
    <TransactionId>14GKD9GE66FAA63E6O6B2JDPZKN53LZ7F22</TransactionId>
    <TransactionStatus>Pending</TransactionStatus>
  </ReserveResult>
  <ResponseMetadata>
    <RequestId>d13273fc-fca8-4963-8fbc-66d03e66055f:0</RequestId>
  </ResponseMetadata>
</ReserveResponse>

Sample Response to SOAP Request

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
 <SOAP-ENV:Header>
   <wsa:RelatesTo xmlns:wsa="http://www.w3.org/2005/08/addressing">
    MESSAGE123
   </wsa:RelatesTo>
   <wsa:To xmlns:wsa="http://www.w3.org/2005/08/addressing">
    http://www.w3.org/2005/08/addressing/anonymous
   </wsa:To>
   <wsa:Action xmlns:wsa="http://www.w3.org/2005/08/addressing">
    Reserve:Response
   </wsa:Action>
   <wsa:MessageID xmlns:wsa="http://www.w3.org/2005/08/addressing">
    urn:uuid:a9e1fc80-03f6-4e1b-a1c0-541df545afac
   </wsa:MessageID>
 </SOAP-ENV:Header>
 <SOAP-ENV:Body>
   <ReserveResponse xmlns="http://fps.amazonaws.com/doc/2008-09-17/">
     <ReserveResult>
       <TransactionId>13N8TKAK15P3GOIPLP796OKSB66C6K2LBEK</TransactionId>
       <TransactionStatus>Pending</TransactionStatus>
     </ReserveResult>
     <ResponseMetadata>
       <RequestId>a9e1fc80-03f6-4e1b-a1c0-541df545afac:0</RequestId>
     </ResponseMetadata>
   </ReserveResponse>
 </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Sample IPN Pending Notification to Rest Request

--------------------------
transactionId: 14GKD9GE66FAA63E6O6B2JDPZKN53LZ7F22
statusMessage: The transaction is awaiting a response from the backend payment processor.
transactionDate: 1254815482
signatureVersion: 2
signatureMethod: RSA-SHA1
buyerEmail: new_premium@amazon.com
notificationType: TransactionStatus
callerReference: CallerReference05
operation: RESERVE
transactionStatus: PENDING
transactionAmount: USD 1.00
recipientEmail: test-caller@amazon.com
buyerName: Test Business
signature: NvFCZMralNEepynuIhhXJc+jpK1ZMdFLBMcXFv6Vq1jhpdLX/B9T0lluOUv74I6xgO8L2UemgV4S
ZCejlQZ3glwKnEM75lKVlHx34IKp1RFm1DjQOO5KaYGQUNMu1ouYK1YmQUHCuktdLnTXjkxjn0lv
9U4EyzDe8l/tLp2nlAqRF4J7PIhdTkWvBYNYhZrEy5A895OMf9uFtwX8Eyg4lTDMVwEWJoG8CTxJ
qtcsKabmbF9Blwhfe3f+viTnv39YRDb+PZKnpl/XqkKYdNEXClRy3g6xpF/14FJ4hA+A1UP+A+No
17b6lZuKmd5dbdvqTQKOxEAfR6lL1gTzAYY/8w==
recipientName: Test Business
paymentMethod: CC
certificateUrl: https://fps.sandbox.amazonaws.com/certs/090909/PKICert.pem
paymentReason: Reserve
statusCode: PendingNetworkResponse
--------------------------

Sample IPN Success Notification to Rest Request

--------------------------
transactionId: 14GKD9GE66FAA63E6O6B2JDPZKN53LZ7F22
statusMessage: The requested amount was reserved successfully against the given payment instrument.
transactionDate: 1254815482
signatureVersion: 2
signatureMethod: RSA-SHA1
buyerEmail: new_premium@amazon.com
notificationType: TransactionStatus
callerReference: CallerReference05
transactionAmount: USD 1.00
transactionStatus: RESERVED
operation: RESERVE
recipientEmail: test-caller@amazon.com
buyerName: Test Business
signature: RIVZQHF+NmGUEbZNXijRcSwmeBTcYg/GCZD/xeUpLLXMwDNrM1D0+ewFLiUqJvdbQueUilBkJPoB
5j+ZYvvrXfldEofaMZ85pz2pA/DyUicWR4e/DgcZrk/B7FO6LL9ki6aE0qPzpRR/nzRcLiu1lH2a
zUPnMVf3dT+SfDhaKyKIfX40QYL6U3m3NTaGYSUbBwzZczg9qTpu4zZ2kCK3uidg7P78sXQEnDhm
8kDAJC4obYFVlZi/Bd8UalxIYf2ko8SkhQ4vbsipjNg++HJ7KlJAa41GTVCrJfeX0Y4r7ToONEaQ
iu/zn8X+q/jPqgGZN+Z2KNls6XVw4Waw3eXbug==
recipientName: Test Business
paymentMethod: CC
certificateUrl: https://fps.sandbox.amazonaws.com/certs/090909/PKICert.pem
paymentReason: Reserve
statusCode: Success
--------------------------