Bank of Maldives Merchant Services
Official API Documentation for Bank of Maldives Connect for Merchants.
Environment | Base URL |
---|---|
Testing | https://api.uat.merchants.bankofmaldives.com.mv/public |
Production | https://api.merchants.bankofmaldives.com.mv/public |
Our system uses a client_id
an client_secret
for API authentication.
You can create new third party applications using your merchant portal.
A new client_id
and client_secret
(API Key) will be issued immediately.
If you are performing direct HTTP requests to the API it sufficient to specific the API Key in the header.
Header | Content |
---|---|
Authorization | api_key |
If you are using a SDK or other libraries it is usually required to specify both the application id (client_id)
and API key (client_secret)
.
SDK | Example |
---|---|
PHP | $client = new Client('apikey', 'appid'); |
For list views the results will be paginated. The envelop for the results is as follows:
{
"count": 100 // total count of all items,
"items": [{...},{...}] // array of returned items
}
The first page parameter if you do not set it explicitely will be 1.
queryString | Example |
---|---|
page | ?page=2 |
We use both error messages and HTTP status codes. The error message envelop is as follows:
{
"code": "PP-xx-xx" // error code,
"message": "Transaction not found" // readable message explaining the error
}
HTTP status code | Description |
---|---|
400 | Bad request, check input parameters |
401 | Not authorized |
404 | Resource not found |
500 | Internal Server Error |
The transaction object exists of specific fields that are either user-defined are auto-generated by our system.
* indicates a required field.
Field | Data type | Description | Example | User-Defined | Limitations |
---|---|---|---|---|---|
amount* | int | The amount of the transaction in cents (e.g. 2000 = 20.00) | 2000 | Yes | Minimum is 100 cents in any local currency |
currency* | string | The three-letter ISO 4217 currency code | MVR | Yes | Limited to the currencies available for the merchant |
signature* | string | A checksum for the transaction | mMBR0TXWHvuno/8su3SKMg== | Yes | According to specification |
deviceId* | string | The client_id of the application | 123456789 | Yes | Must be the app id for the specified API Key |
appVersion* | string | A custom version string from your application | 123456789 | Yes | Must be the app id for the specified API Key |
apiVersion* | string | API used for this request | 2.0 | Yes | Only 2.0 is currently supported |
signMethod* | string | The method used to generate the signature | sha1 | Yes | Must be sha1 or md5 |
localId | string | A local reference by the merchant or third-party system | ID1234 | Yes | - |
customerReference | string | A reference made available to the customer | Invoice 2020-123 | Yes | - |
redirectUrl | string | The optional URL to redirect to after completion or failure of the payment | https://myshop.com/order/13245 | Yes | Only applicable in e-commerce transactions |
id | string | The unique ID of the transaction in our system | 5e22e1037ac57f000841efff | No | - |
qrcode | object | object containing the URL of the QR Code for this transaction | { url: 'https://example.org/image.png'} |
No | - |
provider | string | The payment provider for this transaction | alipay | Yes | Limited to the available payment providers for this merchant |
created | string | The creation timestamp in UTC for this transaction | 2020-01-02T10:42:14.898Z | No | - |
state | string | The status of this transaction | CONFIRMED | No | Can only be one of the following: QR_CODE_GENERATED, CONFIRMED, CANCELLED, REFUND_REQUESTED, REFUNDED |
The following exposed API operations from the Pomelo Pay API are available using the API Client. See below for more details about each resource.
Description | Data |
---|---|
Method | POST |
Testing URL | https://api.uat.merchants.bankofmaldives.com.mv/public/transactions |
Production URL | https://api.merchants.bankofmaldives.com.mv/public/transactions |
Headers | Authorization: api_key, Accept: application/json, Content-Type: application/json |
Body Example:
{
"localId": "123456789",
"customerReference": "invoice 1",
"signature": "mMBR0TXWHvuno/8su3SKMg==",
"amount": 2000,
"currency": "MVR",
"provider": "alipay",
"appVersion": "vendingSoftware1.0",
"apiVersion": "2.0",
"deviceId": "12345789",
"signMethod": "sha1"
}
Description | Data |
---|---|
Method | GET |
Testing URL | https://api.uat.merchants.bankofmaldives.com.mv/public/transactions/<:id> |
Production URL | https://api.merchants.bankofmaldives.com.mv/public/transactions/<:id> |
Headers | Authorization: api_key, Accept: application/json, Content-Type: application/json |
Example | GET https://api.merchants.bankofmaldives.com.mv/public/transactions/5e22e1037ac57f000841efff |
Description | Data |
---|---|
Method | GET |
Testing URL | https://api.uat.merchants.bankofmaldives.com.mv/public/transactions |
Production URL | https://api.merchants.bankofmaldives.com.mv/public/transactions |
Headers | Authorization: api_key, Accept: application/json, Content-Type: application/json |
Example | GET https://api.merchants.bankofmaldives.com.mv/public/transactions?page=3 |
Please see the webhook section for more information
On sending a transaction you must on application side create a signature with your api key.
On receiving webhooks it is strongly recommended to calculate the signature on your side and compare it with the specified signature to ensure data integrity.
The calculation of the signature is as follows:
Signature method | Data |
---|---|
md5 | md5('amount=2000¤cy=MVR&apiKey=mysecretkey').digest('base64') |
sha1 | sha1('amount=2000¤cy=MVR&apiKey=mysecretkey').digest('hex') |
Our system uses webhooks to receive real-time notifications about any transaction state changes. The webhooks are using the POST
http method.
It is strongly recommended to check the signature from the transaction and validate it to ensure the data is coming from an authentic source.
For more information about verifying data integrity you can check the Verifing Data Integrity section.
- Navigate to https://dashboard.merchants.bankofmaldives.com.mv
- Login with your merchant account
- From the left-hand side menu select "Connect"
- From the secondary navigation select "Webhooks"
- Enter the URL on which your system will listen for webhooks events
- The specified URL should be a publicly accessible endpoint that accepts
POST
data inJSON
format
{
"localId": "123456789" // the optional local ID from your internal system,
"customerReference": "invoice 1" // the optional customer reference ,
"transactionId": "5e22e1037ac57f000841efff" // unique transaction id,
"state": "QR_CODE_GENERATED" // state of the transction,
"created": "2020-01-02T10:42:14.898Z" // creation time in UTC,
"signature": "mMBR0TXWHvuno/8su3SKMg==" // signature of the transaction,
"amount": 2000 // amount in cents,
"currency": "MVR" // currency of the transaction,
"provider": "bml_epos" // payment method ,
"qrCode": {
"url": "https://example.org/code.png" // URL location of the QR code
}
}
{
"localId": "123456789" // the optional local ID from your internal system,
"customerReference": "invoice 1" // the optional customer reference ,
"transactionId": "5e22e1037ac57f000841efff" // unique transaction id,
"state": "CONFIRMED" // state of the transction,
"created": "2020-01-02T10:42:14.898Z" // creation time in UTC,
"signature": "mMBR0TXWHvuno/8su3SKMg==" // signature of the transaction,
"amount": 2000 // amount in cents,
"currency": "MVR" // currency of the transaction,
"provider": "bml_epos" // payment method ,
"qrCode": {
"url": "https://example.org/code.png" // URL location of the QR code
}
}
If you're looking to use this API in a specific stack or framework you currently have the following options:
Framework | Package |
---|---|
PHP7 | https://github.com/bankofmaldives/bml-connect-php |
Other | Build one and get featured here! |
Sign up with Bank of Maldives and start accepting online and instore payments for your business today!
If need support with the Bank of Maldives Connect API please open an issue on this repository.
For all other support you can contact us at π§ info@bml.com.mv