Multi-Entity Sub-Accounts & Reporting

Manage complex organizational structures with per-entity custodial wallets and automated financial reporting systems

Summary

Represent each sub-entity as a Swipelux Customer. Use per-entity wallets and GET /balances for reporting. Subscribe to webhooks for state changes; REST verify before updating ledgers.

Problem → Solution mapping

Pain	Capability	Mechanism
Need sub-accounts	Customers API	1:1 mapping to entities
Periodic reporting	Balances API	Poll and cache balances
Audit trail	Webhooks	Store event IDs; re-verify

Architecture

Implementation steps

Create entity as customer

curl https://wallet.swipelux.com/v1/customers \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: sk_test_1234567890abcdef' \
  --data '{"firstName":"Entity","lastName":"North","email":"north@example.com","phone":"+12025550122","birthDate":"1992-02-02","residentialAddress":{"streetLine1":"100 North Ave","city":"Chicago","state":"IL","postalCode":"60601","country":"US"},"identifyingInformation":[{"type":"drivers_license","issuingCountry":"US","frontSideImage":"data:image/png;base64,AAA...","backSideImage":"data:image/png;base64,BBB..."}]}'

Poll balances

curl https://wallet.swipelux.com/v1/customers/cus_cK69MttD5nAUAbud1B/balances \
  --header 'X-API-Key: sk_test_1234567890abcdef'

Handle transfer events

# On webhook, store event, then:
curl https://wallet.swipelux.com/v1/transfers/tr_nEZHWur1pBSAKY7NlV \
  --header 'X-API-Key: sk_test_1234567890abcdef'

Webhooks

Enable once; store secretKey. Validate HMAC each delivery; reconcile via REST.

UX choices

Expose per-entity balance widgets; link to hosted checkout for top-ups.

KPIs

Data freshness (lag), reconciliation failures, event replay handling.

Limits & caveats

USD/USDC only. No webhook-only ledger updates.

Troubleshooting

Recover by re-listing known transfer IDs from your DB and re-GET each.

On this page