apiary.apib
FORMAT: 1A
HOST: http://polls.apiblueprint.org/
# t2-airtime
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
+ 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
irb(main)> account= T2Airtime::Account.get
irb(main)> T2Airtime::Account.serialize(account.data)
```
## 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
irb(main)> countries= T2Airtime::Country.all
irb(main)> T2Airtime::Country.serialize(countries.data)
```
## 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)> operators= T2Airtime::Operator.all(666)
irb(main)> T2Airtime::Operator.serialize(operators.data)
```
## 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
## Operator Relationships
- `country.id` (integer) - Country Airtime ID
# Product
```ruby
irb(main)> products= T2Airtime::Product.all(2361)
irb(main)> T2Airtime::Product.serialize(products.data)
```
## 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)> transactions= T2Airtime::API.api.transaction_list
irb(main)> T2Airtime::Transaction.serialize(transactions.data)
```
```ruby
irb(main)> transaction= T2Airtime::Transaction.get("584171224")
irb(main)> T2Airtime::Transaction.serialize_one(transaction.data)
```
## 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)> topup= T2Airtime::API.api.topup params
irb(main)> T2Airtime::Topup.serialize(topup.data)
```
## 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
irb(main)> msisdn= T2Airtime::Msisdn.info("+628123456710")
irb(main)> T2Airtime::Msisdn.serialize(msisdn.data)
```
## 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
## Accounts [/accounts]
Cached for 1 hour.
### Show Account [GET]
+ Response 200 (application/json)
{
"type": "accounts",
"id": "my-t2-shop-account",
"attributes": {
"type": "Master",
"name": "my-t2-shop-account-name",
"currency": "USD",
"balance": 16.2,
"wallet": 16.2,
"fetchedAt": "2017-09-17T13:48:34Z"
}
}
## Countries [/countries]
Cached for 1 hour.
### List all Countries [GET]
+ Response 200 (application/json)
[
{
"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)
{
"type": "transactions"
"id": 584176053
}
## Number Information [/msisdn_info]
Cached for 24 hours.
### Show Number Information [GET]
+ Response 200 (application/json)
{
"type": "msisdn"
"msisdn": "628123456710"
"country": "Indonesia"
"countryId": "767"
"operator": "AAA-TESTING Indonesia USD"
"operatorId": "1562"
"fetchedAt": "2017-09-17T17:05:08Z"
}
## Topup [/topup]
### Create Topup [POST]
+ Response 200 (application/json)
{
"type": "msisdn"
"msisdn": "628123456710"
"country": "Indonesia"
"countryId": "767"
"operator": "AAA-TESTING Indonesia USD"
"operatorId": "1562"
"fetchedAt": "2017-09-17T17:05:08Z"
}