Create a transaction

POST

/api/v1/transactions

Unified endpoint for creating all types of transactions with consistent payload.
All transaction types require the same base fields and support multi-currency.

Required fields for ALL types:

portfolio_id - Portfolio ID

account_id - Source account ID

kind - "incoming" or "outgoing"

amount_cents - Amount in cents

amount_currency - Currency code (e.g., "IDR", "MYR", "USD")

category_id - Category ID (required for all transactions)

Optional fields for ALL types:

description, notes, reference_number, transaction_date

destination_amount_cents, destination_currency, exchange_rate (for multi-currency)

For Internal Transfer: Add transfer_type: "internal" and destination_account_id

For External Transfer: Add transfer_type: "external" and either:

external_account_id (use existing), OR

external_name + external_account_number + external_bank_name (create new)

Request

Authorization

JWT Bearer

Add the parameter

Authorization

to Headers

Example:

Authorization: ********************

Body Params application/jsonRequired

Examples

Responses

🟢201Created

application/json

Transaction created

Bodyapplication/json

Request Example

Shell

JavaScript

Java

Swift

cURL

Regular expense (IDR)Regular income with currency conversionInternal transfer (same currency)Internal transfer cross-currency (Wise MYR → BCA IDR)External transfer (create new external account)External transfer (use existing external account)External transfer cross-currency

curl --location '/api/v1/transactions' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
    "portfolio_id": "portfolio-uuid",
    "account_id": "account-uuid",
    "kind": "outgoing",
    "amount_cents": 150000,
    "amount_currency": "IDR",
    "category_id": "category-uuid",
    "description": "Lunch at restaurant",
    "transaction_date": "2024-01-15"
}'

Response Example

{
    "success": true,
    "data": {
        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
        "kind": "incoming",
        "amount": {
            "cents": 100000,
            "currency": "IDR"
        },
        "description": "Grocery shopping at supermarket",
        "notes": "string",
        "reference_number": "string",
        "transaction_date": "2019-08-24T14:15:22.123Z",
        "account": {
            "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
            "label": "string",
            "kind": "string"
        },
        "category": {
            "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
            "name": "string",
            "icon": "string",
            "color": "string"
        },
        "is_transfer": true,
        "transfer_type": "internal",
        "transfer_details": {
            "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
            "external": true,
            "external_destination": "string",
            "external_name": "John Doe",
            "external_account_number": "1234567890",
            "source_amount": {
                "cents": 100000,
                "currency": "IDR"
            },
            "destination_amount": {
                "cents": 100000,
                "currency": "IDR"
            },
            "exchange_rate": 0,
            "fee": {
                "cents": 100000,
                "currency": "IDR"
            }
        },
        "attachments": [
            {
                "id": "string",
                "filename": "string",
                "content_type": "string",
                "byte_size": 0,
                "url": "string"
            }
        ],
        "created_at": "2019-08-24T14:15:22.123Z",
        "updated_at": "2019-08-24T14:15:22.123Z"
    }
}

Modified at 2025-12-03 16:47:21

List all transactions

List transactions for a specific account