0
# Treasury
1
2
Stripe Treasury enables platforms to offer embedded financial services including bank-like accounts, money movement, and financial management tools. This comprehensive financial infrastructure supports everything from simple balance management to complex multi-party financial workflows.
3
4
## Financial Accounts
5
6
### Treasury.FinancialAccounts
7
8
Create and manage financial accounts with banking capabilities:
9
10
```typescript { .api }
11
interface TreasuryFinancialAccount {
12
id: string;
13
object: 'treasury.financial_account';
14
supported_currencies: string[];
15
features: {
16
card_issuing?: { requested: boolean; status: 'active' | 'pending' | 'restricted' };
17
deposit_insurance?: { requested: boolean; status: 'active' | 'pending' | 'restricted' };
18
financial_addresses?: {
19
aba?: { requested: boolean; status: 'active' | 'pending' | 'restricted' };
20
};
21
inbound_transfers?: {
22
ach?: { requested: boolean; status: 'active' | 'pending' | 'restricted' };
23
};
24
intra_stripe_flows?: { requested: boolean; status: 'active' | 'pending' | 'restricted' };
25
outbound_payments?: {
26
ach?: { requested: boolean; status: 'active' | 'pending' | 'restricted' };
27
us_domestic_wire?: { requested: boolean; status: 'active' | 'pending' | 'restricted' };
28
};
29
outbound_transfers?: {
30
ach?: { requested: boolean; status: 'active' | 'pending' | 'restricted' };
31
us_domestic_wire?: { requested: boolean; status: 'active' | 'pending' | 'restricted' };
32
};
33
};
34
balance: {
35
[currency: string]: {
36
available: number;
37
pending: number;
38
};
39
};
40
financial_addresses: FinancialAddress[];
41
status: 'open' | 'closed';
42
}
43
44
// Create financial account with basic features
45
const financialAccount = await stripe.treasury.financialAccounts.create({
46
supported_currencies: ['usd'],
47
features: {
48
card_issuing: { requested: true },
49
deposit_insurance: { requested: true },
50
financial_addresses: {
51
aba: { requested: true }
52
},
53
inbound_transfers: {
54
ach: { requested: true }
55
},
56
outbound_transfers: {
57
ach: { requested: true },
58
us_domestic_wire: { requested: true }
59
}
60
}
61
});
62
63
// Create financial account for marketplace
64
const marketplaceAccount = await stripe.treasury.financialAccounts.create({
65
supported_currencies: ['usd', 'eur'],
66
features: {
67
card_issuing: { requested: true },
68
deposit_insurance: { requested: true },
69
intra_stripe_flows: { requested: true },
70
outbound_payments: {
71
ach: { requested: true }
72
}
73
},
74
metadata: {
75
account_type: 'marketplace_settlement',
76
business_id: 'biz_123'
77
}
78
});
79
80
// Retrieve financial account
81
const retrieved = await stripe.treasury.financialAccounts.retrieve('fa_123', {
82
expand: ['financial_addresses']
83
});
84
85
// Update financial account
86
const updated = await stripe.treasury.financialAccounts.update('fa_123', {
87
metadata: {
88
updated_features: 'added_wire_transfers',
89
updated_at: new Date().toISOString()
90
}
91
});
92
93
// List financial accounts
94
const accounts = await stripe.treasury.financialAccounts.list({
95
limit: 10
96
});
97
98
// Retrieve account features
99
const features = await stripe.treasury.financialAccounts.retrieveFeatures('fa_123');
100
101
// Update account features
102
const updatedFeatures = await stripe.treasury.financialAccounts.updateFeatures(
103
'fa_123',
104
{
105
card_issuing: { requested: false }, // Disable card issuing
106
outbound_payments: {
107
us_domestic_wire: { requested: true } // Enable wire payments
108
}
109
}
110
);
111
```
112
113
## Money Movement - Inbound
114
115
### Treasury.InboundTransfers
116
117
Handle incoming money transfers:
118
119
```typescript { .api }
120
interface TreasuryInboundTransfer {
121
id: string;
122
object: 'treasury.inbound_transfer';
123
financial_account: string;
124
amount: number;
125
currency: string;
126
status: 'processing' | 'succeeded' | 'failed' | 'canceled';
127
origin_payment_method: string;
128
origin_payment_method_details?: {
129
type: 'us_bank_account';
130
us_bank_account?: {
131
account_holder_type?: 'individual' | 'company';
132
account_type?: 'checking' | 'savings';
133
bank_name?: string;
134
fingerprint?: string;
135
last4?: string;
136
routing_number?: string;
137
};
138
};
139
failure_details?: {
140
code?: string;
141
description?: string;
142
};
143
}
144
145
// Create inbound transfer from bank account
146
const inboundTransfer = await stripe.treasury.inboundTransfers.create({
147
financial_account: 'fa_123',
148
amount: 10000, // $100.00
149
currency: 'usd',
150
origin_payment_method: 'pm_bank_account_123',
151
description: 'Initial funding from business bank account'
152
});
153
154
// Create inbound transfer with metadata
155
const fundingTransfer = await stripe.treasury.inboundTransfers.create({
156
financial_account: 'fa_456',
157
amount: 50000, // $500.00
158
currency: 'usd',
159
origin_payment_method: 'pm_bank_account_456',
160
statement_descriptor: 'ACME FUNDING',
161
metadata: {
162
source: 'business_bank_account',
163
purpose: 'operational_funding',
164
reference_id: 'funding_789'
165
}
166
});
167
168
// Retrieve inbound transfer
169
const retrieved = await stripe.treasury.inboundTransfers.retrieve('ibt_123');
170
171
// List inbound transfers
172
const inboundTransfers = await stripe.treasury.inboundTransfers.list({
173
financial_account: 'fa_123',
174
limit: 20
175
});
176
177
// List transfers by status
178
const succeededTransfers = await stripe.treasury.inboundTransfers.list({
179
financial_account: 'fa_123',
180
status: 'succeeded'
181
});
182
183
// Cancel pending inbound transfer
184
const canceled = await stripe.treasury.inboundTransfers.cancel('ibt_123');
185
```
186
187
## Money Movement - Outbound
188
189
### Treasury.OutboundTransfers
190
191
Send money to external bank accounts:
192
193
```typescript { .api }
194
interface TreasuryOutboundTransfer {
195
id: string;
196
object: 'treasury.outbound_transfer';
197
financial_account: string;
198
amount: number;
199
currency: string;
200
status: 'processing' | 'posted' | 'failed' | 'canceled' | 'returned';
201
destination_payment_method: string;
202
destination_payment_method_details?: {
203
type: 'us_bank_account';
204
us_bank_account?: {
205
account_holder_type?: 'individual' | 'company';
206
account_type?: 'checking' | 'savings';
207
bank_name?: string;
208
fingerprint?: string;
209
last4?: string;
210
routing_number?: string;
211
};
212
};
213
expected_arrival_date?: number;
214
returned_details?: {
215
code?: string;
216
transaction?: string;
217
};
218
}
219
220
// Create outbound transfer to bank account
221
const outboundTransfer = await stripe.treasury.outboundTransfers.create({
222
financial_account: 'fa_123',
223
destination_payment_method: 'pm_bank_account_external',
224
amount: 25000, // $250.00
225
currency: 'usd',
226
description: 'Payout to supplier'
227
});
228
229
// Create scheduled outbound transfer
230
const scheduledTransfer = await stripe.treasury.outboundTransfers.create({
231
financial_account: 'fa_123',
232
destination_payment_method: 'pm_bank_account_payroll',
233
amount: 75000, // $750.00
234
currency: 'usd',
235
statement_descriptor: 'ACME PAYROLL',
236
metadata: {
237
type: 'payroll',
238
pay_period: '2024-01',
239
employee_count: '5'
240
}
241
});
242
243
// Retrieve outbound transfer
244
const retrieved = await stripe.treasury.outboundTransfers.retrieve('obt_123');
245
246
// List outbound transfers
247
const outboundTransfers = await stripe.treasury.outboundTransfers.list({
248
financial_account: 'fa_123',
249
limit: 20
250
});
251
252
// List transfers by date range
253
const recentTransfers = await stripe.treasury.outboundTransfers.list({
254
financial_account: 'fa_123',
255
created: {
256
gte: Math.floor(Date.now() / 1000) - 86400 * 7 // Last 7 days
257
}
258
});
259
260
// Cancel pending outbound transfer
261
const canceled = await stripe.treasury.outboundTransfers.cancel('obt_123');
262
```
263
264
### Treasury.OutboundPayments
265
266
Send ACH and wire payments to external accounts:
267
268
```typescript { .api }
269
interface TreasuryOutboundPayment {
270
id: string;
271
object: 'treasury.outbound_payment';
272
financial_account: string;
273
amount: number;
274
currency: string;
275
status: 'processing' | 'posted' | 'failed' | 'canceled' | 'returned';
276
destination_payment_method: string;
277
destination_payment_method_details?: {
278
type: 'us_bank_account';
279
us_bank_account?: {
280
account_holder_type?: 'individual' | 'company';
281
account_type?: 'checking' | 'savings';
282
bank_name?: string;
283
routing_number?: string;
284
};
285
};
286
end_user_details: {
287
present: boolean;
288
ip_address?: string;
289
};
290
returned_details?: {
291
code?: string;
292
transaction?: string;
293
};
294
}
295
296
// Create ACH outbound payment
297
const achPayment = await stripe.treasury.outboundPayments.create({
298
financial_account: 'fa_123',
299
amount: 15000, // $150.00
300
currency: 'usd',
301
destination_payment_method: 'pm_bank_account_vendor',
302
description: 'Vendor payment for services',
303
end_user_details: {
304
present: true,
305
ip_address: '192.168.1.1'
306
},
307
statement_descriptor: 'ACME VENDOR PAY'
308
});
309
310
// Create wire payment
311
const wirePayment = await stripe.treasury.outboundPayments.create({
312
financial_account: 'fa_123',
313
amount: 100000, // $1,000.00
314
currency: 'usd',
315
destination_payment_method: 'pm_bank_account_supplier',
316
description: 'Wire payment for equipment',
317
end_user_details: {
318
present: false
319
},
320
metadata: {
321
payment_type: 'wire',
322
urgency: 'high',
323
approval_id: 'approval_456'
324
}
325
});
326
327
// Retrieve outbound payment
328
const retrieved = await stripe.treasury.outboundPayments.retrieve('obp_123');
329
330
// List outbound payments
331
const payments = await stripe.treasury.outboundPayments.list({
332
financial_account: 'fa_123',
333
limit: 20
334
});
335
336
// Cancel pending outbound payment
337
const canceled = await stripe.treasury.outboundPayments.cancel('obp_123');
338
```
339
340
## Money Movement - Internal
341
342
### Treasury.ReceivedCredits
343
344
Track incoming credits to financial accounts:
345
346
```typescript { .api }
347
interface TreasuryReceivedCredit {
348
id: string;
349
object: 'treasury.received_credit';
350
financial_account: string;
351
amount: number;
352
currency: string;
353
status: 'succeeded';
354
network: 'ach' | 'us_domestic_wire' | 'stripe';
355
description?: string;
356
initiating_payment_method_details?: {
357
type: string;
358
us_bank_account?: {
359
account_holder_type?: 'individual' | 'company';
360
account_type?: 'checking' | 'savings';
361
bank_name?: string;
362
fingerprint?: string;
363
last4?: string;
364
routing_number?: string;
365
};
366
};
367
}
368
369
// Retrieve received credit
370
const credit = await stripe.treasury.receivedCredits.retrieve('rc_123');
371
372
// List received credits
373
const credits = await stripe.treasury.receivedCredits.list({
374
financial_account: 'fa_123',
375
limit: 20
376
});
377
378
// List credits by network type
379
const achCredits = await stripe.treasury.receivedCredits.list({
380
financial_account: 'fa_123',
381
network: 'ach'
382
});
383
384
// List credits by date range
385
const recentCredits = await stripe.treasury.receivedCredits.list({
386
financial_account: 'fa_123',
387
created: {
388
gte: Math.floor(Date.now() / 1000) - 86400 * 30 // Last 30 days
389
}
390
});
391
```
392
393
### Treasury.ReceivedDebits
394
395
Track outgoing debits from financial accounts:
396
397
```typescript { .api }
398
interface TreasuryReceivedDebit {
399
id: string;
400
object: 'treasury.received_debit';
401
financial_account: string;
402
amount: number;
403
currency: string;
404
status: 'succeeded';
405
network: 'ach';
406
description?: string;
407
initiating_payment_method_details?: {
408
type: string;
409
us_bank_account?: {
410
account_holder_type?: 'individual' | 'company';
411
account_type?: 'checking' | 'savings';
412
bank_name?: string;
413
fingerprint?: string;
414
last4?: string;
415
routing_number?: string;
416
};
417
};
418
}
419
420
// Retrieve received debit
421
const debit = await stripe.treasury.receivedDebits.retrieve('rd_123');
422
423
// List received debits
424
const debits = await stripe.treasury.receivedDebits.list({
425
financial_account: 'fa_123',
426
limit: 20
427
});
428
429
// List debits by status and network
430
const achDebits = await stripe.treasury.receivedDebits.list({
431
financial_account: 'fa_123',
432
network: 'ach',
433
status: 'succeeded'
434
});
435
```
436
437
## Transaction Reversals
438
439
### Treasury.CreditReversals
440
441
Reverse credit transactions:
442
443
```typescript { .api }
444
interface TreasuryCreditReversal {
445
id: string;
446
object: 'treasury.credit_reversal';
447
financial_account: string;
448
received_credit: string;
449
amount: number;
450
currency: string;
451
status: 'processing' | 'succeeded' | 'failed';
452
status_transitions: {
453
posted_at?: number;
454
};
455
network: 'ach' | 'stripe';
456
}
457
458
// Create credit reversal
459
const creditReversal = await stripe.treasury.creditReversals.create({
460
received_credit: 'rc_123'
461
});
462
463
// Create partial credit reversal
464
const partialReversal = await stripe.treasury.creditReversals.create({
465
received_credit: 'rc_456',
466
amount: 5000 // Reverse only $50 of the original credit
467
});
468
469
// Retrieve credit reversal
470
const retrieved = await stripe.treasury.creditReversals.retrieve('crev_123');
471
472
// List credit reversals
473
const reversals = await stripe.treasury.creditReversals.list({
474
financial_account: 'fa_123',
475
limit: 20
476
});
477
478
// List reversals by received credit
479
const creditReversals = await stripe.treasury.creditReversals.list({
480
received_credit: 'rc_123'
481
});
482
```
483
484
### Treasury.DebitReversals
485
486
Reverse debit transactions:
487
488
```typescript { .api }
489
interface TreasuryDebitReversal {
490
id: string;
491
object: 'treasury.debit_reversal';
492
financial_account: string;
493
received_debit: string;
494
amount: number;
495
currency: string;
496
status: 'processing' | 'succeeded' | 'failed';
497
status_transitions: {
498
completed_at?: number;
499
};
500
network: 'ach';
501
}
502
503
// Create debit reversal
504
const debitReversal = await stripe.treasury.debitReversals.create({
505
received_debit: 'rd_123'
506
});
507
508
// Create partial debit reversal
509
const partialDebitReversal = await stripe.treasury.debitReversals.create({
510
received_debit: 'rd_456',
511
amount: 3000 // Reverse only $30 of the original debit
512
});
513
514
// Retrieve debit reversal
515
const retrieved = await stripe.treasury.debitReversals.retrieve('drev_123');
516
517
// List debit reversals
518
const reversals = await stripe.treasury.debitReversals.list({
519
financial_account: 'fa_123',
520
limit: 20
521
});
522
```
523
524
## Transaction Tracking
525
526
### Treasury.Transactions
527
528
Monitor all transactions in financial accounts:
529
530
```typescript { .api }
531
interface TreasuryTransaction {
532
id: string;
533
object: 'treasury.transaction';
534
financial_account: string;
535
amount: number;
536
currency: string;
537
description: string;
538
status: 'open' | 'posted' | 'void';
539
status_transitions: {
540
posted_at?: number;
541
void_at?: number;
542
};
543
flow_type: 'credit' | 'debit';
544
flow_details: {
545
type: 'inbound_transfer' | 'outbound_transfer' | 'outbound_payment' | 'received_credit' | 'received_debit' | 'credit_reversal' | 'debit_reversal' | 'other';
546
inbound_transfer?: { id: string };
547
outbound_transfer?: { id: string };
548
outbound_payment?: { id: string };
549
received_credit?: { id: string };
550
received_debit?: { id: string };
551
credit_reversal?: { id: string };
552
debit_reversal?: { id: string };
553
};
554
}
555
556
// Retrieve transaction
557
const transaction = await stripe.treasury.transactions.retrieve('trxn_123');
558
559
// List all transactions
560
const transactions = await stripe.treasury.transactions.list({
561
financial_account: 'fa_123',
562
limit: 50
563
});
564
565
// List transactions by flow type
566
const credits = await stripe.treasury.transactions.list({
567
financial_account: 'fa_123',
568
flow_type: 'credit'
569
});
570
571
const debits = await stripe.treasury.transactions.list({
572
financial_account: 'fa_123',
573
flow_type: 'debit'
574
});
575
576
// List transactions by status
577
const postedTransactions = await stripe.treasury.transactions.list({
578
financial_account: 'fa_123',
579
status: 'posted'
580
});
581
582
// List recent transactions
583
const recentTransactions = await stripe.treasury.transactions.list({
584
financial_account: 'fa_123',
585
created: {
586
gte: Math.floor(Date.now() / 1000) - 86400 // Last 24 hours
587
}
588
});
589
```
590
591
### Treasury.TransactionEntries
592
593
Detailed transaction entry records:
594
595
```typescript { .api }
596
interface TreasuryTransactionEntry {
597
id: string;
598
object: 'treasury.transaction_entry';
599
financial_account: string;
600
transaction: string;
601
type: 'credit' | 'debit';
602
amount: number;
603
currency: string;
604
effective_at: number;
605
flow_type: string;
606
flow_details: {
607
type: string;
608
[key: string]: any;
609
};
610
}
611
612
// Retrieve transaction entry
613
const entry = await stripe.treasury.transactionEntries.retrieve('trxne_123');
614
615
// List transaction entries
616
const entries = await stripe.treasury.transactionEntries.list({
617
financial_account: 'fa_123',
618
limit: 50
619
});
620
621
// List entries by transaction
622
const transactionEntries = await stripe.treasury.transactionEntries.list({
623
transaction: 'trxn_123'
624
});
625
626
// List entries by effective date
627
const todayEntries = await stripe.treasury.transactionEntries.list({
628
financial_account: 'fa_123',
629
effective_at: {
630
gte: Math.floor(new Date().setHours(0, 0, 0, 0) / 1000)
631
}
632
});
633
```
634
635
## Test Helpers
636
637
### TestHelpers.Treasury
638
639
Simulate treasury scenarios in test mode:
640
641
```typescript { .api }
642
// Test inbound transfer scenarios
643
const succeededTransfer = await stripe.testHelpers.treasury.succeed('ibt_test_123');
644
645
const failedTransfer = await stripe.testHelpers.treasury.fail('ibt_test_123', {
646
failure_code: 'account_closed'
647
});
648
649
const returnedTransfer = await stripe.testHelpers.treasury.return('ibt_test_123', {
650
failure_code: 'account_closed'
651
});
652
653
// Test outbound transfer scenarios
654
const postedOutbound = await stripe.testHelpers.treasury.post('obt_test_123');
655
656
const failedOutbound = await stripe.testHelpers.treasury.fail('obt_test_123', {
657
failure_code: 'insufficient_funds'
658
});
659
660
const returnedOutbound = await stripe.testHelpers.treasury.return('obt_test_123', {
661
failure_code: 'no_account'
662
});
663
664
// Test outbound payment scenarios
665
const postedPayment = await stripe.testHelpers.treasury.post('obp_test_123');
666
667
const failedPayment = await stripe.testHelpers.treasury.fail('obp_test_123', {
668
failure_code: 'generic_decline'
669
});
670
671
const returnedPayment = await stripe.testHelpers.treasury.return('obp_test_123', {
672
failure_code: 'credit_entry_refused_by_receiver'
673
});
674
675
// Create test received credits and debits
676
const testCredit = await stripe.testHelpers.treasury.createReceivedCredit({
677
financial_account: 'fa_test_123',
678
network: 'ach',
679
amount: 10000,
680
currency: 'usd',
681
description: 'Test incoming ACH credit'
682
});
683
684
const testDebit = await stripe.testHelpers.treasury.createReceivedDebit({
685
financial_account: 'fa_test_123',
686
network: 'ach',
687
amount: 5000,
688
currency: 'usd',
689
description: 'Test outgoing ACH debit'
690
});
691
```
692
693
## Integration Examples
694
695
### Multi-tenant Financial Accounts
696
697
```typescript { .api }
698
// Create separate financial accounts for marketplace participants
699
async function createMerchantAccount(merchantId: string) {
700
const financialAccount = await stripe.treasury.financialAccounts.create({
701
supported_currencies: ['usd'],
702
features: {
703
inbound_transfers: { ach: { requested: true } },
704
outbound_transfers: { ach: { requested: true } },
705
intra_stripe_flows: { requested: true }
706
},
707
metadata: {
708
merchant_id: merchantId,
709
account_type: 'merchant_settlement'
710
}
711
});
712
713
return financialAccount;
714
}
715
716
// Transfer funds between accounts
717
async function transferToMerchant(
718
sourceAccountId: string,
719
destinationAccountId: string,
720
amount: number
721
) {
722
// First move to platform account
723
const outbound = await stripe.treasury.outboundTransfers.create({
724
financial_account: sourceAccountId,
725
destination_payment_method: 'ba_platform_account',
726
amount: amount,
727
currency: 'usd'
728
});
729
730
// Then to merchant account
731
const inbound = await stripe.treasury.inboundTransfers.create({
732
financial_account: destinationAccountId,
733
origin_payment_method: 'ba_platform_account',
734
amount: amount,
735
currency: 'usd'
736
});
737
738
return { outbound, inbound };
739
}
740
```
741
742
### Automated Payroll System
743
744
```typescript { .api }
745
// Process payroll payments
746
async function processPayroll(payrollData: PayrollEntry[]) {
747
const results = [];
748
749
for (const entry of payrollData) {
750
try {
751
const payment = await stripe.treasury.outboundPayments.create({
752
financial_account: 'fa_payroll_account',
753
amount: entry.netPay,
754
currency: 'usd',
755
destination_payment_method: entry.employeeBankAccount,
756
description: `Payroll for ${entry.employeeName}`,
757
end_user_details: {
758
present: false
759
},
760
metadata: {
761
employee_id: entry.employeeId,
762
pay_period: entry.payPeriod,
763
gross_pay: entry.grossPay.toString(),
764
deductions: entry.deductions.toString()
765
}
766
});
767
768
results.push({ success: true, payment, employee: entry.employeeName });
769
} catch (error) {
770
results.push({ success: false, error, employee: entry.employeeName });
771
}
772
}
773
774
return results;
775
}
776
```
777
778
### Real-time Balance Monitoring
779
780
```typescript { .api }
781
// Monitor account balance and trigger alerts
782
async function monitorAccountBalance(financialAccountId: string) {
783
const account = await stripe.treasury.financialAccounts.retrieve(financialAccountId);
784
const balance = account.balance.usd;
785
786
if (balance.available < 100000) { // Less than $1,000
787
await sendLowBalanceAlert({
788
accountId: financialAccountId,
789
availableBalance: balance.available,
790
pendingBalance: balance.pending
791
});
792
}
793
794
// Get recent transactions for analysis
795
const transactions = await stripe.treasury.transactions.list({
796
financial_account: financialAccountId,
797
created: {
798
gte: Math.floor(Date.now() / 1000) - 86400 // Last 24 hours
799
}
800
});
801
802
return {
803
balance,
804
recentTransactions: transactions.data,
805
alertSent: balance.available < 100000
806
};
807
}
808
```
809
810
Stripe Treasury provides a comprehensive financial infrastructure that enables platforms to offer sophisticated banking and money movement capabilities with full regulatory compliance and real-time transaction monitoring.