Transfers | Phoenix Wallet

Transfers move funds from one wallet to another. The system uses double-entry accounting to ensure the total balance remains consistent.

Create Transfer

Move funds from a source wallet to a destination wallet.

POST /transfers

Request Headers

Header	Required	Description
`Authorization`	Yes	Bearer token
`Content-Type`	Yes	`application/json`
`Idempotency-Key`	Yes	Unique request identifier

Request Body

Field	Type	Required	Description
`from_wallet_id`	string	Yes	Source wallet ID
`to_wallet_id`	string	Yes	Destination wallet ID
`amount`	string	Yes	Amount to transfer (decimal string)
`asset`	string	Yes	Asset type (e.g., `POINTS`, `BONUS`)
`reference`	string	No	Your reference for this transaction
`metadata`	object	No	Custom key-value pairs
`lot_selection`	object	No	Configure which lots to draw from

Lot Selection Options

Field	Type	Default	Description
`lot_selection.strategy`	string	`fifo`	Selection strategy: `fifo`, `lifo`, `expiring_first`, `specific`
`lot_selection.lot_ids`	array	-	Specific lot IDs (required when strategy is `specific`)

Example Request

curl -X POST {{BASE_URL}}/transfers \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: {{IDEMPOTENCY_KEY}}" \
  -d '{
    "from_wallet_id": "wal_abc123def456",
    "to_wallet_id": "wal_def456ghi789",
    "amount": "100.00",
    "asset": "POINTS",
    "reference": "peer_transfer_001",
    "metadata": {
      "reason": "gift",
      "initiated_by": "user_12345"
    },
    "lot_selection": {
      "strategy": "expiring_first"
    }
  }'

Example Response

{
  "data": {
    "id": "txf_lmn123opq456",
    "from_wallet_id": "wal_abc123def456",
    "to_wallet_id": "wal_def456ghi789",
    "amount": "100.00",
    "asset": "POINTS",
    "reference": "peer_transfer_001",
    "status": "completed",
    "lot_movements": [
      {
        "from_lot_id": "lot_xyz789abc123",
        "to_lot_id": "lot_new456def789",
        "amount": "100.00"
      }
    ],
    "metadata": {
      "reason": "gift",
      "initiated_by": "user_12345"
    },
    "created_at": "2024-01-15T11:00:00Z"
  }
}

Error Codes

Code	Description
`WALLET_NOT_FOUND`	Source or destination wallet does not exist
`WALLET_SUSPENDED`	Cannot transfer from/to a suspended wallet
`INSUFFICIENT_BALANCE`	Source wallet has insufficient available funds
`INVALID_AMOUNT`	Amount must be a positive decimal
`INVALID_ASSET`	Asset type is not configured
`SAME_WALLET`	Cannot transfer to the same wallet
`LOT_NOT_FOUND`	Specified lot does not exist (specific strategy)
`LOT_INSUFFICIENT_BALANCE`	Specified lot has insufficient balance
`POLICY_VIOLATION`	Transfer violates wallet policies
`RESTRICTION_VIOLATION`	Lot restrictions prevent this transfer

Transfer with Lot Attributes

When transferring, you can preserve or modify lot attributes for the destination.

POST /transfers

Additional Request Body Fields

Field	Type	Required	Description
`destination_lot`	object	No	Configuration for destination lot
`destination_lot.preserve_expiry`	boolean	No	Keep original expiration (default: true)
`destination_lot.preserve_attributes`	boolean	No	Keep original attributes (default: true)
`destination_lot.expires_at`	string	No	Override expiration (requires `preserve_expiry: false`)
`destination_lot.attributes`	object	No	Override attributes (requires `preserve_attributes: false`)

Example Request

curl -X POST {{BASE_URL}}/transfers \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: {{IDEMPOTENCY_KEY}}" \
  -d '{
    "from_wallet_id": "wal_abc123def456",
    "to_wallet_id": "wal_def456ghi789",
    "amount": "50.00",
    "asset": "POINTS",
    "reference": "conversion_001",
    "destination_lot": {
      "preserve_expiry": false,
      "preserve_attributes": false,
      "expires_at": "2025-12-31T23:59:59Z",
      "attributes": {
        "source": "conversion",
        "original_asset": "BONUS"
      }
    }
  }'

