logo

1. Your API key and secret

Important

The following key and secret belong to a Mobino demo account and are used for demonstration purposes only. Money sent to this account immediately bounces back.

Credentials for merchant account: 'Generic Shop'
Your api key: 12a873b4619c60f6e3fc5c7316b6dc65
Your secret: 7gXEUWLY/1FqPS87WVfIDEoE4++QWDAlqsjgeYXEQs0=

2. Document overview

This document is targeted towards technical readers who will be integrating Mobino. The chapter Payments with Mobino introduces the basics and should be read carefully.

  • Web developers should read Using the Mobino widget for a very simple way to integrate Mobino payments in a web-shop.

  • If you want to request money in the simplest way possible, you should read the Payment links chapter which can start a payment process by just clicking a link.

  • If you own a shopware, prestashop or gambio based e-commerce website, you can use this plugin: integration plugins

  • Developers who are integrating Mobino in a till, POS,…​ (either dedicated hardware or a general purpose device such as a tablet), or web developers who need more fine grained control over the payment process should refer to The Mobino API

  • Developers who are integrating Mobino on older platforms which don’t allow for easy HTTP calls and JSON parsing should refer to Calling the Mobino API via a library

3. Payments with Mobino

Mobino payments are done in real-time and are secure. To illustrate this, let’s first have a look at how payment services usually work:

In order to transfer money from account A to account B, every payment service must establish the two transaction endpoints including the direction and the amount. Payment services differ fundamentally in how this information is gathered. The most often used approach is ID based:

  1. the merchant requests money

  2. the customer identifies himself at the till (e.g. with NFC or shows barcode or QR code, etc.)

  3. the payment service validates the identity

  4. the payment service checks the accounts (i.e. are enough funds available?)

  5. the payment service transfers the money

  6. the customer and merchant get a confirmation

This approach is fundamentally flawed for the following reasons:

  • the weak point is the identification process, which can be faked (sometimes easily, sometimes not so easily. Up to now, every single identification based process has been broken.)

  • the customer doesn’t get to confirm the payment, he needs to trust the display at the till.

  • this process requires special hardware at the till (fingerprint reader, NFC, etc.) and can’t be used in e-commerce

  • payments are never anonymous

3.1. Mobino’s solution

Mobino’s approach is different and solves these problems in a very simple way. We use a so called token to establish the two transaction endpoints. This token is generated randomly and doesn’t contain any information by itself. The two actors in the payment process use this token in the following way:

  1. the merchant calls the Mobino API with the requested amount

  2. the Mobino backend answers with a 5-digit token. (→ receiving transaction endpoint is now established)

  3. the merchant shows this token to the customer, the customer enters the token

  4. the customer’s smartphone uses this token to get the payment information from the Mobino backend

  5. the customer now sees the requested amount on his smartphone and confirms the payment. (→ sending transaction endpoint is now established)

  6. the customer and merchant get a confirmation of the payment

This has many advantages:

  • the token has no value and can’t be used in a damaging way. (If you steal someone’s token, you can pay their bill.) Because of this, we can use highly insecure transmission technologies such as bluetooth beacons to transmit tokens, without fear of any damage.

  • payments can be anonymous

  • the customer stays in control: he must confirm before any money gets sent

  • a 5-digit token is easy to display without any special hardware and can be used in any situation, including e-commerce

We have prepared a simple webshop for you to try out right away: widget_example.html

The following screenshots show how a beacon supported payment at a till works from the user’s perspective:

screenflow

Payments without a beacon work similarly, except that the user enters the token manually. From the merchant’s point of view, there is no difference at all.

screenflow no beacon

The following diagram shows the high level backend communication that happens during a payment.

HighLevelPaymentProcess

Our simple token-based payment process makes Mobino open to incorporate any current and future technology. For instance, you can pay with a smartwatch like in the following video.

It would simply not be possible to do this with an ID-based payment process using an ordinary smartwatch without any special in-built hardware.

In order to process a payment, the merchant’s payment system needs to implement an API which is described in the following chapters.

3.1.1. API Credentials

The API key is used to identify you to the Mobino payment backend. The API Secret is used to sign programmatic requests that you make to Mobino. While the key is public, the secret must be kept confidential in order to protect your account.

