Amex

Welcome to the last continuation of my Ruby-based assault on various online banking systems, much like my Lloyds TSB screen scraper.

However, this one doesn't rely on nasty screen-scraping. Instead, it uses the previous unknown internal API used by American Express for their "Amex UK" iPhone app. I suspect it works elsewhere, but I haven't tested.

This allows you to fetch the details of all the cards on your American Express login, as well as the most recent statement's transactions.

Changelog

v0.1.0 - Original version v0.2.0 - Support for multiple American Express cards, parsing using Nokogiri v0.3.0 - Adds support for loading the transactions from the most recent statement (but it's broken because I forgot to change something from testing :( ) v0.3.1 - Working version of v0.3.0 that will successfully load transactions from the most recent statement

Usage

The file example.rb provides a very simple example of how the code works, but here's a step by step:

  1. Ensure the gem is installed, and then include it in your Ruby file, or in your Gemfile where appropriate:
$ gem install amex
`require 'amex'
  1. You'll just need two variables, @username and @password, each unsurprisingly corresponding to different authentication details used
@username = "chuck_norris"
@password = "roundhousekick123"
  1. Instantiate a new instance of the Amex::Client object, passing in the username and password - this is used to perform the authentication required.

client = Amex::Client.new(@username, @password)

  1. Call the account method of the object you just made - it'll take a few seconds, and will return an Amex::CardAccount object. There'll only be one, since this only supports one card at a time right now.
accounts = client.accounts
 = accounts.first
puts .product
puts .type
puts .transactions.inspect

Data models

An Amex::CardAccount is created by Amex::CardAccount.new passing in a hash of the parsed XML. The parsing is done by Amex::Client.

An Amex::CardAccount instance has the following attributes:

  • product (string) - the type of card (e.g. "The Preferred Rewards Gold Card®")
  • card_number_suffix (string) - the last five digits of your card number
  • card_index (integer) - the internal number of the card on your account in the Amex system, starting from 0 (used internally by the gem)
  • lending_type (string) - either "Charge" or "Credit", depending on the type of credit arrangement you have
  • card_member_name (string) - your name, as recorded as the account holder
  • past_due (boolean) - is the card past its due payment date?
  • cancelled? (boolean)__ - has the account been cancelled?
  • is_basic/centurion/platinum/premium] (boolean) - which type of account does this conform to?
  • market (string) - the market that your card is registered too, e.g. "en_GB"
  • cardart (string)__ - a URL for an image of your card
  • loyalty_indicator (boolean) - does this card have some kind of loyalty scheme active? (e.g. Membership Rewards)
  • loyalty_programmes (array of Amex::LoyaltyProgramme objects) - the loyalty programmes this card belongs to
  • loyalty_balances (hash) - the loyalty balances on this card - the key is the name of the programme (string), and the balance is the value, as an integer
  • statement_balance (float) - the amount of the last statement on your account
  • payment_credits (float) - the combination of current payments and credits on your account
  • recent_charges (float) - charges since your last statement was issued (I believe)
  • total_balance (float) - what American Express refer to as your total balance, whatever that is!
  • payment_due (float) - the amount of money you need to pay before payment_due_date
  • payment_due_date (DateTime) - when the payment_due needs to be paid by
  • transactions (array) - an array of Amex::Transaction objects)

There are lots of extra useful methods here to make accessing some of the various properties easier. They're very self-explanatory - check lib/amex/card_account.rb.

A __Amex::LoyaltyProgramme has just two attributes:

  • name (string) - The name of the programme, most often "Membership Rewards"
  • balance (integer) - The balance of the programme

An __Amex::Transaction represents a transaction in your most recent American Express statement. It has four attributes:

  • amount (float) - The amount of the transaction
  • date (Date) - The date that the transaction was recorded
  • narrative (string) - The description shown on your statement, usually contaning the name of the merchant and their location
  • extra_details (hash) - This hash contains any extra pieces of information provided by American Express...for instance, foreign transactions have their exchange rate and commission. The name of the attribute will be the key, and its formatted value in the value in the hash.

There's one helper method currently available here, is_foreign_transaction?, which returns a boolean representing whether the transaction was foreign (i.e. in a non-native currency).

Limitations

  • You can only view transactions from the most recent statement. I intend to change this in due course to support pagination of some description.

License

Use this for what you will, as long as it isn't evil. If you make any changes or cool improvements, please let me know at [email protected].