MiMo API / OAuth v2 + REST

Making REST calls to the MiMo API server

In order to interact with a user's MiMo account (e.g. facilitating payments), you will first need to have the user authenticate your MiMo client. This method of authentication works very similarly to Facebook and Twitter's authentication flow. The user is first presented with a permission dialog for your application, at which point the user can either approve the request permissions or reject them. Once the user has granted approval, a user authentication code is sent to your application server which then permits your application to transfer money. Follow this 3-step guide below to get started with the MiMo API today.

MiMo conforms to OAuth version 2. You may read more about this standard here.

Step 1: Obtaining the User Authentication Code (Expand/Collapse)

Request MiMo API access

Before you can begin using the MiMo API you must request access for your client application. MiMo API access is only granted to fully-verified merchant users. These are users with a confirmed email address, a confirmed mobile number and who are KYC verified.

Your MiMo API access will have an associated "client_id" and "client_secret" which will be needed during the next steps.

Request user authentication code

When initiating a new payment from your client application, the user should be redirected to MiMo in order for the system to authenticate the user’s identity and allow him to accept the Terms of Service. The request must include the required information for a payment: client_id, amount, notes and the callback URL.

Once the user accepts or rejects the Merchant-Initiated Payment agreement, the user will be redirected back to the callback URL along with a user authentication code. The user authentication code does not expire since the user has granted you access to your application. A user may revoke this access at a later time. It is acceptable to cache the user authentication code so that you may use it to obtain access tokens later on.

Request parameters:

Parameter Description
client_id Client ID for the application which was provided by MiMo.
url Callback URL to redirect the user to after they have approved or rejected the authentication request. If not provided, this will default to the registered OAuth Callback URL. The url parameter must be a full, valid URL.
amount The transfer amount which the user will verify for the payment.
notes The notes should include additonal information about the payment like an invoice number or similar. (Maximum of 255 characters.)
destination_user This is an optional parameter which you can use to facilitate payments between two other MiMo users. The value for this should be a valid MiMo username.
response_type MiMo uses the OAuth 'code' response type by default (OAuth Standards).

Request format:

https://sandbox.mimo.com.ng/oauth/v2/authenticate?client_id={CLIENT_ID}&url={CALLBACK_URL}&amount={AMOUNT}&notes={NOTES}&response_type=code

Request example:

https://sandbox.mimo.com.ng/oauth/v2/authenticate?client_id=k7nz3wp3tr0heW4k&url=https://www.yourwebsite.com&amount=980.99&notes=Invoice+Nr.%10234327&response_type=code

User redirection

After approving or rejecting the authentication request, the user will be redirected to the supplied callback URL along with a user authentication code. Note: this user authentication code is not your access token. The user authentication code returned on redirect is used to get a temporary access token.

Response parameters:

Parameter Description
code Returned on redirect to callback URL. This is a user authentication code which is used in the next step.

Response format for a successful approval:

{CALLBACK_URL}?code={CODE}&response_type=code

Response format for a failure or rejection:

{CALLBACK_URL}?response_type=access_denied

Response example:

https://www.yourwebsite.com?code=KXq44pIkKuE&response_type=code
Step 2: Obtaining an OAuth Access Token (Expand/Collapse)

Request an access token

In this final step of the OAuth flow, you will use the user authentication code granted on Step 1 to request a MiMo OAuth access token. In order to do so, you will need to make a POST HTTP request from your application server to the MiMo authentication server. The access token will expire after thirty (30) minutes. You will need to request a new access token after it has expired by using the user authentication code.

Request parameters:

Parameter Description
client_id Client ID for the application which was provided by MiMo.
client_secret Client Secret for the application which was provided by MiMo.
grant_type Use a value of 'authorization_code' for a web server application.
code user authentication code from redirect response in Step 1.

Request format:

POST https://sandbox.mimo.com.ng/oauth/v2/token?client_id={CLIENT_ID}&client_secret={CLIENT_SECRET}&grant_type=authorization_code&code={CODE}

Request example:

POST https://sandbox.mimo.com.ng/oauth/v2/token?client_id=k7nz3wp3tr0heW4k&client_secret=TC-Vf9hDDo89RMeiABLQSX55&grant_type=authorization_code&code=KXq44pIkKuE

MiMo's authentication server will respond to your request with the following formats, depending on whether your request was successful or not.

Response parameters:

Parameter Description
access_token Access token used to make authorized requests by your application.
error The type of error if an error occurred processing the request.
error_description The error description if an error occurred processing the request.

Successful response example:

{ access_token: AAbbCCddEE }

Failed response example:

{ "error": "access_denied" }
Step 3: OAuth Endpoints (Expand/Collapse)

Select an endpoint

After you obtained an access token you can use it to perform different actions. You may initiate a money transfer, void a previous transfer, refund a transfer, request the status of a transfer or request user information.

Money transfer endpoint

To process a payment you have to create a money transfer via this endpoint. The amount and notes for the new transaction are inherited from Step 1 when you requested the user authentication code.

The URL to POST your request for a money transfer is: https://sandbox.mimo.com.ng/partner/transfers/create

Request parameters:

Parameter Description
access_token Access token used to make authorized requests by your application.

Request format:

