Amazon Flexible Payments Service
Marketplace Quick Start (API Version 2010-08-28)
AWS Documentation » Amazon Flexible Payments Service » Marketplace Quick Start » API Reference » Actions » Pay
« PreviousNext »
View the PDF for this guide.Go to the AWS Discussion Forum for this product.Did this page help you?  Yes | No |  Tell us about it...

Pay

Description

The Pay action initiates a transaction to move funds from a sender to a recipient. The SenderTokenId, obtained from a Co-Branded service request, specifies the payment instrument the sender chose to execute the transaction. If the payment method specified is 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.

The marketplace implementation of Pay 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 website 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.

In addition, for marketplace applications, the Pay parameters also specify the marketplace fee and who is charged (the caller or recipient). The marketplace fee is typically the fee you charge 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

ParameterDescriptionRequired

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.

  • ChargeFeeTo must be set to be consistent with the value for the Recipient Token API recipientPaysFee parameter set when the recipient signed up for your marketplace services. Otherwise, you will get an error message.

Type: String

Default: Recipient

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

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.

Important

The value for MarketPlaceFixedFee must be less than or equal to the amount specified for the recipient token. If not, an InvalidParams error is returned with the following messages:

"The MarketPlaceFixedFee ($amount-specified) specified is greater than the maximum fixed fee ($amount-agreed) agreed by the recipient.

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.

Important

The value for MarketPlaceVariableFee must be less than or equal to the amount specified for the recipient token. If not, an InvalidParams error is returned with the following messages:

"The MarketPlaceVariableFee ($amount-specified) specified is greater than the maximum variable fee ($amount-agreed) agreed by the recipient.

Type: Decimal

Default: None

No

OverrideIPNURL

Specifies the URL to receive the Instant Payment Notification (IPN) for the request. The IPN URL set with this parameter takes precedence over the IPN URL set in your account.

Type: String

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

Condition: Required for marketplace transactions

Conditional

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

ElementDescription

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. Use this to determine if the transaction has completed, failed, or has not completed yet.

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

Sample REST Request

https://fps.sandbox.amazonaws.com?
Action=Pay
&AWSAccessKeyId=AKIAIOSFODNN7EXAMPLE
&CallerDescription=MyWish
&CallerReference=CallerReference02
&RecipientTokenId=254656Example83987
&SenderTokenId=553ILMLCG6Z8J431H7BX3UMN3FFQU8VSNTSRNCTAASDJNX66LNZLKSZU3PI7TXIH
&Signature=0AgvXMwJmLxwdMaiE7lMHZxc6384h%2FjBkiTserQFpBQ%3D
&SignatureMethod=HmacSHA256
&SignatureVersion=2
&Timestamp=2009-10-06T05%3A49%3A52.843Z
&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: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>14GK6BGKA7U6OU6SUTNLBI5SBBV9PGDJ6UL</TransactionId>
      <TransactionStatus>Pending</TransactionStatus>
   </PayResult>
   <ResponseMetadata>
      <RequestId>c21e7735-9c08-4cd8-99bf-535a848c79b4: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>

Sample IPN Pending Notification to Rest Request

--------------------------
transactionId: 14GK6BGKA7U6OU6SUTNLBI5SBBV9PGDJ6UL
statusMessage: The transaction is awaiting a response from the backend payment processor.
transactionDate: 1254808208
signatureVersion: 2
signatureMethod: RSA-SHA1
buyerEmail: new_premium@amazon.com
notificationType: TransactionStatus
callerReference: CallerReference02
transactionAmount: USD 1.00
transactionStatus: PENDING
operation: PAY
recipientEmail: test-caller@amazon.com
buyerName: Test Business
signature: uhP7uiCAvF/wTpRg6U279KTGPU2QHt23WiwNIB43i4ni1AEZOmBCTa3tUh1ugwxvIMSRASBhiG0u
rUl22IAXbt1iXfYprM2VrS0W0/W23BpkxInuNeAQWKu4W5/uuOJ1gVqyXsmxdFqJM7KKOh3IuUdC
wSfvPooR2qDQ2r5H/HjcOHfWQZk+BknX1w+aYpBRTa/mTYVxI6yq39mRyYPyMmh8r+tIPDevfnV1
B7sRljhXkJZh6rHJEi7CHq4oqbf8HZ38xaaqyggWy310SmMOuY3YcxNng0TOdbkgNAozMIQgfOsL
4yxiyVIZZJEKFPgT/OdebCZkR/raY1JeuBdYOg==
recipientName: Test Business
paymentMethod: CC
certificateUrl: https://fps.sandbox.amazonaws.com/certs/090909/PKICert.pem
paymentReason: MyWish
statusCode: PendingNetworkResponse
--------------------------

Sample IPN Success Notification to Rest Request

--------------------------
transactionId: 14GK6BGKA7U6OU6SUTNLBI5SBBV9PGDJ6UL
statusMessage: The transaction was successful and the payment instrument was charged.
transactionDate: 1254808208
signatureVersion: 2
signatureMethod: RSA-SHA1
buyerEmail: new_premium@amazon.com
notificationType: TransactionStatus
callerReference: CallerReference02
transactionAmount: USD 1.00
transactionStatus: SUCCESS
operation: PAY
recipientEmail: test-caller@amazon.com
buyerName: Test Business
signature: yuYUR4IkONbOfrerafrzC6raA90suk+jKXCgaV1LY0DxieYCAG2tAf9S7Rt231kzr0mhMMOIH0oe
ocHId3zdXp+2VaUbE4qGjPGfImpaBVxtxVwcdQP6cSFnvnKAbPbmQMdeIHMlgDeqVdtu5BO5skwj
e6bkDs+b8TQ3pHBYmXDc69aHceGqWAjMujs6m4HH3Othlb5Rj54s1IedwTi63HyQo+IAyRWvGPTn
nT6YlV0ajG38GCPoS9Wqa+UKcIr0sLoPY0y2StCDyjYHz7iVx+6lzG1eeCmZ++rAKU8swwhBiWGZ
56ajlKTzhoIJnK5yk7jFYreRt+Ff0W2fEnvEyQ==
recipientName: Test Business
paymentMethod: CC
certificateUrl: https://fps.sandbox.amazonaws.com/certs/090909/PKICert.pem
paymentReason: MyWish
statusCode: Success
--------------------------

Related Actions

Document Conventions« PreviousNext »
Terms of UseDid this page help you?  Yes | No |  Tell us about it...