t2_airtime 0.4.0 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 326cdd5b38f8d1c9749d76ba60268f5d5d7c98d1
-  data.tar.gz: '07913bae3db4c8571829ac372aac6a4112472023'
+  metadata.gz: 0a465a10576955be1e193df5070890b80d6884d4
+  data.tar.gz: 1182a3ea5ee57f02f690ac599ce286fc2bc5af53
 SHA512:
-  metadata.gz: 28c3c4f9055cbd006ff05b2bd629e874d93162859e25ab7180a463a61aa68028aad04e7d9bcad5da4038f8544bae6b06ebec7e2d6951006b5b617a601161853e
-  data.tar.gz: f64ba5dd35a5e8d7ba427526ccc732c5c6049fe9a979bdee67b4e0311b02983eb0bbaef0f6c5caa5cbca09840b79b414dab0b9cef154dc23e8285c18447cf3b6
+  metadata.gz: b77299b057c64afb6e9a4591d89cb308b027bc89d08c79c98c24eeab8ade528cc39e37160c7efce85a5abb4ed9f6f61dd86a8a53e21a8e57c85b430a5936290d
+  data.tar.gz: 5d13a4d7bb0f2bfa5ee5daf76eed8e3f67f897b5b667d464a8c72189bd2c316377ff34913a022e7e3a8b8fc5a03ee2371eb9c3df81bac68665d7a08d303edac5

data/README.md

@@ -1,464 +1,518 @@
-# TransferTo Airtime API
+FORMAT: 1A
+HOST: http://polls.apiblueprint.org/
 