POST https://sandbox.mimo.com.ng/partner/transfers/create?access_token={ACCESS_TOKEN}

Request example:

POST https://sandbox.mimo.com.ng/partner/transfers/create?access_token=PccKIHvcoxXZP

Response example:

{ "message": "Money was successfully transferred.", "transactionId": 11234 }

Void transfer endpoint

A transfer can be canceled via this endpoint before the transfer has been settled.

The URL to POST your request to void a transfer is: https://sandbox.mimo.com.ng/partner/transfers/void

Request parameters:

Parameter Description
access_token Access token used to make authorized requests by your application.
transaction_id The MiMo ID for this transaction. This is returned with a successful response to transfer money.

Request format:

POST https://sandbox.mimo.com.ng/partner/transfers/void?access_token={ACCESS_TOKEN}&transaction_id={TRANSACTION_ID}

Request example:

POST https://sandbox.mimo.com.ng/partner/transfers/void?access_token=zk2tJaggbgKK8-dpJwcQiR9eUsecitrm6rU-FZIddM0&transaction_id=11234

Response example:

{ "message": "Transaction has been voided" }

Refund transfer endpoint

A transfer can be refunded if the transaction is already settled. The amount of a refund cannot exceed the amount of the original transaction.

The URL to POST your request to refund a transfer is: https://sandbox.mimo.com.ng/partner/transfers/refund

Request parameters:

Parameter Description
access_token Access token used to make authorized requests by your application.
transaction_id The MiMo ID for this transaction. This is returned with a successful response to transfer money.
amount The amount that you will be refunding the customer.
notes Notes to explain this action to the customer. (Maximum of 255 characters.)

Request format:

POST https://sandbox.mimo.com.ng/partner/transfers/refund?access_token={ACCESS_TOKEN}&transaction_id={TRANSACTION_ID}&amount={AMOUNT}&notes={NOTES}

Request example:

POST https://sandbox.mimo.com.ng/partner/transfers/refund?access_token=zk2tJaggbgKK8-dpJwcQiR9eUsecitrm6rU-FZIddM0&transaction_id=11234&amount=852.92&notes=Refund

Response example:

{ "message": "Money was successfully refunded.", "refundtransactionId": 11235 }

Transaction status endpoint

You can request the status information for a transfer that you have created.

The URL to POST your request for the status of a transfer is: https://sandbox.mimo.com.ng/partner/transfers/details

Request parameters:

Parameter Description
access_token Access token used to make authorized requests by your application.
transaction_id The MiMo ID for this transaction. This is returned with a successful response to transfer money.

Request format:

POST https://sandbox.mimo.com.ng/partner/transfers/details?access_token={ACCESS_TOKEN}&transaction_id={TRANSACTION_ID}

Request example:

POST https://sandbox.mimo.com.ng/partner/transfers/details?access_token=zk2tJaggbgKK8-dpJwcQiR9eUsecitrm6rU-FZIddM0&transaction_id=11234

Response example:

{ "id": 1, "datetime": "2013-03-28T11:32:30+01:00", "type": "Money In", "destination": { "account_type": "personal", "company_name": "foo", "first_name": "foo", "id": 1, "middle_name": nil, "surname": "bar", "username": "confirmed_foo1", "photo_url": "http://localhost:3000/images/thumb_default.png", "email": "confirmed_user1@example.com", "account_number": "2010119700" }, "amount": "1000000.0", "notes": "Deposit into receiver account", "status": "completed" }

User profile endpoint

You can request MiMo user account information for a transfer that you have created.

The URL to POST your request for user information is: https://sandbox.mimo.com.ng/partner/users/card_id

Request parameters:

Parameter Description
access_token Access token used to make authorized requests by your application.

Request format:

POST https://sandbox.mimo.com.ng/partner/users/card_id?access_token={ACCESS_TOKEN}

Request example:

POST https://sandbox.mimo.com.ng/partner/users/card_id?access_token=PccKIHvcoxXZPtI

Response example:

{ "account_number": "0000010123-0", "account_type": "personal", "company_name": "", "first_name": "fname", "id": 1, "middle_name": "mname", "surname": "lname", "username": "username", "photo_url": "/thumb_fadf.jpeg", "email": "username@mail.com", "level": 2 }
User experience (Expand/Collapse)

Here is the typical user experience of MiMo's OAuth + REST API:

1) Customer initiates a checkout on the merchant site and clicks a button to proceed to pay.

01

2) OAuth permissions page displays (only during first interaction).

02

3) If customer accepts and grants access to the client application, the user inputs their MiMo PIN code.

03

4) Merchant server interacts with the customer’s MiMo account and the transaction completes.

04
OAuth Terms of Service (Expand/Collapse)

When a MiMo user grants access to the merchant’s application for the first time, they have to accept the Terms of Service – see below. This helps users understand what kind of permissions they are granting your application.

Scope Name Scope Description
Person Account Info You allow the merchant to view information about you:
  • Username
  • MiMo account number
  • Account type (Merchant or Personal)
  • Full name
  • Company name (for Merchant accounts only)
  • Email address
  • Profile photo
  • KYC verification level (I, II, or III)
Charge Charge Account You allow the merchant to charge your MiMo account for the purchase of goods or services.