Transfer from Reservation

Convert a held reservation into a transfer to another wallet.

POST /transfers/from-reservation

Request Body

Field	Type	Required	Description
`reservation_id`	string	Yes	Reservation to convert
`to_wallet_id`	string	Yes	Destination wallet ID
`amount`	string	No	Partial amount (defaults to full reservation)
`reference`	string	No	Your reference for this transaction
`metadata`	object	No	Custom key-value pairs

Example Request

curl -X POST {{BASE_URL}}/transfers/from-reservation \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: {{IDEMPOTENCY_KEY}}" \
  -d '{
    "reservation_id": "rsv_abc123def456",
    "to_wallet_id": "wal_merchant_001",
    "reference": "order_completion_789"
  }'

Example Response

{
  "data": {
    "id": "txf_rst789uvw012",
    "from_wallet_id": "wal_abc123def456",
    "to_wallet_id": "wal_merchant_001",
    "amount": "75.00",
    "asset": "POINTS",
    "reference": "order_completion_789",
    "status": "completed",
    "reservation_id": "rsv_abc123def456",
    "reservation_status": "committed",
    "created_at": "2024-01-15T12:00:00Z"
  }
}

Error Codes

Code	Description
`RESERVATION_NOT_FOUND`	Reservation does not exist
`RESERVATION_EXPIRED`	Reservation has expired
`RESERVATION_ALREADY_COMMITTED`	Reservation was already committed
`RESERVATION_ALREADY_RELEASED`	Reservation was already released
`AMOUNT_EXCEEDS_RESERVATION`	Requested amount exceeds reservation

Get Transfer

Retrieve details of a specific transfer.

GET /transfers/{{TRANSFER_ID}}

Path Parameters

Parameter	Type	Description
`transfer_id`	string	The transfer ID (e.g., `txf_lmn123opq456`)

Example Request

curl -X GET {{BASE_URL}}/transfers/{{TRANSFER_ID}} \
  -H "Authorization: Bearer {{API_KEY}}"

Example Response

{
  "data": {
    "id": "txf_lmn123opq456",
    "from_wallet_id": "wal_abc123def456",
    "to_wallet_id": "wal_def456ghi789",
    "amount": "100.00",
    "asset": "POINTS",
    "reference": "peer_transfer_001",
    "status": "completed",
    "lot_movements": [
      {
        "from_lot_id": "lot_xyz789abc123",
        "to_lot_id": "lot_new456def789",
        "amount": "100.00"
      }
    ],
    "metadata": {
      "reason": "gift",
      "initiated_by": "user_12345"
    },
    "created_at": "2024-01-15T11:00:00Z"
  }
}

List Transfers

Retrieve a paginated list of transfers for a wallet.

GET /wallets/{{WALLET_ID}}/transfers

Path Parameters

Parameter	Type	Description
`wallet_id`	string	The wallet ID

Query Parameters

Parameter	Type	Default	Description
`limit`	integer	20	Number of results (max 100)
`cursor`	string	-	Pagination cursor
`direction`	string	-	Filter by `incoming` or `outgoing`
`asset`	string	-	Filter by asset type
`from_date`	string	-	Filter transfers after this date (ISO 8601)
`to_date`	string	-	Filter transfers before this date (ISO 8601)

Example Request

curl -X GET "{{BASE_URL}}/wallets/{{WALLET_ID}}/transfers?direction=outgoing&limit=10" \
  -H "Authorization: Bearer {{API_KEY}}"

Example Response

{
  "data": [
    {
      "id": "txf_lmn123opq456",
      "from_wallet_id": "wal_abc123def456",
      "to_wallet_id": "wal_def456ghi789",
      "amount": "100.00",
      "asset": "POINTS",
      "reference": "peer_transfer_001",
      "status": "completed",
      "created_at": "2024-01-15T11:00:00Z"
    }
  ],
  "pagination": {
    "has_more": false,
    "next_cursor": null
  }
}