Allocation & Withdrawals

Manage vault allocations, process withdrawals from ring-fenced funds, transfer between vaults, and view allocation history. All operations maintain the invariant that total allocations never exceed gross income.

/api/v1/allocations

Endpoints

POST

/api/v1/allocations/allocateSoon

Create a new vault allocation from safe-to-spend

POST

/api/v1/allocations/withdrawSoon

Withdraw funds from a vault to safe-to-spend

POST

/api/v1/allocations/transferSoon

Transfer between two vaults

GET

/api/v1/allocations/history/{user_id}Soon

List allocation and withdrawal history

Parameters

Parameter	Type	Required	Description
user_id	string	Required	User identifier
vault_type	string	Required	Vault category (FIXED, SAVINGS, DISCRETIONARY)
amount	integer	Required	Amount in pence to allocate or withdraw
label	string	Optional	Human-readable label for the allocation

Example

Request

http

POST /api/v1/allocations/allocate HTTP/1.1
Host: api.tpay365.com
Authorization: Bearer sk_live_abc123
Content-Type: application/json

{
  "user_id": "usr_8821-9920",
  "vault_type": "SAVINGS",
  "amount": 5000,
  "label": "Holiday Fund"
}

Response

json

{
  "allocation_id": "alloc_new789",
  "vault_type": "SAVINGS",
  "amount": 5000,
  "label": "Holiday Fund",
  "safe_to_spend_remaining": 165451,
  "created_at": "2026-02-10T14:30:00Z"
}