Using Treasury to set up financial accounts and cards
Homebox is a fictitious vertical SaaS that builds software for home-services companies like HVAC technicians, cleaners, and plumbers. Homebox begins its Treasury integration by setting up a Treasury financial account and creating payment cards. To see how Homebox moves money to and from external bank accounts, see the Using Treasury to move money example integration.
Platform onboarding
Homebox is already a Stripe platform with Payments and Connect enabled. Homebox uses Custom connected accounts, and those connected accounts already have the card_payments capability enabled.
Adding capabilities
To use Treasury and Issuing services, Homebox needs to request the additional treasury and card_issuing capabilities for the platform’s users. The connected accounts must then onboard before Stripe can create a Treasury financial account for the user.
To use ACH transfers with Treasury, Homebox also needs to request the us_bank_account_ach_payments capability.
To request the treasury, card_issuing, and us_bank_account_ach_payments capabilities, Homebox makes a request to the Accounts API.
To use Hosted Onboarding, Homebox makes a call to Account Links to retrieve a URL their customer can use to submit onboarding information for the Treasury financial account.
The response includes a URL the customer uses to access the application, which must be done before the link expires.
{ "object": "account_link", "created": 1612927106, "expires_at": 1612927406, "url": "https://connect.stripe.com/setup/s/iCtLfmYb2tEU" }
Homebox listens for the account.updated webhook to confirm the following fields and capabilities on the connected account:
{ "object": { "id": "{{CONNECTED_ACCOUNT_ID}}", "object": "account", "capabilities": { "card_payments": "active", "treasury": "active", "card_issuing": "active", // Only appears if requesting the `card_issuing` capability. "us_bank_account_ach_payments": "active", // Only appears if requesting the `us_bank_account_ach_payments` capability. }, ... } }
Creating a FinancialAccount
After Stripe adds the treasury capability to an account, Homebox can create the FinancialAccount object for the account. To do so, Homebox calls FinancialAccounts and requests the Features the company wants to provide.
The response confirms the account is processing. After complete and all relevant features are active, Homebox gets a confirmation from their treasury.financial_account.features_status_updated webhook listener.
{ "object": "treasury.financial_account", "created": 1612927106, "id": "{{FINANCIAL_ACCOUNT_ID}}", "country": "US", "supported_currencies": ["usd"], "financial_addresses": [ // This field is empty until the "financial_addresses.aba" feature becomes active { "type": "aba", "supported_networks": ["ach", "us_domestic_wire"], "aba": { "account_number_last4": "7890", // Use the expand[] parameter to view the `account_number` field hidden by default "account_number": "1234567890", "routing_number": "000000001", "bank_name": "Bank of Earth" } } ], "livemode": true, // State machine: // open - the account is ready to be used // closed - the account is closed "status": "open", "status_details": { // `closed` is null if financial account is not closed "closed": { // List of one or more reasons why the FinancialAccount was closed: // - account_rejected // - closed_by_platform // - other "reasons": [], } }, active_features: ["card_issuing"], pending_features: ["deposit_insurance", "financial_addresses.aba", "outbound_payments.ach", "us_domestic_wire", "inbound_transfers.ach", "outbound_transfers.ach", "outbound_transfers.us_domestic_wire"], restricted_features: [], "features": { "object": "treasury.financial_account_features", "card_issuing": { "status": "active", "status_details": [], "access": "active", }, "deposit_insurance": { "requested": true, "status": "pending", // Becomes "active" once the Treasury financial account is set up "status_details": [{"code": "activating", "resolution": nil}], }, "financial_addresses": { "aba": { "requested": true, "status": "pending", // Becomes "active" once the Treasury financial account is set up "status_details": [{"code": "activating", "resolution": nil}], }, }, "outbound_payments": { "ach": { "requested": true, "status": "pending", // Becomes "active" once the Treasury financial account is set up "status_details": [{"code": "activating", "resolution": nil}], }, }, "us_domestic_wire": { "requested": true, "status": "pending", // Becomes "active" once the Treasury financial account is set up "status_details": [{"code": "activating", "resolution": nil}], }, "inbound_transfers": { "ach": { "requested": true, "status": "pending", // Becomes "active" once the Treasury financial account is set up "status_details": [{"code": "activating", "resolution": nil}], }, }, "outbound_transfers": { "ach": { "requested": true, "status": "pending", // Becomes "active" once the Treasury financial account is set up "status_details": [{"code": "activating", "resolution": nil}], }, }, "outbound_payments": { "ach": { "requested": true, "status": "pending", // Becomes "active" once the Treasury financial account is set up "status_details": [{"code": "activating", "resolution": nil}], }, }, "outbound_transfers": { "us_domestic_wire": { "requested": true, "status": "pending", // Becomes "active" once the Treasury financial account is set up "status_details": [{"code": "activating", "resolution": nil}], }, }, "platform_restrictions": { "inbound_flows": "unrestricted", "outbound_flows": "unrestricted" }, "metadata": {}, ... }
Creating a payment cardholder
Before Homebox can create cards for Treasury financial accounts, it needs to create cardholders. The cardholders in this example are plumbers who utilize Homebox services and own the connected accounts on the platform.
The response confirms the cardholder is created.
{ "id": "{{CARDHOLDER_ID}}", "object": "issuing.cardholder", "billing": { "address": { "city": "\"San Francisco\"", "country": "US", "line1": "\"1234 Main Street\"", "postal_code": "94111", "state": "CA" } }, "created": 1623803705, "email": "jenny@example.com", "livemode": false, "metadata": {}, "name": "Jenny Bath Remodeling", "phone_number": "+18008675309", "requirements": { "disabled_reason": "under_review", "past_due": [] }, "spending_controls": { "allowed_categories": [], "blocked_categories": [], "spending_limits": [], }, "status": "active", "type": "company" }
Creating payment cards
Now that the connected account has a FinancialAccount object associated with it and an available cardholder, Homebox can create a payment card using the FinancialAccount balance as the card’s available balance.
The response confirms the card is issued.
{ "id": "{{CARD_ID}}", "object": "issuing.card", "cardholder": { "id": "{{CARDHOLDER_ID}}", "object": "issuing.cardholder", "billing": { "address": { "city": "San Francisco", "country": "US", "line1": "123 Main Street", "line2": null, "postal_code": "94111", "state": "CA" } }, ... }, "created": 1643293629, "currency": "usd", "exp_month": 12, "exp_year": 2024, "last4": "0930", "livemode": false, ... }