Create Internal Transaction

POST 
/internal_transactions

Transfer an amount from the current wallet of the caller to the current wallet of the recipient. The recipient_id can be an Entity, Platform or a Beneficiary.

Some types of transfers are restricted based on your account configuration.

The result for this API is instant, either a success or a failure, if you want to revert a transaction, the recipient has to transfer the amount back.

Request

application/json

Body

required

recipient_id uuidrequired
currency Currency (string)required

ISO-4217 three-letter currency code.

amount integerrequired
A positive integer representing the internal transaction amount in the smallest currency unit.
Examples:
• 1.00 SAR = 100
• 1.00 KWD = 1000
• 1 JPY = 1
description string

A string descriping the purpose of this internal transactions.

metadata

object

A set of key-value pairs where both key and value are strings. Metadata allows you to add more information to the object that will be returned later on in responses and webhook messages.

Metadata is searchable using the Payment List API.

property name* string

Responses

200

Successful operation

application/json

Schema

Schema

id uuid
recipient_type string

Possible values: [Entity, Platform, Beneficiary]

recipient_id uuid
currency Currency (string)

ISO-4217 three-letter currency code.

amount integer

Amount of the internal transaction movement.

transfer_id uuid

In case this internal transaction has been settled, this will contain the ID of the transaction.

description string

A string descriping the purpose of this internal transactions.

created_at timestamp

Date and time when the internal transaction was created.

updated_at timestamp

Date and time when the internal transaction status was updated.

settled_at timestamp

Date and time when the internal transaction was settled.

metadata

object

A set of key-value pairs where both key and value are strings. Metadata allows you to add more information to the object that will be returned later on in responses and webhook messages.

Metadata is searchable using the Payment List API.

property name* string

Example (from schema)

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "recipient_type": "Entity",
  "recipient_id": "c5c57597-0d06-4583-9da5-c755c4943ede",
  "currency": "SAR",
  "amount": 24209,
  "transfer_id": "6db14dc8-9647-4dff-ae6f-822c29ae3a92",
  "description": "string",
  "created_at": "2026-02-15T12:59:11Z",
  "updated_at": "2026-02-15T12:59:11Z",
  "settled_at": "2026-02-16T10:13:12Z",
  "metadata": {
    "cart_id": "72e470a5-cbc4-47b3-a52a-e89fda6adb19",
    "customer_email": "[email protected]",
    "customer_id": "23432"
  }
}

400

Business Error or validation error.

application/json

Schema

Schema

type string

Contains the error type

message string

Human readable error message for the error

errors object

Contains string-array pair representing a field and list of validation errors.

Example (from schema)

{
  "type": "invalid_request",
  "message": null,
  "errors": {
    "foo": "this is returned for validation errors only"
  }
}

401

Invalid authorization credentials

application/json

Schema

Schema

type string

Possible values: [authentication_error]

message string

Possible values: [Invalid authorization credentials]

errors object

Example (from schema)

{
  "type": "authentication_error",
  "message": "Invalid authorization credentials",
  "errors": null
}

403

Invalid authorization credentials

application/json

Schema

Schema

type string

Possible values: [api_error]

message string

Possible values: [User not authorized]

errors object

Example (from schema)

{
  "type": "api_error",
  "message": "User not authorized",
  "errors": null
}

Loading...