MBLOX BILLING API SPECIFICATION User guide

Transcription

MBLOX BILLING API SPECIFICATION
User guide
Use the Mblox Billing API to access account
information programmatically via a secure HTTP
connection. This guide outlines how to request
general account information.
w: www.mblox.com e: [email protected]
© 2015 MBLOX | WWW.MBLOX.COM
CONTENTS
1.0 OVERVIEW...............................................3
2.0 GENERAL INFORMATION.................3
3.0 KEYWORDS............................................4
3.1 COVERAGE................................................4
3.2 SERVICE.....................................................5
3.3 BALANCE...................................................6
3.4 SUBS............................................................6
3.5 TRANSFER.................................................7
2
1.0 OVERVIEW
This document describes how certain information about your Mblox account can be accessed via a secured
HTTP interface.
The format and level of access you have to these features depends upon your account settings.
2.0 GENERAL INFORMATION
You can access the billing interface at https://billing.cardboardfish.com/Billing. You must always
include the following parameters:
PARAMETER
DESCRIPTION
Username
Your account username
Password
Your account password
Request
A keyword describing your request. See section 3
If an error occurs during any request, you will receive a text response:
ERR [error message]
Where [error message] will indicate the problem.
COMMON ERRORS:
ERR Bad Request - Your request was not
formatted correctly.
ERR Bad username or password - Your
username or password was not recognised by
the system.
ERR Forbidden - Your request was valid, and
your username and password were correct,
but you do not have permission to access the
requested information.
3
3.0 KEYWORDS
The following keywords access / affect the corresponding information. Additional parameters may be
required which are described later.
KEYWORD
ADDITIONAL PARAMETERS
INFORMATION
Coverage*
Yes
The SMS coverage of a service on your account.
Services*
No
The list of services on your account.
Balance
No
The live SMS balance on your account.
Subs*
No
The list of sub-accounts and balance on your account.
Transfer
Yes
Allows the transfer of funds between your account and your sub-accounts.
* Creates a CSV
The remaining sections describe these facilities in more detail.
3.1 COVERAGE
This keyword requests a CSV detailing the coverage on any SMS service on your account.
EXTRA PARAMETERS:
PARAMETER
DESCRIPTION
ServiceUser
The username of an SMS-based service on your account.
Please note that this only applies to SMS-based services; coverage has no meaning for non-SMS services.
RESPONSE:
Either a CSV of the coverage, or an error string.
EXAMPLES:
A normal, successful request
4
REQUEST:
https://billing.cardboardfish.com/Billing?Username=testuser&
Password=x0f8g6ew&Request=Coverage&ServiceUser=testuser1
RESPONSE (CSV):
testuser1_coverage_1234567890.csv
Columns: MCCMNC, Country, Network, Currency, Price
ERRORS:
ERR Service not found
The username specified does not belong to a service on your account.
ERR Not an SMS Service
The username specified is a non-SMS service on your account, e.g. a Virtual Number, which is
attached to another service, or HLR Lookup, which does not send or receive SMS.
3.2 SERVICES
No extra parameters are required for this request. Returns a CSV listing the services on your account along
with their usernames.
EXAMPLES:
REQUEST:
Password=x0f8g6ew&Request=Services
RESPONSE (CSV):
testuser_services_1234567890.csv
Columns: Username, Service Name
5
3.3 BALANCE
No extra parameters are required for this request. Returns a string in the following format:
OK username balance currency
EXAMPLES:
REQUEST:
Password=x0f8g6ew&Request=Balance
RESPONSE:
OK testuser 12.345 EUR
ERRORS:
ERR Forbidden
You do not have permission to view the balance on your account.
3.4 SUBS
This request returns a CSV listing the sub-accounts under your account, and their balances. If permissions
do not allow this, an error string will be returned.
EXAMPLES:
REQUEST:
Password=x0f8g6ew&Request=Subs
RESPONSE (CSV):
testuser_subs_1234567890.csv
Columns: Username, Balance, Currency, Credits, Rate
6
3.5 TRANSFER
This request allows you to transfer credit from your account into a sub-account and vice versa. The
response will show your balance and the balance of the sub-account in currency and credits, like this:
OK username balance currency subuser subbalance subcurrency subcredits
WHERE:
username = your account username
balance = your account balance in currency
currency = your account currency
subuser = sub account username
subbalance = sub account balance in currency
subcurrency = sub account currency
subcredits = sub account balance in credits
EXAMPLE:
OK test 17.345 EUR subtest 5.00 EUR 250.0
EXTRA PARAMETERS:
PARAMETER
DESCRIPTION
ONE OF:
To
From
The username of the sub-account to transfer credit to / from
ONE OF:
Accounts
Credits
The amount of credit or number of credits to transfer
EXAMPLES:
Transfer 5.00 from sub-account “subtest” into my account “test”
REQUEST:
https://billing.cardboardfish.com/Billing?Username=test&
Password=rw8y78qw&Request=Transfer&From=subtest&Amount=5.00
RESPONSE:
Transfer 50 credits from my account “test” into sub-account “subtest”
7
REQUEST:
https://billing.cardboardfish.com/Billing?Username=test&
Password=rw8y78qw&Request=Transfer&To=subtest&Credits=50
RESPONSE:
ERRORS:
ERR Cannot use To and From at the same time
Only one of these parameters can be used at once; use To to indicate that you wish to transfer credit
into the account specified by the To parameter, OR From to indicate that you wish to transfer credit out
of the account specified by the From parameter. To transfer credit between sub-accounts, first transfer
the credit from the source sub-account into your main account, then transfer the credit to the destination
sub-account.
ERR Amount not specified
Neither the Credits nor the Amount parameter was given. You must specify the amount of credit to
transfer using one of these parameters.
ERR Amount too small
Credit transfers are limited to a minimum of 0.001, so any smaller amount, including zero, is not valid.
Since all transfers are done using currency, this also applies to very small credit amounts if the rate
means it is not greater than 0.001.
ERR No rate set for credits, please use currency or set a rate
The credits parameter was used, but the sub-account has no rate set for credits. Either log into your
online account and set a rate, or use the Amount parameter to specify a currency amount.
ERR Amount must be a decimal
The Amount parameter did not contain a decimal value, 12.345 for example.
ERR Cannot reduce sub-account balance below zero
The amount of credit requested in the transfer is more than is available in the sub-account. You cannot
move more credit than is available.
ERR Sub-account not found
The account specified by the To or From parameter is not a sub-account of your account.
8
ERR Either To or From must be specified
You must specify either an account to move credit into (To) or an account to move credit out of (From).
ERR An error occurred while dealing with your request
During the steps taken by our system to transfer credit between accounts, an error prevented the full set
of steps from completing. The entire process was cancelled.
9

MBLOX BILLING API SPECIFICATION User guide

Transcription

Similar documents

Registration for My Account website

4. Select the “My Lexile Range” drop down. Now, click search. 2

Glencoe Math

SJECCD Online Education

Veterinary Medical Center

Broward Enterprise Education

Logging in to the System Please go to the following URL to begin

my.hrw.com

Business Application

How to Get Tennis Channel Everywhere for Desktop

PDF - American Express REDcard

Extension Package Programmer's Manual