Skip to main content

Own Transfers

Learn how to transfer funds between your own Brighty accounts using the intent-based transfer system.

Overview​

Own transfers allow you to move funds between different Brighty accounts within your business. The transfer system uses a two-step process:

  1. Create Intent - Calculate fees and validate the transfer
  2. Execute Transfer - Process the actual transfer using the intent

Transfer Flow Diagram​

Prerequisites​

Before creating transfers, you'll need to identify your source and target accounts. You can retrieve all your business accounts using:

curl -X GET https://api.brighty.codes/business/v1/accounts \
  -H "Authorization: Bearer ${BRIGHTY_API_TOKEN}" \
  -H "Content-Type: application/json"

Response:

{
  "accounts": [
    {
      "id": "acc_eur_main_123",
      "currency": "EUR",
      "balance": { "amount": "1500.00", "currency": "EUR" },
      "type": "BUSINESS",
      "status": "ACTIVE"
    },
    {
      "id": "acc_usd_456",
      "currency": "USD",
      "balance": { "amount": "2000.00", "currency": "USD" },
      "type": "BUSINESS",
      "status": "ACTIVE"
    }
  ]
}

Transfer Flow​

Step 1: Create Transfer Intent​

First, calculate the transfer details and fees:

curl -L 'https://api.brighty.codes/business/v1/transfers/own/intent' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${BRIGHTY_API_TOKEN}" \
-d '{
  "amount": {
    "amount": "100",
    "currency": "EUR"
  },
  "side": "SELL",
  "sourceCurrency": "EUR",
  "targetCurrency": "USDC"
}'

Response:

{
  "amount": { "amount": "100.00", "currency": "EUR" },
  "quote": {
    "sourceAmount": { "amount": "100.00", "currency": "EUR" },
    "targetAmount": { "amount": "117.222886", "currency": "USDC" },
    "fx": {
      "rate": {
        "currencyPair": { "base": "EUR", "counter": "USDC" },
        "timestamp": "2025-07-04T14:19:33.000Z",
        "bid": "1.17222886",
        "ask": "1.1839905"
      },
      "side": "SELL",
      "appliedMarkup": "0.005",
      "feeMarkup": "0",
      "availability": "TRADABLE"
    }
  },
  "fees": [],
  "deliveryInfo": { "estimatedDeliveryDate": "2025-07-04T14:22:06.946Z" },
  "hash": "8c1c0c17994b7fc6c0576ccf1ef436305be9aa548706a08ea790af8dfaea6268"
}

Step 2: Execute Transfer​

Use the intent to execute the actual transfer:

curl -X POST https://api.brighty.codes/business/v1/transfers/own \
  -H "Authorization: Bearer ${BRIGHTY_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceAccountId": "acc_source_123",
    "targetAccountId": "acc_destination_456",
    "hash": "8c1c0c17994b7fc6c0576ccf1ef436305be9aa548706a08ea790af8dfaea6268",
    "quote": {
      "sourceAmount": { "amount": "100.00", "currency": "EUR" },
      "targetAmount": { "amount": "117.222886", "currency": "USDC" },
      "fx": {
        "rate": {
          "currencyPair": { "base": "EUR", "counter": "USDC" },
          "timestamp": "2025-07-04T14:19:33.000Z",
          "bid": "1.17222886",
          "ask": "1.1839905"
        },
        "side": "SELL",
        "appliedMarkup": "0.005",
        "feeMarkup": "0",
        "availability": "TRADABLE"
      }
    },
    "fees": []
  }'

Response:

{
  "id": "txn_transfer_789",
  "status": "COMPLETED",
  "sourceAccountId": "acc_source_123",
  "targetAccountId": "acc_destination_456",
  "quote": {
    "sourceAmount": { "amount": "100.00", "currency": "EUR" },
    "targetAmount": { "amount": "117.222886", "currency": "USDC" }
  },
  "fees": [],
  "createdAt": "2025-07-04T14:20:00Z",
  "completedAt": "2025-07-04T14:20:01Z"
}

Understanding the "Side" Parameter​

The side parameter determines the direction of the transfer:

Same Currency Transfers (EUR to EUR)​

For transfers between accounts with the same currency, the side parameter doesn't matter:

  • "side": "BUY" - Same result
  • "side": "SELL" - Same result

Cross-Currency Transfers​

For transfers involving currency conversion:

Buy Side (Buying destination currency):

{
  "amount": {
    "amount": "100.0",
    "currency": "EUR"
  },
  "side": "BUY",
  "sourceCurrency": "USD",
  "targetCurrency": "EUR"
}

"I want to buy 100 EUR using USD from my USD account"