Important
Keep your secret confidential. Never email it nor share it outside your organization, even if an inquiry appears to come from Mobino. No one who legitimately represents Mobino will ever ask you for your secret.

4. Using the Mobino widget

For e-commerce, the simplest way to use Mobino is by using the provided Mobino widget.

Try it out: widget_example.html

If you are integrating Mobino in a cash register or need more control over the payment process in a e-commerce plugin, please refer to chapter The Mobino API.

Mobino provides you with a JavaScript widget that you can embed in your page where a sale is being made. Place the following code snippet in your page where you would like the Mobino button to appear.

Minimal sample invocation of Mobino Widget:
<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', {
      lang: 'en',
      popup: false, // immediately open the popup widget
      success_callback: successFunction,
      close_callback: closeFunction,
      api_key: 'YOUR_API_KEY',
      transaction: {
        amount: 9.99,
        currency: 'CHF',
        reference_number: 'YOUR_REF_NUMBER',
        nonce: nonce,
        signature: 'CALCULATED_SIGNATURE'
      },
      cancellation: {
        nonce: cancellation_nonce,
        signature: 'CALCULATED_SIGNATURE'
      }
    });
</script>
Full sample invocation of Mobino Widget:
<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: '12a873b4619c60f6e3fc5c7316b6dc65',
      transaction: {
        amount: 2.50,
        currency: 'CHF',
        reference_number: 'PO-79748',
        nonce: '8e4eaef37c382b75413cd5a6579964e0688e903f',
        signature: 'baa7a5295f21fc0b68bb10cfd4c7454c5e18f591'
      },
      cancellation: {
        nonce: 'fa5054ca5d092837601a9a1f6b7bea8fcc702e20',
        signature: 'baa7a5295f21fc0b68bb10cfd4c7454c5e18f591'
      }
    });
</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.

popup

(Optional) if true, immediately open the popup widget, don’t show the pay with mobino button.

success_callback

(Optional) A function that will be called once the payment has completed successfully. Ignored if callback is set.

close_callback

(Optional) A function that will be called if the user pushes the close button

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 . (dot), not a comma. No other formatting is allowed (thousand separators etc.)

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 with this reference number in the callback 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 chapter Signature.

cancellation

The cancellation attributes needed to cancel the token when the user closes the widget window

cancellation.nonce

A random unique string that is sent as part of the token cancellation request (you should always generate UNIQUE RANDOM nonce, only Alphanumeric characters, "-", and "_" are allowed).

cancellation.signature

A signature of the cancellation_nonce and secret parameters. See chapter Signature.

4.1. Signature

In order to protect the integrity of your calls to Mobino, you will need to provide a computed signature. This signature is generated using a one way hash function over the nonce you provide and the API Secret we provide to you.

Important

Please make sure that every nonce you use to sign the request is UNIQUE and RANDOM! (The Mobino backend enforces this.) In case of e-commerce: The signing process should ALWAYS be done on the server, never send the secret out to the customer’s browser.

You concatenate your nonce and your API Secret and then calculate the SHA1 hash.

For example, your original parameters:
 Mobino.createButton('YOUR_DIV_ID', {
  lang: 'fr',
  country: 'CH',
  callback: 'http://example.com/paymentCompleted.html',
  api_key: '12a873b4619c60f6e3fc5c7316b6dc65',
  transaction: {
    amount: 2.50,
    currency: 'CHF',
    reference_number: 'PO-70824',
    nonce: '8e4eaef37c382b75413cd5a6579964e0688e903f'
  }
});

and your API secret is: 7gXEUWLY/1FqPS87WVfIDEoE4++QWDAlqsjgeYXEQs0=

So your signature will be hash_method([RANDOM_NONCE][YOUR_API_SECRET]):
Ruby:
Digest::SHA1.hexdigest('8e4eaef37c382b75413cd5a6579964e0688e903f7gXEUWLY/1FqPS87WVfIDEoE4++QWDAlqsjgeYXEQs0=')
=> "baa7a5295f21fc0b68bb10cfd4c7454c5e18f591"

