Enabling mobile payments for 5 billion people
We believe that each citizen of the world should be able to effortlessly send and receive money with their phone, no matter where they live, which telco they use, whether they have a bank account, a credit card or just cash in their pocket, no matter how much they earn and what they buy.
Please contact us directly and we will create a merchant account for you, then you can start
to integrate Mobino payment system into your own business by looking at our API documentation.
If you have any question regarding the integration, please don’t hesitate to contact us by this
email address: [email protected]
Mobino uses a simple REST based JSON API. All requests and responses are transfered in JSON format over HTTP.
Before you can start to use the Mobino API you will need to setup API keys and secrets. These are generated automatically for you when your merchant account is created. You can change them anytime by going to your profile page and clicking "Create API credentials" in the Edit form of your profile.
|
Caution
|
As soon as you change the credentials, any applications you have that use the old pair of credentials will stop working. |
In addition, you will need to provide a callback URL that we call upon a successful transaction. Details to be found in the section Callback URL.
The simplest way to use Mobino is by using the provided Mobino Widget.
Check out our online demo: https://app.mobino.com/merchants/widget_example.html
Mobino provides you with a JavaScript widget that you can embed on the page where a sale is being made. Here’s the code you need to put where you want the button to appear:
<div id="mobino_payment"></div>
<script src="http://ajax.googleapis.com/ajax/libs/jquery/1.9.1/jquery.min.js"></script>
<script src="https://app.mobino.com/merchants/api/v1/mobino.js"></script>
<script>
Mobino.createButton('YOUR_DIV_ID', {
api_key: 'YOUR_API_KEY',
transaction: {
amount: 9.99,
currency: 'CHF',
reference_number: 'YOUR_REF_NUMBER', // MUST be UNIQUE to identify your payment
nonce: nonce, // MUST be UNIQUE in order to differentiate every API call
signature: 'CALCULATED_SIGNATURE'
}
});
</script>
<div id="mobino_payment"></div>
<script src="http://ajax.googleapis.com/ajax/libs/jquery/1.9.1/jquery.min.js"></script>
<script src="https://app.mobino.com/merchants/api/v1/mobino.js"></script>
<script>
Mobino.createButton('mobino_payment', {
lang: 'de',
country: 'CH',
callback: 'http://example.com/paymentCompleted.html',
api_key: 'YOUR_API_KEY',
transaction: {
amount: 2.50,
currency: 'CHF',
reference_number: 'PO-79748',
nonce: '449127420-68853',
signature: 'CALCULATED_SIGNATURE'
}
});
</script>
The parameters are as follows:
lang
|
Optional Parameter: Select the language of the widget and popup. en selects English, the default. fr selects French. de selects German. |
country
|
Optional Parameter: Overrides the country-detection, based on GeoIP. The Country code has to be in capitals. Currently supported: UK selects Great Britain, the default. CH selects Switzerland. FR selects France. DE selects Germany. |
callback
|
Optional Parameter: If passed a string the user will be redirected to this page when he successfully completed his transaction. Note: This is only there to improve the user experience and you need to use the server callback to verify the payment. |
transaction
|
The transaction that should be started when the user clicks on the button. |
transaction.amount
|
The amount to charge in Euro’s and Cent’s.
Separator of Euros and Cents is a |
transaction.currency
|
Optional Parameter: The currency used for the payment (if no currency is present, your default account currency will be used) |
transaction.api_key
|
The API key found discussed above. |
transaction.reference_number
|
A UNIQUE reference number that you can use to track the payment. We will provide you this reference number in the callback we do on a successful transaction. (Only Alphanumeric characters, "-", and "_" are allowed) |
transaction.nonce
|
A random unique string that you send with your request (you should always generate UNIQUE RANDOM nonce, only Alphanumeric characters, "-", and "_" are allowed). |
transaction.signature
|
A signature of the parameters. See section on Signature. |
In order to protect the integrity of your call to Mobino, you will need to
provide a computed signature. This signature is generated using a one way Hash
function using the UNIQUE nonce you provide and the API Secret we provide to
you.
Please make sure every nonce you use to sign the request is UNIQUE and RANDOM! And the signing process should ALWAYS be done at the server side. (Only Alphanumeric characters, "-", and "_" are allowed)
Basically, you only have to concatenate your nonce and your API Secret,
and then calculate the SHA1 hash.
Mobino.createButton('YOUR_DIV_ID', {
lang: 'fr',
country: 'CH',
callback: 'http://example.com/paymentCompleted.html',
api_key: 'YOUR_API_KEY',
transaction: {
amount: 2.50,
currency: 'CHF',
reference_number: 'PO-70824',
nonce: '449127420-47481'
}
});
and your API secret is: 46ixHhzoP/GS9tYY7S9SyaOm\f2h=b1r
Ruby:
Digest::SHA1.hexdigest('449127420-4748146ixHhzoP/GS9tYY7S9SyaOm\f2h=b1r')
=> "9d6fee302a883a5af307d0002e2f4688ec7ed58d"
or
PHP:
sha1("449127420-4748146ixHhzoP/GS9tYY7S9SyaOm\f2h=b1r")
=> "9d6fee302a883a5af307d0002e2f4688ec7ed58d"
transaction: Mobino.createButton('YOUR_DIV_ID', {
lang: 'fr',
country: 'CH',
callback: 'http://example.com/paymentCompleted.html',
api_key: 'YOUR_API_KEY',
transaction: {
amount: 2.50,
currency: 'CHF',
reference_number: 'PO-70824',
nonce: '449127420-47481',
signature: '9d6fee302a883a5af307d0002e2f4688ec7ed58d'
}
});
We will call the callback URL you provided to us at the end of a transaction with the following information:
status-
The status of the transaction. One of authorized or unauthorized. If you receive authorized, the transaction was completed successfully, and you will be credited the amount. If the transaction is unauthorized, then the customer didn’t approve the transaction.
amount-
The amount of the transaction (formatted with two decimal digits)
currency-
The currency code of the transaction
reference_number-
The reference number you passed in when you generated the request for a transaction
api_key-
your API key
token-
The token used to pay this transaction
signature-
The signature for this callback
This callback URL is different from the one mentioned in the widget, as the former
one is a simple callback from the browser which aims to improve the user experience.
This callback, however, is a server-side HTTP POST callback that will be triggered in our
payment system.
We support callback URLs with HTTP and HTTPS protocol, but HTTPS is strongly recommended.
At the moment, the parameters are returned url-encoded. In the future, you will be able to select either JSON or URL encoding.
Note: The procedure to calculate a signature in this callback is very similar, we will
hash the concatenation of the reference_number you provided and your API Secret.
sha1([YOUR_REFERENCE_NUMBER][YOUR_API_SECRET])
It is of course possible to work without the mobino widget. You will need to call our API directly. This is a two-step process. First, you need to generate a token for your transaction. Second, you need to poll the service for the state of the transaction.
Call the URL https://app.mobino.com/merchants/api/v1/tokens.json with the following parameters:
| Parameter | Description |
|---|---|
|
the amount of the transaction (formatted with two decimal digits) |
|
Optional Parameter: The currency used for the payment (if no currency is present, your default account currency will be used) |
|
your API key |
|
a unique reference number to identify your payment (Only Alphanumeric characters, "-", and "_" are allowed) |
|
a random unique string that you send with your request (make sure you generate a RANDOM nonce, only Alphanumeric characters, "-", and "_" are allowed) |
|
a signature calculated like: sha1([YOUR_NONCE][YOUR_API_SECRET]) |
The response will be a JSON object with the following field:
| Field | Description |
|---|---|
|
the token |
GET /api/v1/tokens.json?amount=2.50&api_key=YOUR_KEY&reference_number=79748&nonce=184819-149&signature=CALCULATED_SIGNATURE
{"token":12345}
To retrieve the status of the transaction you can call the URL /api/v1/transactions.json
with the following parameters:
| Parameter | Description |
|---|---|
|
your API key |
|
the token you retrieved in step 1 |
|
the language that you want the text message to be in (can be either |
The response will be a JSON object with the following fields:
| Field | Description |
|---|---|
|
a human readable message describing the next step |
|
the transaction status, for example |
|
the amount you set for this transaction_type |
|
the currency code |
If the status is "in_progress" you have to call the URL again until the transaction succeeded of failed.
A good time interval between two polls is 5 seconds.
| Status | Message |
|---|---|
|
Initializing… |
|
Your transaction is being processed. Please enter your PIN on the telephone. |
|
Transaction has expired. Please restart the payment process. |
|
This transaction could not be completed. |
|
"Payment received. Your reference number for this transaction is: %{reference_number}" |
GET /api/v1/transactions.json?api_key=YOUR_API_KEY&token=TOKEN
{
"message": "Your transaction is being processed. Please enter your PIN on the telephone.",
"status": "in_progress"
}
You can consult your account status and keep track of your latest transactions including both in and out payments.
These API calls require also a nonce and a signature calculated by yourself.
To consult your account information, you can call the URL GET /api/v1/account
with the following parameters:
| Parameter | Description |
|---|---|
|
your API key |
|
a random unique string that you send with your request (make sure you generate a RANDOM nonce) |
|
a signature calculated like: sha1([YOUR_NONCE][YOUR_API_SECRET]) |
The response will be a JSON array containing the number of transaction objects.
To get all the recent transactions, you can call the URL GET /api/v1/transaction_list
with the following parameters:
| Parameter | Description |
|---|---|
|
your API key |
|
a random unique string that you send with your request (make sure you generate a RANDOM nonce) |
|
a signature calculated like: sha1([YOUR_NONCE][YOUR_API_SECRET]) |
|
the number of records you want to retrieve (if you don’t precise, the default limit is 20) |
The response will be a JSON array containing the number of transaction objects.
Of course, you can check out our online demo as well: https://app.mobino.com/merchants/transaction_list_example.html
When a payment dispute occurs, you could choose to refund the transaction by calling this
URL POST /api/v1/transaction/TRX_UUID/refund (TRX_UUID is the unique id of the transaction)
with the following parameters:
| Parameter | Description |
|---|---|
|
your API key |
|
a signature calculated like: sha1([THE_TRX_UUID][YOUR_API_SECRET]) |
The response will be a JSON array containing the new transaction created.
In order to show the buyer the local telephone number for Mobino, you can ask Mobino for the preferred telephone number based on the buyers IP and an optional language:
Call the URL https://app.mobino.com/api/v1/preferred_phone_numbers.json with
the following parameters:
| Parameter | Description |
|---|---|
|
the ip address of the buyer |
|
the default language preferred |
This call returns a JSON object with the following fields
| Name | Description |
|---|---|
|
the country that the buyer is in |
|
Array with [country, language, phone_number] |
|
Array with all other possible phone numbers (in same format as preferred_number |
GET /api/v1/preferred_phone_numbers.json?ip=12.12.12.12&lang=de
{ "country": "CH",
"preferred_number": { "country": "CH",
"language": "de",
"phone_number": "+41 43 508 05 18"},
"other_numbers": [{ "country": "CH",
"language": "fr",
"phone_number": "+41 22 123 12 12"},
{ "country": "DE",
"language": "de",
"phone_number": "+49 30 123 123 12"}]
}