-[TransferTo](https://www.transfer-to.com/home) helps businesses offer airtime top-ups, goods and services, and mobile money around the world in real time.
-TransferTo Airtime API enables developers to integrate TransferTo Top-up service into their system.
+# t2-airtime
 
-This gem is a convenience wrapper around the Airtime API. Requirement is that Two Factor Authentication (2FA) is enabled in your [TransferTo Shop](https://shop.transferto.com) Security Center section.
+T2-Airtime is a Ruby gem providing a proxy cache and a REST API to [TransferTo](https://www.transfer-to.com/home) Airtime service.
 
+## Authorization
 
-## Usage
-
-Create a new rails application:
-
-    rails new t2_airtime
-
-Add this line to your application's Gemfile:
-
-```ruby
-gem 't2_airtime'
-```   
-
-And then execute:
-
-    $ bundle 
-
-Create a `.env` file with the required information:
-
-    T2_SHOP_USER=
-    T2_AIRTIME_KEY=
-
-Start the server: `bundle exec puma -C config/puma.rb`
-
-### Routes
-
-The following routes are mada available to your application when you mount the API engine in `config/routes.rb`:
++ Two Factor Authentication (2FA) is enabled in your [TransferTo Shop](https://shop.transferto.com) Security Center section
++ You have your Transfer-To Shop username and Airtime secret key generated by 2FA
++ Export the secrets as environment variables `T2_SHOP_USER`, `T2_AIRTIME_KEY`
+    
+# Account
 
 ```ruby
-mount T2Airtime::Engine => '/t2_airtime'
+irb(main)> account= T2Airtime::Account.get
+irb(main)> T2Airtime::Account.serialize(account.data)
 ```
 
-* `/t2_airtime/account` [Account information](#account_info)
-* `/t2_airtime/countries` [List of all countries offered](#country_list)
-* `/t2_airtime/countries/<country_id>/operators` [List of all operators available for a certain country](#operator_list)
-* `/t2_airtime/countries/<country_id>/operators/<operator_id>/products` [List of all products available for a certain operator](#product_list)
-* `/t2_airtime/transactions` [List all transactions](#transaction_list)
-* `/t2_airtime/transactions/<id>` [Show a transaction](#transaction_show)
-    
-### API Object
-
-You can access the Airtime API in Ruby as:
+## Account Attributes
+- `id` (string) - Transfer-To TShop login name
+- `type` (string) - `Master` (main account) or `Retailer` (subaccount)
+- `name` (string) - Transfer-To TShop account name
+- `currency` (string) - Account currency (USD, GBP, EUR, etc...)
+- `balance` (float) - For `Master` account returns the account’s remaining balance. 
+For `Retailer` returns the account’s remaining limit balance of the day 
+if a daily limit is fixed. Else, returns the account remaining balance
+- `wallet` (float) - For `Master` returns the total remaining balance (sum 
+of all sub-accounts and current master). For `Retailer`: 
+        1. If balance is shared and daily limit is fixed: returns the fixed daily limit amount 
+        2. If balance is shared but daily limit is not fixed: returns "No Limit"
+        3. Else if balance is not shared: returns the remaining balance  
+- `fetchedAt` (string) - The date and time at which the information was fetched         
+
+# Country
 
 ```ruby
-api = T2Airtime::API.api
+irb(main)> countries= T2Airtime::Country.all
+irb(main)> T2Airtime::Country.serialize(countries.data)
 ```
 
-The following methods are available to the `api` object:
-
-* `ping` [Test the connection to the Airtime API](#ping)
-* `account_info` [Information regarding your TransferTo account](#account_info)
-* `country_list` [Retrieve available countries](#country_list)
-* `operator_list` [Retrieve all operators available for a certain country](#operator_list)
-* `product_list` [Retrieve all products available for a certain operator](#product_list)
-* `transaction_list` [Retrieve the list of transactions performed within a date range](#transaction_list)
-* `transaction_info` [Retrieve available information on a specific transaction](#transaction_info)
-* `topup` Recharge a destination number with a specified product.
-* `msisdn_info` Retrieve various information of a specific MSISDN as well as the list of all products configured for your specific account and the destination operator of the MSISDN.
-* `reserve_id` Reserve a transaction ID in the system. Maybe used in a topup operation.
-* `get_id_from_key` Retrieve the ID of a transaction previously performed based on the key used in the request at that time.
-
-Each method returns an object with the following properties:
-
-* `success?` `true` if the request was successful.
-* `status` The HTTP status of the reply. `200` indicates a successful request.
-* `error_code` The error code of the request. `0` indicates a successful request.
-* `error_message` The error message of the request. `Transaction successful` indicates a successful request.
-* `url` The full URL of the request.
-* `information` The response body as a hash.
-* `auth_key` The authorization key used in the request.
-* `headers` The HTTP Headers of the reply.
-* `raw` The raw body of the reply.
-
-<a name="ping"></a>
-#### Ping
-
-This method can be used for keep-alive. To test the connection with the API:
+## Country Attributes
+- `id` (integer) - Country Airtime ID
+- `name` (string) - The country name
+- `alpha3` (string) - The alpha3 code of the country
+- `callingCode` (float) - The international dialing code of the country
+- `fetchedAt` (string) - The date and time at which the information was fetched
+
+# Operator
 
 ```ruby
-irb(main)> response= T2Airtime::API.api.ping
-irb(main)> response.success?
-=> true
+irb(main)> operators= T2Airtime::Operator.all(666)
+irb(main)> T2Airtime::Operator.serialize(operators.data)
 ```
 
-<a name="account_info"></a>
-#### Account Information
+## Operator Attributes
+- `id` (integer) - Operator Airtime ID
+- `name` (string) - The operator name
+- `logo` (string) - The URL to the operator logo
+- `countryId` (float) - The country Airtime ID of the operator
+- `countryName` (float) - The country name
+- `countryAlpha3` (float) - The country alpha3
+- `fetchedAt` (string) - The date and time at which the information was fetched
 
-The `account_info` method retrieves the various information regarding your TransferTo account. 
-To format the response as JSON-API you can call `T2Airtime::Account.serialize(data)`.
+## Operator Relationships
+- `country.id` (integer) - Country Airtime ID
 
-From a Rails console (or Ruby file):
+# Product
 
 ```ruby
-irb(main)> response= T2Airtime::API.api.account_info
-irb(main)> account= T2Airtime::Account.serialize(response.data)
+irb(main)> products= T2Airtime::Product.all(2361)
+irb(main)> T2Airtime::Product.serialize(products.data)
 ```
 
-The serializer returns the following JSON representation of your account:
-
-```ruby
-{
-    "type": "accounts",
-    # Account login name
-    "id": ACCOUNT_ID,
-    "attributes": {
-        # Account type: "Master" (main account) or "Retailer" (subaccount)
-        "type": ACCOUNT_TYPE 
-        # Account login name
-        "name": ACCOUNT_NAME,
-        # Account currency (USD, GBP, EUR, etc…)
-        "currency": ACCOUNT_CURRENCY,
-        # For main account: returns the account’s remaining balance.
-        # For sub-account: returns the account’s remaining limit balance
-        # of the day if a daily limit is fixed. Else, returns the account
-        # remaining balance
-        "balance": ACCOUNT_BALANCE,
-        # For main account: returns the total remaining balance (sum 
-        # of all sub-accounts and current master).
-        # For sub-account: 
-        # 1. If balance is shared and daily limit is fixed: returns the fixed daily limit amount 
-        # 2. If balance is shared but daily limit is not fixed: returns "No Limit"
-        # 3. Else if balance is not shared: returns the remaining balance        
-        "wallet": ACCOUNT_WALLET,
-        # The time at which the information was fetched. 
-        # Can be used for caching purposes.
-        "fetched-at": TIMESTAMP
-    }
-}
-{{</ highlight >}}
-
-From a browser:
-[http://localhost:3000/account](/)
-
-![JSON response](/img/account_json.png) 
-
-<a name="country_list"></a>
-#### Country List
-
-The `country_list` method retrieves the countries offered in your TransferTo price list. 
-To format the response as JSON-API you can call `T2Airtime::Country.serialize(data)`.
-
-From a Rails console (or Ruby file):
+## Product Attributes
+- `id` (integer) - Product Airtime ID
+- `name` (string) - The product name
+- `localCurrency` (string) - The currency code of the product
+- `localCurrencySymbol` (string) - The currency symbol of the product
+- `currency` (string) - The curreny of your account
+- `currencySymbol` (string) - The currency symbol of your account
+- `localPrice` (float) - The face-value of the topup
+- `retailPrice` (float) - The retail price of the product
+- `wholesalePrice` (float) - The wholesale price of the product
+- `countryId` (float) - The country Airtime ID of the product
+- `countryName` (float) - The country name
+- `countryAlpha3` (float) - The country alpha3
+- `operatorId` (string) - The operator Airtime ID of the product
+- `operatorName` (string) - The operator name
+- `operatorLogo` (string) - The URL to the operator logo
+- `fetchedAt` (string) - The date and time at which the information was fetched
+
+## Product Relationships
+- `country.id` (integer) - Country Airtime ID
+- `operator.id` (integer) - Operator Airtime ID
+
+# Transaction
 
 ```ruby
-irb(main)> response= T2Airtime::API.api.country_list
-irb(main)> countries= T2Airtime::Country.serialize(response.data)
+irb(main)> transactions= T2Airtime::API.api.transaction_list
+irb(main)> T2Airtime::Transaction.serialize(transactions.data)
 ```
 
-The serializer returns the following JSON representation of a country:
-
 ```ruby
-{
-    "type": "countries",
-    # Unique Airtime ID for the country
-    "id": COUNTRY_ID,
-    "attributes": {
-        # The country name
-        "name": COUNTRY_NAME, 
-        # The ISO 3166-1 country alpha-3, https://it.wikipedia.org/wiki/ISO_3166-1_alpha-3
-        # Can be used for unique country identification.
-        "alpha3": COUNTRY_ALPHA3,
-        # The time at which the country was fetched. 
-        # Can be used for caching purposes.
-        "fetched-at": TIMESTAMP
-    },
-    "relationships": {
-        "operators": { "links": { "related": "/countries/COUNTRY_ID/operators" } }
-    }
-}
+irb(main)> transaction= T2Airtime::Transaction.get("584171224")
+irb(main)> T2Airtime::Transaction.serialize_one(transaction.data)
 ```
 
-The `relationships` section of the response provides a link you can use to navigate the country operators.
-
-From a browser:
-[http://localhost:3000/countries](/)
-
-![JSON response](/img/country_list_json.png)
-
-<a name="operator_list"></a>
-#### Operator List
-
-The `operator_list` method retrieves the operators available for a certain country. 
-To format the response as JSON-API you can call `T2Airtime::Operator.serialize(data)`.
-
-From a Rails console (or Ruby file):
+## Transaction Attributes
+- `id` (integer) - Transaction Airtime ID
+- `msisdn` (string) - The international phone number or name of 
+the user (sender) requesting to credit a phone number
+- `destinationMsisdn` (string) - Destination MSISDN (usually recipient phone number)
+- `transactionAuthenticationKey` (string) - Authentication key used during the transaction
+- `transactionErrorCode` (string) - Error code for the transaction
+- `transactionErrorTxt` (string) - Description of the error code for the transaction
+- `referenceOperator` (string) - Reference of the operator (returned only if available)
+- `actualProductSent` (string) - Returns the value requested to the operator 
+(equals to product_requested in case of successful transaction). It equals to 0 when Top-up 
+failed or in a simulation.
+- `sms` (string) - The custom message appended to the default notification SMS sent 
+to the recipient
+- `cid1` (string) - Value of the customized field cid1 sent in the Top-up request
+- `cid2` (string) - Value of the customized field cid2 sent in the Top-up request
+- `cid3` (string) - Value of the customized field cid3 sent in the Top-up request
+- `date` (string) - Date of the transaction (GMT) 
+- `currency` (string) - Currency of the account from which the transaction is requested
+- `localCurrency` (string) - Currency of the destination country
+- `pinBased` (string) - Type of product returned ("Yes", default "No" if not set)
+- `localInfoAmount` (string) - Final amount received by recipient. Indicative value only
+- `localInfoCurrency` (string) - Local currency in destination
+- `localInfoValue` (string) - Value of the transaction before tax and service fee in local currency
+- `errorCode` (string) - Error code for the transaction
+- `errorTxt` (string) - Description of the error code for the transaction
+- `productName` (string) - The product name
+- `productLocalCurrency` (string) - The currency code of the product
+- `productLocalCurrencySymbol` (string) - The currency symbol of the product
+- `productCurrency` (string) - The curreny of your account
+- `productCurrencySymbol` (string) - The currency symbol of your account
+- `productLocalPrice` (float) - The face-value of the topup
+- `productRetailPrice` (float) - The retail price of the product
+- `productWholesalePrice` (float) - The wholesale price of the product
+- `countryId` (float) - The country Airtime ID of the product
+- `countryName` (float) - The country name
+- `countryAlpha3` (float) - The country alpha3
+- `operatorId` (string) - The operator Airtime ID of the product
+- `operatorName` (string) - The operator name
+- `operatorLogo` (string) - The URL to the operator logo
+- `fetchedAt` (string) - The date and time at which the information was fetched
+
+## Transaction Relationships
+- `country.id` (integer) - Country Airtime ID
+- `operator.id` (integer) - Operator Airtime ID
+- `product.id` (integer) - Product Airtime ID
+
+# Topup
 
 ```ruby
-irb(main)> response= T2Airtime::API.api.operator_list countries.shuffle.first["id"]
-irb(main)> operators= T2Airtime::Operator.serialize(response.data)
+irb(main)> topup= T2Airtime::API.api.topup params
+irb(main)> T2Airtime::Topup.serialize(topup.data)
 ```
 
-The serializer returns the following JSON representation of an operator:
+## Topup Attributes
+- `balance` (string) - For main account: returns the account’s remaining
+balance. For sub-account: returns the account’s remaining
+limit balance of the day if a daily limit is fixed. Else,
+returns the account remaining balance.
+- `balanceDisplay` (string) - The `balance` value formatted in the currency of your account
+- `transactionId` (integer) - Airtime ID of the transaction.
+- `msisdn` (string) - The international phone number or name of 
+the user (sender) requesting to credit a phone number
+- `destinationMsisdn` (string) - Destination MSISDN (usually recipient phone number)
+- `transactionAuthenticationKey` (string) - Authentication key used during the transaction
+- `transactionErrorCode` (string) - Error code for the transaction
+- `transactionErrorTxt` (string) - Description of the error code for the transaction
+- `referenceOperator` (string) - Reference of the operator (returned only if available)
+- `actualProductSent` (string) - Returns the value requested to the operator 
+(equals to product_requested in case of successful transaction). It equals to 0 when Top-up 
+failed or in a simulation.
+- `sms` (string) - The custom message appended to the default notification SMS sent 
+to the recipient
+- `smsSent` (string) - Defines the status of the notification SMS sent to the
+recipient. Returns `yes` only if the SMS has been successfully sent.
+- `smsText` (string) - The custom message appended to the default
+notification SMS sent to the sender.
+- `cid1` (string) - Value of the customized field cid1 sent in the Top-up request
+- `cid2` (string) - Value of the customized field cid2 sent in the Top-up request
+- `cid3` (string) - Value of the customized field cid3 sent in the Top-up request
+- `currency` (string) - Currency of the account from which the transaction is requested
+- `localCurrency` (string) - Currency of the destination country
+- `productName` (string) - The product name
+- `productLocalCurrency` (string) - The currency code of the product
+- `productLocalCurrencySymbol` (string) - The currency symbol of the product
+- `productCurrency` (string) - The curreny of your account
+- `productCurrencySymbol` (string) - The currency symbol of your account
+- `productLocalPrice` (float) - The face-value of the topup
+- `productRetailPrice` (float) - The retail price of the product
+- `productWholesalePrice` (float) - The wholesale price of the product
+- `countryId` (float) - The country Airtime ID of the product
+- `countryName` (float) - The country name
+- `countryAlpha3` (float) - The country alpha3
+- `operatorId` (string) - The operator Airtime ID of the product
+- `operatorName` (string) - The operator name
+- `operatorLogo` (string) - The URL to the operator logo
+- `executedAt` (string) - The date and time at which the information was fetched
+
+# Msisdn
 
 ```ruby
-{
-    "type": "operators",
-    # Unique Airtime ID for the operator
-    "id": OPERATOR_ID,
-    "attributes": {
-        # The operator name
-        "name": OPERATOR_NAME, 
-        # The time at which the operator was fetched. 
-        # Can be used for caching purposes.        
-        "fetched-at": TIMESTAMP
-    },
-    "links": {
-        # The URL at which you can retrieve the operator's logo
-        logo: OPERATOR_LOGO_URL
-    },
-    "relationships": {
-        "country": { "data": { "type": "countries", "id": COUNTRY_ID } },
-        "products": { "links": { "related": "/countries/COUNTRY_ID/operators/OPERATOR_ID/products" } }              
-    },
-    "included": [
-        {
-            "type": "countries",
-            "id": COUNTRY_ID,
-            "attributes": {
-                "name": COUNTRY_NAME,             
-                "alpha3": COUNTRY_ALPHA3
-            }                
-        }
-    ] 
-}
-```            
-
-* The `relationships` section of the response provides a link you can use to navigate the operator products.
-* The `included` section of the response provides all the information regarding the operator's country.
-
-From a browser:
-[http://localhost:3000/countries/COUNTRY_ID/operators](/)
-
-![JSON response](/img/operator_list_json.png)
-
-<a name="product_list"></a>
-#### Product List
-
-The `product_list` method retrieves the products available for a certain operator. 
-To format the response as JSON-API you can call `T2Airtime::Product.serialize(data)`.
+irb(main)> msisdn= T2Airtime::Msisdn.info("+628123456710")
+irb(main)> T2Airtime::Msisdn.serialize(msisdn.data)
+```
 
-From a Rails console (or Ruby file):
+## Msisdn Attributes
+- `msisdn` (string) - The international mobile number
+- `country` (string) - The country of the number
+- `countryId` (string) - Country Airtime ID
+- `operator` (string) - The operator of the number
+- `operatorId` (string) - Operator Airtime ID
+- `fetchedAt` (string) - The date and time at which the information was fetched
 
-```ruby
-irb(main)> response= T2Airtime::API.api.product_list operators.shuffle.first["id"]
-irb(main)> products= T2Airtime::Product.serialize(response.data)
-```
+## Accounts [/accounts]
+Cached for 1 hour.
 
-The serializer returns the following JSON representation of a product:
+### Show Account [GET]
++ Response 200 (application/json)
 
-```ruby
-{
-    "type": "products",
-    # Airtime ID for the product. Attention! It is only unique within
-    # the scope of the operator
-    "id": PRODUCT_ID, 
-    "attributes": {
-        # The product name, or face value for display, es. 5EUR
-        "name": PRODUCT_NAME, 
-        # Currency of the destination country
-        "currency": PRODUCT_CURRENCY,
-        # The face value of the product (same as id)
-        "local-price": PRODUCT_LOCAL_PRICE,
-        # The retail price of the product
-        "retail-price": PRODUCT_RETAIL_PRICE,
-        # The wholesale price  (also known as your cost) of the product
-        "wholesale-price": PRODUCT_WHOLESALE_PRICE,  
-        # The time at which the operator was fetched. 
-        # Can be used for caching purposes.                     
-        "fetched-at": TIMESTAMP
-    },
-    "relationships": {
-        "country": { "data": { "type": "countries", "id": COUNTRY_ID } },
-        "operator": { "data": { "type": "operators", "id": OPERATOR_ID } }
-    },
-    "included": [
         {
-            "type": "countries",
-            "id": COUNTRY_ID,
+            "type": "accounts", 
+            "id": "my-t2-shop-account", 
             "attributes": {
-                "name": COUNTRY_NAME,
-                "alpha3": COUNTRY_ALPHA3
-            }                
-        },
-        {
-            "type": "operators",
-            "id": OPERATOR_ID,
-            "attributes": { "name": OPERATOR_NAME },
-            "links": { "logo": OPERATOR_LOGO_URL }              
+                "type": "Master", 
+                "name": "my-t2-shop-account-name", 
+                "currency": "USD", 
+                "balance": 16.2, 
+                "wallet": 16.2, 
+                "fetchedAt": "2017-09-17T13:48:34Z"
+            }
         }
-    ]
-    }
-}
-```            
-
-* The `relationships` section of the response provides a link you can use to navigate the product `included` relationships.
-* The `included` section of the response provides all the information regarding the product's country and operator.
-
-From a browser:
-[http://localhost:3000/countries/COUNTRY_ID/operators/OPERATOR_ID/products](/)
-
-![JSON response](/img/product_list_json.png)
-
-<a name="transaction_list"></a>
-#### Transaction List
-
-The `transaction_list` method retrieves all transaction within the specified time-range. 
-To format the response as JSON-API you can call `T2Airtime::Transaction.serialize(data)`.
-
-From a Rails console (or Ruby file):
-
-```ruby
-irb(main)> response= T2Airtime::API.api.transaction_list
-irb(main)> transactions= T2Airtime::Transaction.serialize(response.data)
-```
-
-From a browser:
-[http://localhost:3000/transactions](/)
-
-![JSON response](/img/transaction_list_json.png)
 
+## Countries [/countries]
+Cached for 1 hour.
 
-<a name="transaction_info"></a>
-#### Transaction Information
+### List all Countries [GET]
 
-The `transaction_info` method retrieves information regarding a certain transaction. 
-To format the response as JSON-API you can call `T2Airtime::Transaction.serialize_one(data)`.
++ Response 200 (application/json)
 
-From a Rails console (or Ruby file):
-
-```ruby
-irb(main)> response= T2Airtime::API.api.transaction_info
-irb(main)> transactions= T2Airtime::Transaction.serialize_one(response.data)
-{{</ highlight >}}
-
-The serializer returns the following JSON representation of a transaction:
+        [
+            {
+            "type": "countries" 
+            "id": 661
+            "attributes": {
+                "name": "Afghanistan" 
+                "alpha3": "AFG"
+                "callingCode": "93"
+                "fetchedAt": "2017-09-17T13:58:46Z"
+                }
+            }
+            ...
+        ]
+
+## Operators [/operators]
+
+### List all Operators [GET]
+Cached for 1 hour.
+
++ Response 200 (application/json)
+
+        [
+            {
+            "type": "operators"
+            "id": 2361
+            "attributes": {
+                "name": "Movicel Angola USD" 
+                "logo": "https://operator-logo.transferto.com/logo-2361-1.png"
+                "countryId": 666
+                "countryName": "Angola"
+                "countryAlpha3": "AGO" 
+                "fetchedAt": "2017-09-17T16:44:08Z"
+            },
+            "relationships": {
+                "country": {
+                    "data":{
+                        "type": "countries"
+                        "id": 666
+                        }
+                    }
+                }
+            },
+            ...
+        ]
+
+## Products [/products]
+Cached for 1 hour.
+
+### List all Products [GET]
+
++ Response 200 (application/json)
+
+        [
+            {
+            "type": "products"
+             "id": 1
+             "attributes": {
+                "name": "$1.00"
+                "localCurrency": "USD"
+                "localCurrencySymbol": "$"
+                "currency": "USD"
+                "currencySymbol": "$"
+                "localPrice": 1.0
+                "retailPrice": 1.1
+                "wholesalePrice": 1.03
+                "countryId": 666
+                "countryName": "Angola"
+                "countryAlpha3": "AGO"
+                "operatorId": 2361
+                "operatorName": "Movicel Angola USD"
+                "operatorLogo": "https://operator-logo.transferto.com/logo-2361-1.png"
+                "fetchedAt": "2017-09-17T16:48:20Z"
+             },
+             "relationships": {
+                 "country": {
+                    "data": {
+                         "type": "countries"
+                         "id": 666
+                         }
+                 },
+                 "operator": {
+                    "data": {
+                         "type": "operators"
+                         "id": 2361
+                         }
+                 }
+             },
+             ...
+            ]
+
+## Transactions [/transactions]
+
+### List all Transactions [GET]
+
++ Response 200 (application/json)
+
+        [
+            {
+            "type": "transactions"
+            "id": 584176053
+            "attributes": {
+                "msisdn": "+393800000000"
+                "destinationMsisdn": "393800000001"
+                "transactionAuthenticationKey": "1505553036"
+                "transactionErrorCode": 0
+                "transactionErrorTxt": "Transaction successful"
+                "referenceOperator": nil
+                "actualProductSent": "5"
+                "sms": nil
+                "smsText": "Test"
+                "cid1": "Cid1"
+                "cid2": "Cid2"
+                "cid3": "Cid3"
+                "date": "2017-09-16 09:10:39"
+                "currency": "USD"
+                "localCurrency": "EUR"
+                "pinBased": "no"
+                "localInfoAmount": "5.00"
+                "localInfoCurrency": "EUR"
+                "localInfoValue": "5.00"
+                "errorCode": 0
+                "errorTxt": "Transaction successful"
+                "countryId": 772
+                "countryName": "Italy"
+                "countryAlpha3": "ITA"
+                "operatorId": 734
+                "operatorName": "Wind Italy"
+                "operatorLogo": "https://operator-logo.transferto.com/logo-734-1.png"
+                "productName": "€5.00"
+                "productLocalCurrency": "EUR"
+                "productLocalCurrencySymbol": "€"
+                "productCurrency": "USD"
+                "productCurrencySymbol": "$"
+                "productLocalPrice": 5.0
+                "productRetailPrice": 7.5
+                "productWholesalePrice": 6.9
+                "fetchedAt": "2017-09-17T16:56:29Z"
+            },
+            "relationships": {
+                "country": {
+                    "data": {
+                        "type": "countries"
+                        "id": 772
+                    }
+                },
+                "operator": {
+                    "data": {
+                        "type": "operators"
+                        "id": 734
+                    }
+                },
+                "product": {
+                    "data": {
+                        "type": "products"
+                        "id": 5
+                        }
+                    }
+                }
+            },
+            ...
+        ]
+
+### Show Transactions [GET]
+
++ Response 200 (application/json)
+
+            {
+            "type": "transactions"
+            "id": 584176053
+            "attributes": {
+                "msisdn": "+393800000000"
+                "destinationMsisdn": "393800000001"
+                "transactionAuthenticationKey": "1505553036"
+                "transactionErrorCode": 0
+                "transactionErrorTxt": "Transaction successful"
+                "referenceOperator": nil
+                "actualProductSent": "5"
+                "sms": nil
+                "smsText": "Test"
+                "cid1": "Cid1"
+                "cid2": "Cid2"
+                "cid3": "Cid3"
+                "date": "2017-09-16 09:10:39"
+                "currency": "USD"
+                "localCurrency": "EUR"
+                "pinBased": "no"
+                "localInfoAmount": "5.00"
+                "localInfoCurrency": "EUR"
+                "localInfoValue": "5.00"
+                "errorCode": 0
+                "errorTxt": "Transaction successful"
+                "countryId": 772
+                "countryName": "Italy"
+                "countryAlpha3": "ITA"
+                "operatorId": 734
+                "operatorName": "Wind Italy"
+                "operatorLogo": "https://operator-logo.transferto.com/logo-734-1.png"
+                "productName": "€5.00"
+                "productLocalCurrency": "EUR"
+                "productLocalCurrencySymbol": "€"
+                "productCurrency": "USD"
+                "productCurrencySymbol": "$"
+                "productLocalPrice": 5.0
+                "productRetailPrice": 7.5
+                "productWholesalePrice": 6.9
+                "fetchedAt": "2017-09-17T16:56:29Z"
+            },
+            "relationships": {
+                "country": {
+                    "data": {
+                        "type": "countries"
+                        "id": 772
+                    }
+                },
+                "operator": {
+                    "data": {
+                        "type": "operators"
+                        "id": 734
+                    }
+                },
+                "product": {
+                    "data": {
+                        "type": "products"
+                        "id": 5
+                        }
+                    }
+                }
+            }
+            
+### Create (Reserve) Transaction [POST]
+
++ Response 200 (application/json)
 
-```ruby
-{
-    type: "transactions",
-    # Unique Airtime ID for the transaction
-    id: TRANSACTION_ID,
-    attributes: {
-        # The international phone number or name of 
-        # the user (sender) requesting to credit a phone 
-        # number
-        "msisdn": TRANSACTION_MSISDN,
-        # Destination MSISDN (usually recipient phone number)
-        "destination-msisdn": TRANSACTION_DESTINATION_MSISDN,
-        # Authentication key used during the transaction
-        "transaction-authentication-key": TRANSACTION_AUTHENTICATION_KEY,
-        # Error code for the transaction
-        "transaction-error-code": TRANSACTION_ERROR_CODE,
-        # Description of the error code for the transaction
-        "transaction-error-txt": TRANSACTION_ERROR_TEXT,
-        # Reference of the operator (returned only if available)
-        "reference-operator": TRANSACTION_REFERENCE_OPERATOR,
-        # Returns the value requested to the operator 
-        # (equals to product_requested in case of successful
-        # transaction). It equals to 0 when Top-up 
-        # failed.
-        "actual-product-sent": TRANSACTION_PRODUCT_SENT,
-        # Recipient SMS
-        # Returns the custom message appended to the 
-        # default notification SMS sent to the recipient
-        "sms": TRANSACTION_SMS,
-        # Value of the customized field cid1 sent in the Top-up request
-        "cid1": TRANSACTION_CID1,
-        # Value of the customized field cid2 sent in the Top-up request
-        "cid2": TRANSACTION_CID2,
-        # Value of the customized field cid3 sent in the Top-up request
-        "cid3": TRANSACTION_CID3,
-        # Date of the transaction (GMT)
-        "date": TRANSACTION_DATE,
-        # Currency of the account from which the transaction is requested
-        "originating-currency": TRANSACTION_ORIGINATING_CURRENCY,
-        # Currency of the destination country
-        "destination-currency": TRANSACTION_DESTINATION_CURRENCY,
-        # Type of product returned ("Yes", default "No" if not set)
-        "pin-based": TRANSACTION_PIN_BASED,
-        # Final amount received by recipient. Indicative value only
-        "local-info-amount": TRANSACTION_LOCAL_INFO_AMOUNT,
-        # Local currency in destination
-        "local-info-currency": TRANSACTION_LOCAL_INFO_CURRENCY,
-        # Value of the transaction before tax and service 
-        # fee in local currency.
-        "local-info-amount": TRANSACTION_LOCAL_INFO_AMOUNT,
-        # The time at which the transaction was fetched. 
-        # Can be used for caching purposes.         
-        "fetched-at": TIMESTAMP
-    },
-    relationships: {
-        country: { data: { type: "countries", id: COUNTRY_ID } },
-        operator: { data: { type: "operators", id: OPERATOR_ID } },
-        product: { data: { type: "products", id: PRODUCT_ID } }
-    },
-    included: [
-        {
-            type: "countries",
-            id: COUNTRY_ID,
-            attributes: {
-                "name": COUNTRY_NAME,
-                "alpha3": COUNTRY_ALPHA3
-            }                
-        },
         {
-            type: "operators",
-            id: OPERATOR_ID,
-            attributes: { "name": OPERATOR_NAME },
-            links: { logo: OPERATOR_LOGO_URL }               
-        },
-        {
-            type: "products",
-            id: PRODUCT_ID,
-            attributes: {
-                "name": PRODUCT_NAME,
-                "currency": PRODUCT_CURRENCY,
-                "wholesale-price": PRODUCT_WHOLESALE_PRICE,
-                "retail-price": PRODUCT_RETAIL_PRICE,
-                "local-price": PRODUCT_LOCAL_PRICE
-            }              
+            "type": "transactions"
+            "id": 584176053
         }
-    ]
-}
-```            
-
-* The `relationships` section of the response provides a link you can use to navigate the product `included` relationships.
-* The `included` section of the response provides all the information regarding the product's country and operator.
-
-From a browser:
-[http://localhost:3000/transactions/TRANSACTION_ID](/)
-
-![JSON response](/img/transaction_list_json.png)  
-
-## Testing
-
-Clone this repository and export your secrets:
-
-    $> export T2_SHOP_USER=
-    $> export T2_AIRTIME_KEY=
-
-Execute:
-
-    rake
+    
+## Number Information [/msisdn_info]
+Cached for 24 hours.
 
-To execute the test application:
+### Show Number Information [GET]
 
-    cd spec/dummy
++ Response 200 (application/json)
 
-Start the server: `puma -C config/puma.rb`
+        {
+            "type": "msisdn"
+            "msisdn": "628123456710"
+            "country": "Indonesia"
+            "countryId": "767"
+            "operator": "AAA-TESTING Indonesia USD"
+            "operatorId": "1562"
+            "fetchedAt": "2017-09-17T17:05:08Z"
+        }
 
-## Contributing
+## Topup [/topup]
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/matteolc/t2_airtime.
+### Create Topup [POST]
 
-## License
++ Response 200 (application/json)
 
-The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
+        {
+            "type": "msisdn"
+            "msisdn": "628123456710"
+            "country": "Indonesia"
+            "countryId": "767"
+            "operator": "AAA-TESTING Indonesia USD"
+            "operatorId": "1562"
+            "fetchedAt": "2017-09-17T17:05:08Z"
+        }