or

PHP:
sha1("8e4eaef37c382b75413cd5a6579964e0688e903f7gXEUWLY/1FqPS87WVfIDEoE4++QWDAlqsjgeYXEQs0=")
=> "baa7a5295f21fc0b68bb10cfd4c7454c5e18f591"
This signature is then appended to the parameter transaction:
 Mobino.createButton('YOUR_DIV_ID', {
  lang: 'fr',
  country: 'CH',
  callback: 'http://example.com/paymentCompleted.html',
  api_key: '12a873b4619c60f6e3fc5c7316b6dc65',
  transaction: {
    amount: 2.50,
    currency: 'CHF',
    reference_number: 'PO-70824',
    nonce: '8e4eaef37c382b75413cd5a6579964e0688e903f',
    signature: 'baa7a5295f21fc0b68bb10cfd4c7454c5e18f591'
  }
});

4.2. Callback URL

We will invoke the callback URL you provided 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.

Example
sha1([YOUR_REFERENCE_NUMBER][YOUR_API_SECRET])

Payment links are a way to request money using the Mobino widget without having to integrate the widget code into your website. While the widget requires you to create a backend component that signs messages to the mobino backend, the payment link does this job for you. To request money, you just have to show your customer a link like so:

https://app.mobino.com/merchants/pay?api_key=<api_key>&amount=<amount>&currency=<currency>&reference=<reference>
Example
https://app.mobino.com/merchants/pay?api_key=12a873b4619c60f6e3fc5c7316b6dc65&amount=0.10&currency=CHF&reference=copy-machine-by-the-water-dispenser

Once the customer clicks on the link, he’ll see a new page with a token. Once the token is paid, he will be shown a success page.

Try it out:

You can send these links in an email or put them on a web page to collect money. Use the reference to easily track payments for a specific cause.

Important

A merchant can only have 5 open tokens through a payment link at the same time.

Parameter Description

api_key

your API key

amount

The amount of the transaction in base units (e.g. "1.00")

currency (optional)

The currency used for the payment (if no currency is present, your default account currency will be used)

reference (optional)

The reference number. If no reference number is given, Mobino will create one for you. Please note that since a reference number can only be used one time, Mobino will add a sequence number to the reference number to guarantee uniqueness.

return_url (optional)

After the payment has completed, the customer will be shown a button that forwards him to the URL. This button will not appear if the URL is omitted.

abort_url (optional)

if the payment has been cancelled or if there was an error, the customer will be forwarded to this URL.

6. Magic beacons

Magic beacons enable payments in a wide range of unattended services such as: vending machines, fuel stations, parking meters, etc.

Mobino can configure a merchant’s beacon to automatically create reserve money tokens. A client will see a payment request on his phone and reserve money for a future payment.

Magic beacons

Payment process:

  1. The beacon sends out the payment_key periodically

  2. A customer’s mobino app fetches the payment information of this payment_key. Since the payment_key has the ‘magic’ flag enabled, it returns a ‘reserve money’ intent.

  3. The customer pays this payment intent and the requested amount is held back for a certain amount of time.

  4. As soon as the vending automaton is being operated, the machine fetches the active reserve intent if its beacon (identified via the payment_key).

  5. If it successfully can verify an active ‘reserve money intent’, it will start serving. (e.g. pumping fuel, or let the customer choose a product)

  6. Once the total amount of the transaction is known, the vending automaton finalizes the payment. Note that only up to the reserved amount can be claimed. The remainder is released back to the customer’s funds.

The Mobino API has two special API calls to support this use case:

7. The Mobino API

Mobino uses a simple REST API. All requests and responses are transfered in JSON format over HTTPS.

If you have any question regarding the integration, please don’t hesitate to contact us at: api@mobino.com

All calls in this document should go to: https://app.mobino.com/merchants + <RESOUCE_PATH>

Working with the Mobino API is a two-step process. In the first step you generate a token for your payment. In the second step, you poll the service for the state of your transaction using the token from step 1.

7.1. Payment process

The following diagrams depict the flow and sequence of a payment.

Sequence diagram

Figure 1: Sequence of a normal payment.

Flow diagram of a payment including error conditions

