or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

Files

docs

billing.mdcheckout.mdconfiguration.mdcore-resources.mdidentity.mdindex.mdissuing.mdradar.mdsubscriptions.mdtax.mdterminal.mdtreasury.mdwebhooks.md

treasury.mddocs/

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.