Transfers

Transfers move funds instantly between Martis accounts within the platform. Unlike payouts that send money to external bank accounts, transfers keep funds within the Martis ecosystem for immediate availability.

Overview

Transfers enable instant money movement between active Martis accounts without external processing delays. Common use cases include:

Business-to-business payments between platform merchants
Multi-account fund allocation
Internal treasury management
Revenue sharing between partners

Transfers require both source and destination accounts to be active. For sending funds to external bank accounts, use Payouts.

Transfer Flow

Stage	Description
1. Initiation	Transfer request submitted via API with destination account and amount
2. Validation	Source balance and destination account status verified
3. Execution	Funds deducted from source and credited to destination
4. Confirmation	Transfer completed with immediate availability

Key Features

Feature	Description
Instant Settlement	Funds available immediately in the destination account
Real-time Validation	Immediate confirmation of account status and balance
Automated Tracking	Complete audit trail with timestamps and references
Zero Processing Delay	No external banking system involvement

Transfer States

A transfer can have the following states:

Name
succeeded
Description
Transfer completed successfully. Funds are available in the destination account.
Name
failed
Description
Transfer failed due to insufficient balance or inactive destination account.

Requirements

Before initiating a transfer:

Source Account: Must have sufficient available balance
Destination Account: Must be an active Martis account
API Authentication: Valid API key with transfer permissions

Example: Create a Transfer

curl --location 'https://api-staging.martis.id/api/v1/transfers' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {API_KEY}' \
--data '{
  "destination_account_id": "01HZDEF456789012ABCDEF",
  "amount": 100000.00,
  "currency": "idr",
  "description": "Revenue share payment",
  "client_reference_id": "TRF-2024-001"
}'

Response

{
  "status": "success",
  "data": {
    "id": "01HZXYZ789012345ABCDEF",
    "source_account_id": "01HZABC123456789FEDCBA",
    "destination_account_id": "01HZDEF456789012ABCDEF",
    "source_account_name": "Source Business",
    "destination_account_name": "Destination Business",
    "amount": 100000.00,
    "currency": "idr",
    "status": "succeeded",
    "description": "Revenue share payment",
    "client_reference_id": "TRF-2024-001",
    "created_at": "2025-01-15T10:30:00Z",
    "updated_at": "2025-01-15T10:30:00Z"
  }
}

Error Handling

Common transfer errors and resolutions:

Error	Cause	Resolution
`Destination account is not active`	Target account inactive or suspended	Verify destination account status
`Insufficient balance`	Source balance less than transfer amount	Check available balance before transfer
`Amount must be greater than 0`	Invalid amount provided	Ensure amount is a positive number

Best Practices

Validate destination accounts before initiating transfers to avoid failed transactions
Use client_reference_id to correlate transfers with internal records
Implement idempotency using the Idempotency-Key header for safe retries
Monitor balances to ensure sufficient funds for planned transfers

Integration

View Transfers API