Figure 2 shows the different states of a payment. It is important to consider error conditions very carefully: If your payment processor encounters an error while polling for a payment status, it should stay in the loop until the process is interrupted, e.g. by the operator at a till, or by a well defined process (which informs the user accordingly). The system must take into consideration that the token may have been paid by the client at any time during the error condition, therefore, whenever the loop is left because of an exception, the token and the transaction must be cancelled.

7.2. Step 1: Retrieve a token

The first step of a new payment is to get a token from the Mobino backend. You just provide the amount and the Mobino backend returns a token.

Usually a token is used for payment only. However a token can also refill a client’s Mobino account. A typical scenario would be a client who wants to pay with Mobino but doesn’t have enough balance. He can give the merchant cash and pay and refill his Mobino account in one go.

Note

It is important to understand that tokens which contain a refill part must be handled carefully, that is: If such a token gets stolen, it can be easily used by a third party to refill his account. The merchant must cancel such a transaction if something goes wrong.

The merchant creates a token by supplying the amount and currency. Additionally he can supply a refill_amount and refill_currency. Paying such a token will result in two transactions:

  1. the refill transaction: The refill transaction will transfer the refill amount from the merchant’s Mobino account to the customer’s Mobino account.

  2. the payment transaction: The payment transaction will transfer the payment amount from the customer’s Mobino account to the merchant’s Mobino account.

The client will see the refill amount and payment amount on the confirmation screen if both amount and refill_amount are provided:

refill

Call GET /api/v1/tokens.json with the following parameters:

Parameter Description

amount

the amount of the transaction (formatted with two decimal digits)

currency (optional)

Optional Parameter: The currency used for the payment (if no currency is present, your default account currency will be used)

refill_amount (optional)

amount of cash paid by the client as a refill amount (formatted with two decimal digits)

refill_currency (optional)

refill currency. The currency used for the payment (if no currency is present, your default account currency will be used)

ibeacon_id (optional)

the beacon-ID associated with the location. The beacon-ID is managed per-token and contains the beacon-ID which is located closest to the place at which the payment request is issued. If a BLE enabled smartphone with >= iOS7 or Android >= 4.3 is sufficiently close, then no token needs to be entered by the paying client.

api_key

your API key

reference_number

a unique reference number to identify your payment (Only Alphanumeric characters, "-", and "_" are allowed)

nonce

a random unique string that you send with your request (make sure you generate a RANDOM nonce, only Alphanumeric characters, "-", and "_" are allowed)

signature

a signature calculated like: sha1([YOUR_NONCE][YOUR_API_SECRET])

The response will be a JSON object with the following field:

Field Description

token

the token

Example
GET /api/v1/tokens.json?amount=2.50&api_key=YOUR_KEY&reference_number=79748&nonce=184819-149&signature=CALCULATED_SIGNATURE

{"token":12345}

7.3. Step 1b: Retrieve a reserve money token

The merchant can ask a customer to reserve money for an upcoming transaction before we know how much money will actually be paid. The merchant can charge up to the amount of the reserved money once he finalizes the payment.

By way of example, the merchant can ask the customer to reserve CHF 100.- with a token created in this way, the customer pays this token. Once the transaction is completed, i.e. the merchant knows the exact price of the transaction, the merchant finalizes it by telling the Mobino backend how money was actually spent. This amount is then transferred to the merchant’s account while the remainder (if any) will again be accessible to the customer.

Note that a customer can only reseve money for one merchant at a time. The money will be reserved for a predetermined time.

refill

refill

refill

Pay a reserve money token

Displays the amount reserved

After finalize, no money is reserved

From a user’s perspective paying such a token is exactly the same as paying an ordinary token. However, in this case no refill is possible.

The merchant’s system will finalize the transaction as described in the chapter Step 3: Finalizing the payment (reserve money use case)

Note

If the merchant does not finalize the payment within the predetermined time, the reserved money will again be made accessible to the user. To prevent abuse, the merchant must make sure that either the transaction has been completed before this time limit, or the customer can no longer access the service when the reserved money has been released.

The following diagrams depict the flow and sequence of a complete payment in case of a reserved money token.