Pay

Description

The Pay operation initiates a transaction to move funds from a sender to a recipient. The SenderTokenId you obtain from a Co-Branded service request specifies the payment instrument the sender chose for the transaction. If the payment method is an Amazon account balance transfer (ABT), the transaction completes synchronously. If the payment method is a bank account (ACH) or a credit card (CC), the transaction completes asynchronously. For more information about synchronous and asynchronous transactions, see Instant Payment Notification.

The difference in the marketplace implementation of Pay is the recipient token ID, which identifies the recipient. When the recipient signs up on your web site to purchase your marketplace services, part of the process is sending the Co-Branded service request to receive a recipient tokenID. The recipient token ID returned identifies the recipient and enables them to be paid in the money transfer.

The Pay parameters also specify the marketplace fee and who is charged the Amazon FPS fee (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 consist of a flat fee, a percentage of the transaction, or a combination of the two.

Request Parameters

Parameter	Description	Required
`CallerDescription`	Description of this transaction for the caller. Type: String Default: None Constraint: Max size = 160 characters	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.	Conditional
`SenderTokenId`	Specifies the sender token used in the transaction. You obtain this value from the response to the Co-Branded service request. Type: String Default: None	Yes
`TransactionAmount`	Transaction amount charged to the sender for the purchase of an item or service. 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 (max size=35 characters) generated by Amazon FPS for this transaction. Type: String
`TransactionStatus`	Provides the status of the transaction. Type: TransactionStatus

TransactionId

Unique ID (max size=35 characters) generated by Amazon FPS for this transaction.

Type: String

TransactionStatus

Provides the status of the transaction.

Type: TransactionStatus

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

Pay careful attention to all of the response elements listed in the preceding table, especially the response status element which indicates success or failure for the Pay operation. Errors are returned only for REST. For SOAP, an error results in a SOAP fault. If the response status is failure, the Errors element includes an error code that identifies the source of the failure. If the response status is success, the elements listed in the preceding table are returned.

Errors

This action can return the following errors:

Examples

The following sections show a sample request and response.

Sample REST Request

https://fps.amazonaws.com/?
  Action=Pay&
  AWSAccessKeyId=0656Example83G2&
  SignatureVersion=1&
  Timestamp=2008-08-06T13%3A00%3A01Z&
  CallerReference=2938SDF2983&
  TransactionAmount.Value=1200&
  TransactionCurrencyCode=USD&
  RecipientTokenId=254656Example83987&
  SenderTokenId=6SC9UJExampleEYUBJM1&
  Version=2008-09-17&
  Signature=<URL-encoded signature value>

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:Pay 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.1</ns2:Amount>
     </ns2:TransactionAmount>
     <ns2:CallerReference>ReferenceString????rpXe12275876325471</ns2:CallerReference>
     <ns2:CallerDescription>DescriptionString-????i86x12275876325471</ns2:CallerDescription>
     <ns2:SenderDescription>DescriptionString-????0m6112275876325471</ns2:SenderDescription>
   </ns2:Pay>
 </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Sample Response to REST Request

<PayResponse xmlns="http://fps.amazonaws.com/doc/2008-09-17/">
   <PayResult>
      <TransactionId>13N8UPFET32I4I7FCF9T4ZKFETETINTK56Q</TransactionId>
      <TransactionStatus>Pending</TransactionStatus>
   </PayResult>
   <ResponseMetadata>
      <RequestId>b415f09d-5924-4315-b31a-21c977c85c39:0</RequestId>
   </ResponseMetadata>
</PayResponse>

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">Pay:Response</wsa:Action>
   <wsa:MessageID xmlns:wsa="http://www.w3.org/2005/08/addressing">urn:uuid:b415f09d-5924-4315-b31a-21c977c85c39</wsa:MessageID>
 </SOAP-ENV:Header>
 <SOAP-ENV:Body>
   <PayResponse xmlns="http://fps.amazonaws.com/doc/2008-09-17/">
     <PayResult>
       <TransactionId>13N8UPFET32I4I7FCF9T4ZKFETETINTK56Q</TransactionId>
       <TransactionStatus>Pending</TransactionStatus>
     </PayResult>
     <ResponseMetadata>
       <RequestId>b415f09d-5924-4315-b31a-21c977c85c39:0</RequestId>
     </ResponseMetadata>
   </PayResponse>
 </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Pay