Sell Side (Selling source currency):

{
  "amount": {
    "amount": "115.0",
    "currency": "USD"
  },
  "side": "SELL",
  "sourceCurrency": "USD",
  "targetCurrency": "EUR"
}

"I want to sell 115 USD to get EUR in my EUR account"

Transfer Examples​

Same Currency Transfer (EUR to EUR)​

# Step 1: Create intent
curl -X POST https://api.brighty.codes/business/v1/transfers/own/intent \
  -H "Authorization: Bearer ${BRIGHTY_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": {
      "amount": "500.00",
      "currency": "EUR"
    },
    "side": "SELL",
    "sourceCurrency": "EUR",
    "targetCurrency": "EUR"
  }'

# Step 2: Execute transfer
curl -X POST https://api.brighty.codes/business/v1/transfers/own \
  -H "Authorization: Bearer ${BRIGHTY_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceAccountId": "acc_eur_main",
    "targetAccountId": "acc_eur_savings",
    "hash": "intent_hash_from_response",
    "quote": {
      "sourceAmount": { "amount": "500.00", "currency": "EUR" },
      "targetAmount": { "amount": "500.00", "currency": "EUR" },
      "fx": null
    },
    "fees": []
  }'

Cross-Currency Transfer (USD to EUR)​

# Step 1: Create intent (buying EUR with USD)
curl -X POST https://api.brighty.codes/business/v1/transfers/own/intent \
  -H "Authorization: Bearer ${BRIGHTY_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": {
      "amount": "100.00",
      "currency": "EUR"
    },
    "side": "BUY",
    "sourceCurrency": "USD",
    "targetCurrency": "EUR"
  }'

# Response shows exchange rate and amounts
{
  "amount": { "amount": "100.00", "currency": "EUR" },
  "quote": {
    "sourceAmount": { "amount": "117.65", "currency": "USD" },
    "targetAmount": { "amount": "100.00", "currency": "EUR" },
    "fx": {
      "rate": {
        "currencyPair": { "base": "USD", "counter": "EUR" },
        "timestamp": "2025-07-04T14:19:33.000Z",
        "bid": "0.85",
        "ask": "0.852"
      },
      "side": "BUY",
      "appliedMarkup": "0.005",
      "feeMarkup": "0",
      "availability": "TRADABLE"
    }
  },
  "fees": [],
  "deliveryInfo": { "estimatedDeliveryDate": "2025-07-04T14:22:06.946Z" },
  "hash": "abc123def456..."
}

# Step 2: Execute with exact values from intent
curl -X POST https://api.brighty.codes/business/v1/transfers/own \
  -H "Authorization: Bearer ${BRIGHTY_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceAccountId": "acc_usd_123",
    "targetAccountId": "acc_eur_456",
    "hash": "abc123def456...",
    "quote": {
      "sourceAmount": { "amount": "117.65", "currency": "USD" },
      "targetAmount": { "amount": "100.00", "currency": "EUR" },
      "fx": {
        "rate": {
          "currencyPair": { "base": "USD", "counter": "EUR" },
          "timestamp": "2025-07-04T14:19:33.000Z",
          "bid": "0.85",
          "ask": "0.852"
        },
        "side": "BUY",
        "appliedMarkup": "0.005",
        "feeMarkup": "0",
        "availability": "TRADABLE"
      }
    },
    "fees": []
  }'

Error Handling​

Common Transfer Errors​

ErrorDescriptionSolution
insufficient_fundsNot enough balance in source accountCheck account balance
invalid_accountAccount ID doesn't existVerify account IDs
intent_expiredTransfer intent has expiredCreate new intent
quote_mismatchQuote values don't match intentUse exact values from intent response
hash_mismatchHash doesn't match the intentUse exact hash from intent response

Error Response Example​

{
  "errorCode": 400,
  "name": "InsufficientFunds",
  "description": "Insufficient funds in source account",
  "details": {
    "requiredAmount": { "amount": "500.50", "currency": "EUR" },
    "availableBalance": { "amount": "450.00", "currency": "EUR" }
  }
}

Best Practices​

1. Always Use the Intent Flow​

  • Never skip the intent step
  • Use exact values from intent response in transfer execution
  • Check intent expiration time

2. Error Handling​

  • Handle insufficient funds gracefully
  • Validate account IDs before transfer
  • Implement retry logic for temporary failures

3. Fee Management​

  • Always display fees to users before transfer
  • Include fees in balance calculations
  • Store fee information for accounting

4. Testing​

  • Test with small amounts first
  • Verify both successful and failed scenarios
  • Test cross-currency transfers if applicable