# Create an internal transfer

Creates an internal transfer between two merchant accounts.

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

## Security:

  - `JWT` (unknown)
    http bearer JWT

## Request fields (application/json):

  - `amount` (integer, required)
    The amount to transfer, in the smallest unit of `currency` (cents for USD). `10000` is $100.00 when `currency` is USD. A positive integer, sent as a JSON number.
    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, case-insensitive.
    Example: 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:

  - `201` (unknown)
    Internal transfer created successfully

## 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 the smallest unit of `transfer_currency` (cents for USD). `1000` is $10.00 when `transfer_currency` is USD.
    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)

  - `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: USD

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

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

  - `created_at` (string)
    When the internal transfer was created, as an ISO 8601 date-time in UTC.
    Example: 2025-10-17T08:06:42Z

  - `updated_at` (string)
    When the internal transfer was last updated, as an ISO 8601 date-time in UTC.
    Example: 2025-10-17T08:06:42Z

## Response 400:

  - `400` (unknown)
    Bad Request

## Response 400 fields (application/json):

  - `error` (string)
    Example: Bad Request

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

## Response 401:

  - `401` (unknown)
    Unauthorized

## Response 401 fields (application/json):

  - `error` (string)
    Example: Unauthorized

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