# Create an internal transfer

Creates an internal transfer between two merchant accounts.

Endpoint: POST /internal-transfer
Version: 1.0.0
Security: JWT

## Request fields (application/json):

  - `amount` (integer, required)
    The amount to transfer in cents. For example, 10000 cents is 100.00. The currency is determined by the currency field.
    Example: 10000

  - `currency` (string, required)
    The currency in which the transfer is made. The currency code is in [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) format. Currently only AED is supported for internal transfers.
    Enum: "AED"

  - `reference` (string, required)
    A reference identifier for the transfer. Maximum length is 100 characters.
    Example: "sample-reference"

  - `from_merchant_id` (string, required)
    The unique identifier of the merchant account from which funds will be transferred.
    Example: "merch_68cc1216xPrdU"

  - `to_merchant_id` (string, required)
    The unique identifier of the merchant account to which funds will be transferred. Must be different from from_merchant_id.
    Example: "merch_68cc0571y5S4h"

## Response 201 fields (application/json):

  - `id` (string)
    The unique identifier for the internal transfer.
    Example: "inttransfer_68f1f9126GDCB"

  - `from_merchant_id` (string)
    The unique identifier of the merchant account from which funds were transferred.
    Example: "merch_68cc1216xPrdU"

  - `to_merchant_id` (string)
    The unique identifier of the merchant account to which funds were transferred.
    Example: "merch_68cc0571y5S4h"

  - `owner_merchant_id` (string)
    The unique identifier of the merchant account that owns/initiated this transfer.
    Example: "merch_68cc0571y5S4h"

  - `transfer_amount` (integer)
    The amount transferred in cents. For example, 1000 cents is 10.00.
    Example: 1000

  - `transfer_currency` (string)
    The currency in which the transfer was made. The currency code is in [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) format.
    Example: "AED"

  - `reference` (string)
    The reference identifier provided for the transfer.
    Example: "123"

  - `fees` (object)
    The fees associated with the internal transfer.
    Example: {"txn_fee":{"currency":"AED","amount":0},"fx_fee":{"currency":"AED","amount":0}}

  - `fees.txn_fee` (object)
    The transaction fee charged for the internal transfer.
    Example: {"currency":"AED","amount":0}

  - `fees.txn_fee.amount` (number)
    A positive integer representing the smallest currency unit.  For example, if the amount is $299.00, then pass 29900 in this field.  In the case of three decimal currencies, such as KWD, BHD and OMR, to represent an amount of 295.991, pass the value as 295990.  And in the case of zero decimal currencies such as JPY, for amount ￥295, pass the value as 295.
    Example: 1000

  - `fees.txn_fee.currency` (string)
    The currency code in [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) format. For example, USD.
    Example: "AED"

  - `fees.fx_fee` (object)
    The foreign exchange fee charged for the internal transfer.
    Example: {"currency":"AED","amount":0}

  - `error_code` (string,null)
    The error code if the internal transfer failed, null otherwise.

  - `error_description` (string,null)
    The error description if the internal transfer failed, null otherwise.

  - `created_at` (string)
    The creation timestamp of the internal transfer.
    Example: "2025-10-17T08:06:42Z"

  - `updated_at` (string)
    The last update timestamp of the internal transfer.
    Example: "2025-10-17T08:06:42Z"

## Response 400 fields (application/json):

  - `error` (string)
    Example: "Bad Request"

  - `message` (string)
    Example: "Invalid request data"

## Response 401 fields (application/json):

  - `error` (string)
    Example: "Unauthorized"

  - `message` (string)
    Example: "Invalid or missing authentication token"