Amazon provides a web site where Amazon Payments account holders can manage their account and track their transactions. This web site is where most people will interact with FPS, and because Amazon Payments is basically an extension of Amazon’s account management system, the features available here will be familiar to Amazon's customers.
Here is a brief summary of the many things you can do at this web site:
The site provides an overview of the transaction activity in your Amazon Payments account. The transactions may be filtered according to the transaction type, the payment methods used, and when the transactions occurred.
The Amazon Payments system maintains a balance of available funds. The account balance can be used for purchases or for paying FPS transaction fees. Money can be added to this balance by transferring funds from a verified bank account linked to the Amazon Payments account or by receiving payments through FPS. Money can also be transferred out of the balance into a linked bank account.
Amazon Payments accounts have limits on the amount of money that can be transferred through them. The limits applied differ according to the type of the account and whether or not you have entered into any special bulk transaction arrangement with Amazon (see Amazon Payments Accounts” in Chapter 10).
Amazon Payments accounts can be linked to multiple credit card or bank accounts. These linked accounts can be used as a source of funds for FPS transactions. When you link a bank account to your Amazon Payments account and verify it, you can transfer funds between these accounts and your Amazon Payments account.
Account holders can view the long-lived sender tokens they have authorized to be installed in their account and can easily cancel these tokens. Only sender tokens that can be used multiple times, such as the MultiUse and Recurring token types, can be viewed on the web site. Caller and recipient tokens cannot be viewed.
You will want know as soon as possible when one of your customers cancels an authorized token that was installed on behalf of your application. FPS provides a notification mechanism that can inform you when a third-party cancels a token; for more information see Subscribing to FPS Event Notifications” in Chapter 12.
You can have multiple addresses associated with your Amazon Payments account. If you have a business account, you can also change the contact details for your business.
In addition to the standard features available to all users of the Amazon Payments web site, there are some additional features that are only available to those account holders who have registered for an FPS developer account.
FPS developers can configure the branding elements that will be displayed to third parties when they are directed to the CBUI pipeline (refer back to The Co-branded UI (CBUI) Pipeline” in Chapter 10).
FPS provides API operations for programatically retrieving information about your Amazon Payments account. The GetAccountBalance and GetAccountActivity operations allow developers to retrieve transaction and balance information in XML documents.
It is not possible to perform any account management functions through the FPS API, such as transferring funds between your internal balance and external bank account or updating your co-branding preferences. You must visit the web site to perform these tasks.
The GetAccountBalance operation detailed in Table 11-14 retrieves the internal balance stored in your Amazon Payments account. The balance information is divided into different categories, and it includes details about funds in pending transactions that may soon affect the overall account balance.
Table 11-14. GetAccountBalance request parameters
| Parameter Name | Description | Required? |
|---|---|---|
| Action | GetAccountBalance | Yes |
Here is an XML document returned by the operation:
<ns3:GetAccountBalanceResponse
xmlns:ns3='http://fps.amazonaws.com/doc/2007-01-08/'>
<AccountBalance>
<TotalBalance>
<CurrencyCode>USD</CurrencyCode>
<Amount>62.052500</Amount>
</TotalBalance>
<PendingInBalance>
<CurrencyCode>USD</CurrencyCode>
<Amount>0.000000</Amount>
</PendingInBalance>
<PendingOutBalance>
<CurrencyCode>USD</CurrencyCode>
<Amount>0.520000</Amount>
</PendingOutBalance>
<AvailableBalances>
<DisburseBalance>
<CurrencyCode>USD</CurrencyCode>
<Amount>62.052500</Amount>
</DisburseBalance>
<RefundBalance>
<CurrencyCode>USD</CurrencyCode>
<Amount>62.052500</Amount>
</RefundBalance>
</AvailableBalances>
</AccountBalance>
<Status>Success</Status>
<RequestId>c0d4f4f3-2e33-4a77-b1f6-3a948d55399f:0</RequestId>
</ns3:GetAccountBalanceResponse>Information about an Amazon Payments account balance is returned by the service in an AccountBalance element, as described in Table 11-15, in which the balance is divided into two types and five separate elements that summarize the funds in the account.
Table 11-15. Account balances of Amazon Payments accounts
Example 11-11 defines a method that retrieves the balance details for your account and returns a hash dictionary containing a breakdown of the various amounts.
Example 11-11. Get account balance: FPS.rb
def get_account_balance
parameters = build_query_params(API_VERSION, SIGNATURE_VERSION,
{
'Action' => 'GetAccountBalance'
})
xml_doc = do_fps_query(parameters)
return {
:total => {
:amount => xml_doc.elements['//TotalBalance/Amount'].text,
:currency => xml_doc.elements['//TotalBalance/CurrencyCode'].text
},
:pending_in =>{
:amount => xml_doc.elements['//PendingInBalance/Amount'].text,
:currency => xml_doc.elements['//PendingInBalance/CurrencyCode'].text
},
:pending_out => {
:amount => xml_doc.elements['//PendingOutBalance/Amount'].text,
:currency => xml_doc.elements['//PendingOutBalance/CurrencyCode'].text
},
:disburse_balance => {
:amount => xml_doc.elements['//DisburseBalance/Amount'].text,
:currency => xml_doc.elements['//DisburseBalance/CurrencyCode'].text
},
:refund_balance => {
:amount => xml_doc.elements['//RefundBalance/Amount'].text,
:currency => xml_doc.elements['//RefundBalance/CurrencyCode'].text
}
}
endThe get_account_balance
method is very simple and requires no arguments.
# Retrieve the balance of your Amazon Payments account
irb> fps.get_account_balance
{:pending_out=>{:amount=>"0.520000", :currency=>"USD"},
:disburse_balance=>{:amount=>"62.052500", :currency=>"USD"},
:refund_balance=>{:amount=>"62.052500", :currency=>"USD"},
:total=>{:amount=>"62.052500", :currency=>"USD"},
:pending_in=>{:amount=>"0.000000", :currency=>"USD"}}The GetAccountActivity operation retrieves a listing of the transactions that have been performed using your Amazon Payments account within a specific time period. The listing can be filtered by a number of criteria to focus on the specific transactions you are interested in. You can specify whether you need all the information in the listing result, or whether you only need a summary.
This operation, outlined in Table 11-16, returns a maximum of 200 transactions in any one listing. If you need information about a large number of transactions, you may need to perform multiple requests to retrieve them all.
Table 11-16. GetAccountActivity request parameters
| Parameter Name | Description | Required? |
|---|---|---|
| Action | GetAccountActivity | Yes |
| StartDate | Only transactions that were initiated after this date are returned. This date cannot be in the future. | Yes |
| EndDate | Only transactions that occurred before this date are returned. If this value is not provided, FPS uses the current date as the end date. | No |
| ResponseGroup | Specifies the level of transaction detail the service
will return. The value can be Summary, which provides a brief
summary of the transaction details, or Detail, which includes all available
transaction information. If this parameter is not specified,
the Detail mode will be
used. | No |
| Operation | Filters the listing according to the operation that created the transaction. This value can be any of the following: Pay, Refund, Settle, SettleDebt, WriteOffDebt, FundPrepaid, DepositFunds, or WithdrawFunds. | No |
| PaymentMethod | Filters the listing according to the payment method
used. This value will be either Credit card (CC), Bank checking account (ACH), or Amazon Payments account
balance (ABT). | No |
| MaxBatchSize | Specifies the maximum number of transactions to return, between 20 and 200. If this value is not provided, up to 20 transactions are returned in the listing. | No |
| SortOrderByDate | Transactions can be returned in either ascending or descending date order. | No |
| Role | Filters the listing according to the role you played in
the transaction; values returned will be either Sender, Receiver or Caller. | No |
| Status | Filters the listing to include only transactions with a
specific status value. This value may be any of the following:
Success, Failure, Initiated, Reinitiated, or TemporaryDecline. | No |
Here is an XML document returned by the operation with the
default setting of Detail for the
ResponseGroup parameter. The document returned when you use the
Summary ResponseGroup setting does
not include the TransactionParts elements.
<ns3:GetAccountActivityResponse
xmlns:ns3='http://fps.amazonaws.com/doc/2007-01-08/'>
<ResponseBatchSize>1</ResponseBatchSize>
<Transactions>
<TransactionId>12MRCQZ7825E8JB4PS1E7B6KUJBL7T1HAIQ</TransactionId>
<CallerTransactionDate>2007-10-18T23:03:28.000-07:00</CallerTransactionDate>
<DateReceived>2007-10-18T22:47:09.000-07:00</DateReceived>
<DateCompleted>2007-10-18T23:03:28.000-07:00</DateCompleted>
<TransactionAmount>
<CurrencyCode>USD</CurrencyCode>
<Amount>2.500000</Amount>
</TransactionAmount>
<Operation>Settle</Operation>
<Status>Success</Status>
<ErrorCode/>
<TransactionParts>
<AccountId>VCNTDNEJNQUQ4H1V7QDQFU5IAPGKN8UIFDUV75</AccountId>
<Role>Recipient</Role>
<Name>James Murty</Name>
<Reference/>
<Description/>
<FeePaid>
<CurrencyCode>USD</CurrencyCode>
<Amount>0.175000</Amount>
</FeePaid>
</TransactionParts>
<TransactionParts>
<AccountId>VCNTDNEJNQUQ4H1V7QDQFU5IAPGKN8UIFDUV75</AccountId>
<Role>Caller</Role>
<Name>James Murty</Name>
<Reference>Test Reserve</Reference>
<Description/>
<FeePaid>
<CurrencyCode>USD</CurrencyCode>
<Amount>0.000000</Amount>
</FeePaid>
</TransactionParts>
<PaymentMethod>CC</PaymentMethod>
<SenderName>Mr Customer</SenderName>
<CallerName>James Murty</CallerName>
<RecipientName>James Murty</RecipientName>
<Fees>
<CurrencyCode>USD</CurrencyCode>
<Amount>0.175000</Amount>
</Fees>
<Balance>
<CurrencyCode>USD</CurrencyCode>
<Amount>0</Amount>
</Balance>
<CallerTokenId>74UFLUGNG3AF5FHD67114VUNNE...U8QQQVVHQXQNJN3TZC2</CallerTokenId>
<SenderTokenId>U27XQ55SQUTG32I4Z8UB6KTBFY...K186HA4G3N1DO4XGOV</SenderTokenId>
<RecipientTokenId>76UF2UENGSAZ5F8D571T4I...IQU3QQLVEHQBQKJNSTJCE</RecipientTokenId>
</Transactions>
<Status>Success</Status>
<RequestId>982c4c8f-4be6-492c-aab2-c28764660c6c:0</RequestId>
</ns3:GetAccountActivityResponse>The response document includes a set of Transactions elements, each of which is a Transaction as described in Table 11-4. The response also includes two additional elements:
Specifies how many transactions were included in the listing.
If there were more transactions within the specified time period than could be returned in the listing, the response will include a timestamp value that can be used in follow-up requests to retrieve the next batch of transactions. If you need to retrieve all the transactions within a time frame, you can check for the presence of this element and perform follow up requests until the element is no longer included in the response.
Example 11-12 defines a method
that retrieves a listing of transactions that captures the activity in
your Amazon Payments account for a specified time period. The start
date provided to this method must be a Ruby Time
Example 11-12. Get account activity: FPS.rb
def get_account_activity(start_date, options={})
parameters = build_query_params(API_VERSION, SIGNATURE_VERSION,
{
'Action' => 'GetAccountActivity',
'StartDate' => start_date.iso8601,
# Settings
'EndDate' => options[:end_date],
'MaxBatchSize' => options[:max_batch_size],
'SortOrderByDate' => options[:sort_order],
# Filters
'Operation' => options[:operation],
'PaymentMethod' => options[:payment_method],
'ResponseGroup' => options[:response_group],
'Role' => options[:role],
'Status' => options[:status],
})
xml_doc = do_fps_query(parameters)
transactions = []
xml_doc.elements.each('//Transactions') do |t|
transactions << parse_transaction(t)
end
result = {
:transactions => transactions,
:batch_size => xml_doc.elements['//ResponseBatchSize'].text,
}
if xml_doc.elements['//StartTimeForNextTransaction']
result[:next_start_time] =
xml_doc.elements['//StartTimeForNextTransaction'].text
end
return result
endHere are the commands to return all the transaction activity within the last 24 hours.
# Create a start time of one day (24 hours) ago
irb> start_time = Time.now - 60 * 60 * 24
# Perform the GetAccountActivity operation
irb> fps.get_account_activity(start_time)
{:transactions=>
[{:transaction_amount=>{:amount=>"2.500000", :currency_code=>"USD"},
:recipient_name=>"James Murty",
:fees=>{:amount=>"0.175000", :currency_code=>"USD"},
:sender_name=>"Mr Customer",
:caller_token_id=>
"74UFLUGNG3AF5FHD67114VUNNEBDNUVL5VRDCI8HK6PIRU8QQQVVHQXQNJN3TZC2",
:balance=>{:amount=>"0", :currency_code=>"USD"},
:caller_date=>"2007-10-18T23:03:28.000-07:00",
:sender_token_id=>
"U27XQ55SQUTG32I4Z8UB6KTBFYBUIBLKPXAGVGM3M92PSEK186HA4G3N1DO4XGOV",
:recipient_token_id=>
"76UF2UENGSAZ5F8D571T4IUNKEDDNLV25VDDQI8TKTPIQU3QQLVEHQBQKJNSTJCE",
:received_date=>"2007-10-18T22:47:09.000-07:00",
:id=>"12MRCQZ7825E8JB4PS1E7B6KUJBL7T1HAIQ",
:parts=>
[{:name=>"James Murty",
:role=>"Recipient",
:fee_paid=>{:amount=>"0.175000", :currency_code=>"USD"},
:description=>nil,
:id=>"VCNTDNEJNQUQ4H1V7QDQFU5IAPGKN8UIFDUV75",
:reference=>nil},
{:name=>"James Murty",
:role=>"Caller",
:fee_paid=>{:amount=>"0.000000", :currency_code=>"USD"},
:description=>nil,
:id=>"VCNTDNEJNQUQ4H1V7QDQFU5IAPGKN8UIFDUV75",
:reference=>"Test Reserve"}],
:operation=>"Settle",
:error_code=>nil,
:completed_date=>"2007-10-18T23:03:28.000-07:00",
:status=>"Success",
:caller_name=>"James Murty",
:method=>"CC"}],
:batch_size=>"1"}To filter the results to a particular transaction type and reduce the level of detail returned in the listing, we can specify filtering options.
irb> options = {:response_group => 'Summary', :operation => 'Refund'}
irb> fps.get_account_activity(start_time, options)
{:batch_size=>"1",
:transactions=>
[{:completed_date=>"2007-10-18T21:58:46.000-07:00",
:fees=>{:currency_code=>"USD", :amount=>"-0.100000"},
:caller_token_id=>
"74UFLUGNG3AF5FHD67114VUNNEBDNUVL5VRDCI8HK6PIRU8QQQVVHQXQNJN3TZC2",
:operation=>"Refund",
:sender_token_id=>
"71UFVU7NGNAK5F3DC71Z47UNGE3DNCVJ5VJD6I8KKJPISU3QQ8VVHQLQEJNCTNC1",
:balance=>{:currency_code=>"USD", :amount=>"0"},
:caller_name=>"James Murty",
:caller_date=>"2007-10-18T21:58:52.000-07:00",
:sender_name=>"James Murty",
:id=>"12MRA1CRL3RJPH5OHDJ7319BBSJ9NCM9LBF",
:error_code=>nil,
:received_date=>"2007-10-18T21:58:46.000-07:00",
:recipient_name=>"Mr Customer",
:status=>"Success",
:method=>"CC",
:transaction_amount=>{:currency_code=>"USD", :amount=>"1.000000"}}]}