> ## Documentation Index
> Fetch the complete documentation index at: https://dvaultdocs.dukka.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Transfer API

> Handle fund transfers between accounts

# Transfer API Documentation

## Overview

The Transfer API provides endpoints for managing various types of transfers in the wallet service, including intra-wallet transfers, deposits, interbank transfers, and withdrawals.

## Base URL

`/api/v1/transfers`

## Authentication

All endpoints require authentication using an API key in the request headers:

* `X-API-KEY`: Your API key
* `X-Tenant-ID`: Tenant identifier

## Endpoints

### Intra-Wallet Transfer

Transfer funds between accounts within the same wallet.

**Endpoint:** `POST /intra`

**Headers:**

* `X-API-KEY` (optional): API key for authentication
* `X-Tenant-ID`: Tenant identifier

**Request Body:**

```json theme={null}
{
  "debitAccountId": "string",
  "recipientAccountId": "string",
  "amount": "number",
  "narration": "string",
  "requestId": "string",
  "currency": "string"
}
```

**Response:**

```json theme={null}
{
  "statusCode": 202,
  "message": "string",
  "data": "string"
}
```

### Deposit

Deposit funds into a wallet account.

**Endpoint:** `POST /deposit`

**Headers:**

* `X-API-KEY` (optional): API key for authentication
* `X-Tenant-ID`: Tenant identifier

**Request Body:**

```json theme={null}
{
  "recipientAccountId": "string",
  "amount": "number",
  "requestId": "string",
  "currency": "string",
  "narration": "string",
  "senderName": "string",
  "senderBank": "string",
  "senderAccountNumber": "string",
  "bankCode": "string"
}
```

**Response:**

```json theme={null}
{
  "statusCode": 202,
  "message": "string",
  "data": "string"
}
```

### Interbank Transfer

Transfer funds from a wallet account to an external bank account.

**Endpoint:** `POST /inter`

**Headers:**

* `X-API-KEY` (optional): API key for authentication
* `X-Tenant-ID`: Tenant identifier

**Request Body:**

```json theme={null}
{
  "requestId": "string",
  "debitAccountId": "string",
  "currency": "string",
  "bankCode": "string",
  "recipientAccountNumber": "string",
  "amount": "number",
  "narration": "string",
  "beneficiaryName": "string",
  "beneficiaryEmail": "string",
  "beneficiaryPhone": "string"
}
```

**Response:**

```json theme={null}
{
  "statusCode": 202,
  "message": "string",
  "data": "string"
}
```

### Withdrawal

Withdraw funds from a wallet account to a settlement bank account.

**Endpoint:** `POST /withdrawal`

**Headers:**

* `X-API-KEY` (optional): API key for authentication
* `X-Tenant-ID`: Tenant identifier

**Request Body:**

```json theme={null}
{
  "requestId": "string",
  "debitAccountId": "string",
  "recipientNuban": "string",
  "bankCode": "string",
  "bankName": "string",
  "bvn": "string",
  "narration": "string",
  "amount": "number",
  "currency": "string",
  "beneficiaryName": "string",
  "beneficiaryEmail": "string",
  "beneficiaryPhone": "string"
}
```

**Response:**

```json theme={null}
{
  "statusCode": 202,
  "message": "string",
  "data": "string"
}
```

## Error Responses

All endpoints may return the following error responses:

**401 Unauthorized**

```json theme={null}
{
  "statusCode": 401,
  "message": "Unauthorized",
  "data": null
}
```

**404 Not Found**

```json theme={null}
{
  "statusCode": 404,
  "message": "Account not found",
  "data": null
}
```

**409 Conflict**

```json theme={null}
{
  "statusCode": 409,
  "message": "Duplicate request ID",
  "data": null
}
```

**422 Unprocessable Entity**

```json theme={null}
{
  "statusCode": 422,
  "message": "Insufficient funds",
  "data": null
}
```

## Notes

* All timestamps are in ISO-8601 format
* Transfer types:
  * Intra-wallet: Transfer between accounts in the same wallet
  * Deposit: Funds coming into the wallet
  * Interbank: Transfer to external bank accounts
  * Withdrawal: Transfer to settlement bank accounts
* Transfer requirements:
  * Minimum transfer amount is 100
  * Accounts must be active
  * Source account must have sufficient balance
  * Currencies must match for intra-wallet transfers
  * Bank codes must be valid and supported
* Transfer processing:
  * All transfers are processed asynchronously
  * Response includes a request ID for tracking
  * Status updates are sent via notifications
  * Failed transfers can be retried
* Security measures:
  * All transfers require authentication
  * User must own the source account
  * Platform admins cannot perform transfers
  * Duplicate request IDs are rejected
* Transfer limits:
  * Subject to account tier limits
  * Subject to daily and monthly limits
  * Subject to bank-specific limits
* Transfer notifications:
  * Users are notified of transfer status changes
  * Notifications include transfer details
  * Failed transfers include reason for failure
* Transfer tracking:
  * All transfers are logged
  * Transfer history is maintained
  * Transfer status can be queried
* Transfer fees:
  * Fees are calculated based on transfer type
  * Fees are included in the transfer amount
  * Fee formulas are configurable
* Transfer validation:
  * Account numbers are validated
  * Bank codes are validated
  * Amounts are validated
  * Currencies are validated
* Transfer settlement:
  * Interbank transfers are settled via NIBSS
  * Withdrawals are settled to settlement accounts
  * Settlement status is tracked
  * Settlement failures are handled