thijooree/docs/bmlapi/08-transfer.md

# Transfer

Initiate and confirm a fund transfer. The process is two-step: an initial POST triggers an OTP to the user's chosen channel; a second POST with the OTP confirms and completes the transfer.

The same endpoint (`POST /api/mobile/transfer`) handles both steps — the presence of an `otp` field distinguishes them.

---

## Prerequisites

- Valid `access_token` from [OAuth Token Exchange](03-oauth-token.md)
- Validated destination account from [Account Validation](10-validate.md)

---

## Transfer Channels

Before initiating a transfer, fetch the OTP channels available to the user.

```
GET https://www.bankofmaldives.com.mv/internetbanking/api/mobile/transfer
```

```bash
curl --request GET \
  --url 'https://www.bankofmaldives.com.mv/internetbanking/api/mobile/transfer' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'User-Agent: bml-mobile-banking/348 ({manufacturer}; Android {version}; {model})' \
  --header 'x-app-version: 2.1.44.348'
```

### Response

```json
{
  "success": true,
  "payload": {
    "transfer": {
      "otpChannel": [
        {
          "channel": "token",
          "description": "Authenticator App",
          "masked": ""
        },
        {
          "channel": "sms",
          "description": "SMS",
          "masked": "+960 9XX XXXX"
        }
      ]
    }
  }
}
```

| Field | Type | Description |
|---|---|---|
| `channel` | `string` | Channel identifier — use in transfer requests |
| `description` | `string` | Human-readable channel name |
| `masked` | `string` | Partially masked destination (blank for authenticator) |

---

## Transfer Types

| `transfertype` | Description | Requires `bank` |
|---|---|---|
| `IAT` | Internal — BML account to BML account | No |
| `QTR` | Quick Transfer — via PayMV alias | No |
| `DOT` | Domestic Outside Transfer — BML to another bank (e.g. MIB) | Yes — BIC of the destination bank |

---

## Step 1 — Initiate Transfer (Trigger OTP)

```
POST https://www.bankofmaldives.com.mv/internetbanking/api/mobile/transfer
```

### Request Body

**Content-Type:** `application/json`

```json
{
  "debitAccount": "7730000000001",
  "creditAccount": "7730000000002",
  "debitAmount": 100.00,
  "transfertype": "IAT",
  "currency": "MVR",
  "channel": "token"
}
```

For `DOT` (outside bank) transfers, add `"bank"`:

```json
{
  "debitAccount": "7730000000001",
  "creditAccount": "90101000000001000",
  "debitAmount": 250.00,
  "transfertype": "DOT",
  "currency": "MVR",
  "channel": "sms",
  "bank": "MIBVMVMV"
}
```

| Field | Type | Description |
|---|---|---|
| `debitAccount` | `string` | Source BML account number |
| `creditAccount` | `string` | Destination account number |
| `debitAmount` | `number` | Amount to transfer |
| `transfertype` | `string` | `IAT`, `QTR`, or `DOT` |
| `currency` | `string` | Currency code (e.g. `"MVR"`, `"USD"`) |
| `channel` | `string` | OTP channel from the channels list (e.g. `"token"`, `"sms"`) |
| `bank` | `string` | BIC of the destination bank — required for `DOT` only |

### Headers

| Header | Value |
|---|---|
| `Authorization` | `Bearer <access_token>` |
| `User-Agent` | `bml-mobile-banking/348 ({manufacturer}; Android {version}; {model})` |
| `x-app-version` | `2.1.44.348` |
| `accept` | `application/json` |

```bash
curl --request POST \
  --url 'https://www.bankofmaldives.com.mv/internetbanking/api/mobile/transfer' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'User-Agent: bml-mobile-banking/348 ({manufacturer}; Android {version}; {model})' \
  --header 'x-app-version: 2.1.44.348' \
  --header 'accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{"debitAccount":"7730000000001","creditAccount":"7730000000002","debitAmount":100.00,"transfertype":"IAT","currency":"MVR","channel":"token"}'
```

### Response — OTP Triggered

```json
{
  "success": true,
  "code": 22,
  "message": "OTP sent to your authenticator app"
}
```

`success: true` AND `code: 22` together confirm that the OTP has been dispatched. Proceed to Step 2.

Any other combination means the request failed.

---

## Step 2 — Confirm Transfer (Submit OTP)

```
POST https://www.bankofmaldives.com.mv/internetbanking/api/mobile/transfer
```

Repeat the exact same body as Step 1, adding the `otp` field (and optionally `remarks`).

### Request Body

```json
{
  "debitAccount": "7730000000001",
  "creditAccount": "7730000000002",
  "debitAmount": 100.00,
  "transfertype": "IAT",
  "currency": "MVR",
  "channel": "token",
  "otp": "123456",
  "remarks": "Rent payment"
}
```

| Additional field | Type | Description |
|---|---|---|
| `otp` | `string` | OTP received via the chosen channel |
| `remarks` | `string` | Optional transfer reference/memo (omit if blank) |

```bash
curl --request POST \
  --url 'https://www.bankofmaldives.com.mv/internetbanking/api/mobile/transfer' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'User-Agent: bml-mobile-banking/348 ({manufacturer}; Android {version}; {model})' \
  --header 'x-app-version: 2.1.44.348' \
  --header 'accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{"debitAccount":"7730000000001","creditAccount":"7730000000002","debitAmount":100.00,"transfertype":"IAT","currency":"MVR","channel":"token","otp":"123456","remarks":"Rent payment"}'
```

---

## Responses

### Success

```json
{
  "success": true,
  "message": "Transfer successful",
  "payload": {
    "reference": "FT202605160001",
    "timestamp": "2026-05-16 15:10:25"
  }
}
```

| Field | Type | Description |
|---|---|---|
| `success` | `bool` | `true` |
| `message` | `string` | Confirmation message |
| `payload.reference` | `string` | Transfer reference number |
| `payload.timestamp` | `string` | Completion timestamp |

### Failure

```json
{
  "success": false,
  "message": "Invalid OTP. Please try again."
}
```

`success: false` — the `message` field contains the reason. Common causes: wrong OTP, insufficient balance, invalid account.

---

&nbsp;

---

[← Card Statement](07-card-statement.md) &nbsp;&nbsp;&nbsp; **Next →** [Contacts](09-contacts.md)