
## Accounting implementation

So you’re implementing accounting! This guide is intended for For Benefit Of (FBO) account users that are implementing commingled accounts. You'll want to have an engineer and an accountant for this project (or someone comfortable wearing both hats).

Accounting can cover a few different functions within an organization so for the sake of clarity we’re going to be explicit about each function:

- Bookkeeping
- Reconciliation
- Analysis
- Preparing financial statements

This guide solely covers Bookkeeping and Reconciliation.

### Bookkeeping

Bookkeeping is generating the individual debits and credits.

#### Identifying data sources

To start, you should identify which sources of information you’ll use to generate your financial records. This is both the hardest and the most important part of accounting.

For the most part, it’ll be helpful if these are external sources: the ad network summaries you receive, your payment processor reporting, your supplier invoices or receipts. External sources are usually well specified and subject to more formal change processes. They're also easier to point to during an audit.

One source that you should be careful not to use is your bank statement. While this may seem counterintuitive, it is important to save bank statements for Reconciliation.

### Debits and credits

Next, you should think about how these records should generate debits and credits. For example, when you receive a record of a sale from your payment processor, you might want to:

- Debit your payment processor
- Credit your drop shipper
- Credit your Profit and Loss account

When your payment processor transfers funds to you, you’ll then want to:

- Credit your payment processor
- Debit your bank account

And when you pay your drop-shipper, you’ll want to:

- Debit your drop-shipper
- Credit your bank account

Within each of these sets, all transactions are dated the same and so your books should balance at all times. Often timing differences are used to explain unbalanced books. If your accounts are set up correctly this should never happen. Unbalanced books due to timing differences indicate that you’re missing an account.

The transactions' date will be when you reasonably expect the real-world action to occur. For example, if your payment processor says they’ll transfer funds to you on Friday and they’ve been reasonably reliable in the past, future-date the transaction for Friday.

Your rules about how debits and credits are generated from external records are where much of your accounting policy is set and enforced. In fact, the code that generates the debits and credits, including its version control history, can be a great point of discussion with auditors who are trying to understand your accounting policies.

### Accounts

Now that you’ve defined your debits and credits, you know what accounts you need. One note: you’ll oftentimes be tempted to introduce a sub-account (drop-shipper EU sales for example) which isn’t strictly needed for Bookkeeping, but is needed for Analysis. Rather than introducing unnecessary accounts, we’d strongly encourage you to use tags. The reasons for using tags rather than sub-accounts are:

- Decouple Bookkeeping from Analysis
- Give yourself flexibility in the future to change the subclassifications
- Not limit yourself to a strict hierarchy when you want a transaction to have multiple classifications

OK, now how do you test if things look right on your side? Reconciliation!

### Reconciliation

Reconciliation is comparing independent sources for consistency. While Increase will reconcile your bank account balances to your bookkeeping balances, you’ll want to do the same. If there are inconsistencies, you’ll need to address them.

### Identifying data sources

Choosing which data sources to use for Bookkeeping and which to keep for Reconciliation can be non-obvious. Ideally you want the sources to be independent and from different providers. For example, it's better to reconcile a payment provider's daily reporting with a bank account rather than with the payment provider's monthly reporting.

Reconciliation can be the most intensive component of accounting because it requires a deep understanding of what third-parties are sending. It can require understanding things like timing cut-offs, currency rate sources, aggregation arrangements, and rounding conventions.

### {One, Many}-to-{one, many}

The cleanest reconciliations are one-to-one at the most granular level. Unfortunately that isn't always possible and so you might have to rely on one-to-many record matching.

An example is when your payment processor bundles together many payments into one transfer to you but solely gives you information on the payments and not on the bundled transfer.

The messiest reconciliations are many-to-many. These are rare and it's oftentimes a sign that a better understanding of the data sources is needed.

### Inventoried accounts

For some accounts, the balance is fungible: transactions increase and decrease the balance but you don't have to care about how the transactions relate to one another. For other accounts, this isn't the case.

An example where you need to track how outs relate to ins is with any account representing food or other spoilable inventory. If inventory isn't moved along before it spoils, it needs to be written off.

A less obvious example is when you have only a 30 day window to raise an issue with a payment processor who failed to transfer a specific payment to you. Inventoried accounts are a stricter version of first-in-first-out accounting because transactions aren't necessarily even fungible by date or price.

For inventoried accounts, you'll need a record identifier that's shared by both sources. If that's not possible, you'll need to use heuristics for matching. For example, your payment processor and bank might not have a shared identifier for transfers to you, but you can heuristically match the date, amount, and statement descriptor.

### Breakages

You should be looking for missing, additional, and mis-matched transactions when reconciling. Any discovered mis-matches will, unfortunately, likely require manual intervention.

### Other topics and questions

#### How do I handle a For Benefit Of (FBO) account?

The first step is to have a pseudo entity for the For Benefit Of account program. This is separate to your corporate entity. The For Benefit Of account program pseudo entity doesn’t have a Profit and Loss account; it must immediately pass Profit and Loss to other entities. It also doesn’t have equity.

#### Should I backfill data?

You’ll likely be asked if it’s necessary to backfill accounting data or whether you should just set initial balances and go forward. While this is ultimately up to you, oftentimes trying to solve a bundle of messy present-day issues is much easier when you look back at history and solve them one by one as they come up over time. Also, you’ll forever be tempted to attribute any confusing account balance to the initial balance that was set rather than digging further. Going back to history might seem like paying a lot of penance (especially if you weren’t at the organization when the messiness, or lack of recording happened), but it really can be worth it.

#### Separating clean and messy flows

You'll likely run into the difficulty when reconciling your bank account that some flows are well reported and can be reconciled easily while others are more difficult. An example of a clean flow is funds being transferred from your payment processor where you have advance reporting of what amounts will be transferred and when. An example of a messy flow is ATM cash withdrawals for petty cash.

It can be a good idea to completely separate these two kinds of activities into two different bank accounts: one which is expected to have items that don't easily reconcile and one that's expected to reconcile every day.

In the same way, you'll probably want separate corporate cards for not-separately reported versus separately reported transactions.

#### Where to start

While you might agree that these concepts seem worthwhile, you might now be asking where to start. There's a simple answer: start by programmatically reconciling your cash, or at least the flows that are reconcilable.

You'll do this by first identifying the records reported from partners that relate to cash movements. In Excel, manually generate the expected debits and credits for your bank accounts from these records and then compare the generated records to the actual bank account. When these records are consistently matching, move onto the next partner until you're able to reconcile all cashflows.

When you can reconcile ~all cashflows, then move on to non-cash flows.


Accounting


## ACH

Automated Clearing House (ACH) is the dominant low-value transfer mechanism in the US. ACH typically refers to the Federal Reserve’s [FedACH network](https://www.frbservices.org/financial-services/ach) which implements the rules maintained by [Nacha](https://nacha.org/) (formerly stylized as the National Automated Clearing House Association, NACHA).

ACH is an asynchronous network; files containing batches of transfers are sent from originating financial institutions to the Federal Reserve which re-batches the files for onward transmission to receiving financial institutions. FedACH settles within the financial institutions’ Federal Reserve accounts.

ACH supports both credit and debit origination; you can pull and push money. The timeframes have been shortening in the last ten years. FedACH now operates [three same-day windows](https://www.frbservices.org/resources/resource-centers/same-day-ach/fedach-processing-schedule.html). FedACH also operates [six non same-day windows](https://www.frbservices.org/resources/resource-centers/same-day-ach/fedach-processing-schedule.html).

An ACH transfer includes mandatory details of the account number, routing number, and amount. There are optional parameters of the recipient’s name and identifying number. Explicitly, most financial institutions don’t enforce that the recipient name on the transfer matches the account holder name.

### Returns

ACH transfers can be returned. Common return reasons are that the account number isn’t recognized, the account has insufficient funds, and that the account holder states the transfer is unauthorized. Transfer returns can roughly be divided into administrative return (the account number isn't recognized, for example) and unauthorized returns (the account holder stated the transfer wasn’t authorized). Nacha mandates that [administrative returns must be limited to 15% and unauthorized returns must be limited to 0.5%](https://www.nacha.org/rules/ach-network-risk-and-enforcement-topics). Both are calculated on monthly count.

Returns can be correlated with originating transfers by using the date, amount, account number, routing number, and the trace number. Trace numbers are 15 digits but with only eight digits of entropy (as the leading eight identify the original financial institution). Trace numbers need to be unique in a Nacha file and monotonically increase. For any reasonably large institution, it’s usually not possible to uniquely rely on trace numbers for reconciling returns.

### Disputes

Explicitly, FedACH doesn’t intermediate disputes. This is different to the card networks. A transfer recipient can state a transfer is unauthorized and the receiving bank will return it. For corporate accounts this period is two business days. For consumer accounts, this is sixty days. Nacha recommends using non-ACH related dispute resolution mechanisms like contacting the account holder, collections agencies, or courts.

To reduce unauthorized returns, Nacha recommends (and in some cases requires) validation of account and routing number details.

### Account validations

To validation account details you have two options:

- Use a service like Plaid or Finicity, where an account holder provides their bank login details and the platform ~synchronously scrapes the bank’s website.

- Send the account holder micro-deposits and have them confirm the amounts.

There are older methods like collecting an image of a voided check or using [confirmation notes](https://increase.com/documentation/api#ach-prenotifications) but they’re less used in modern integrations.

### Reversals and other conventions

Nacha also has a number of conventions that have reached varying degrees of codification. One is reversals — reclaiming funds from an erroneous transfer. For reversals, Nacha requires all fields are the same except for the `company_entry_description` which must be `REVERSAL`. Importantly, reversals aren’t a network primitive; they’re regular transfers and therefore can be returned.

Other Nacha conventions with varying degrees of formality are child support payments, tax payments, and corporate trade exchange data.

### Non-financial messages

ACH supports some non-financial messages. One is the confirmation note used for accounting and routing number validation. Another is a Notification of Change. Notifications of Change are optionally sent by receiving depository institutions to communicate that although a transfer has been accepted, in the future, updated details should be used.

### Schedule

The Federal Reserve’s FedACH schedule is here:

https://www.frbservices.org/resources/resource-centers/same-day-ach/fedach-processing-schedule.html

Increase submits for every window and we can accept transfers up to an hour before the cut-offs.

### Technical implementation

Nacha’s message format is a fixed-width flat file containing batches of transfer entries. Nacha’s specification is here:

https://achdevguide.nacha.org/ach-file-overview

Many financial institutions implement ACH by allowing clients submit Nacha’s file format through SFTP servers. Submission to the Federal Reserve runs similarly but uses an IBM product, Connect:Direct. FedACH responds with a custom-formatted acknowledgement file within 15 minutes. (There are escalation channels if a file hasn’t been acknowledged in that timeframe.) Most financial institutions similarly operate an acknowledgement mechanism.

### Operating an ACH integration

A common frustration with ACH is that there’s no transfer receipt notification method. As a transfer originator, you have no way to definitely know if or when a transfer has arrived to a recipient’s account.

Some depository institutions allow account holders to maintain an allowlist of companies that can debit their account. This is done by referencing the Company ID. In particular, if you’ll be debiting businesses, you’ll likely want them to register your Company ID with their financial institution.

ACH transfers have many [structured parameters](https://increase.com/documentation/api#ach-transfer-object) like the `company_name`, `company_discretionary_data`, `individual_name`, and `individual_id`. The specifics of how these are serialized to a transaction description shown to a recipient vary by bank.

Typical operational issues you’ll run into are that Nacha’s file form is ASCII. If you’re allowing UTF-8 data submission you’ll want to flatten it. You’ll also want to exclude client entered data containing things like newline characters.

Not all financial institutions preserve the trace numbers you submit. You’ll want to understand if yours does as it makes a difference to how you’ll correlate returns.

Many financial institutions will fund your ACH transactions by aggregating your daily files and batches possible by transfer effective date. Understanding your bank’s aggregation method is necessary for you to reconcile the transfer instructions you’ve submitted to the cash in your bank account.

While not common, there are data quality issues with FedACH. In particular, the network itself doesn’t store the state of a transfer. Therefore it’s possible for a receiving depository institution to return a transfer multiple times, for example. It’s also possible for them to include the incorrect details on a return.



## Versioning and backwards compatibility

The Increase API is currently unversioned, meaning we'll never make backwards-incompatible changes such as removing a field from the API without reaching out to you first. We're of course continually making backwards-compatible changes to the API. Examples of things we do **not** consider breaking include:

- Adding new API resources.
- Adding new optional request parameters to existing API methods.
- Adding new properties to existing API responses. We will occasionally move response fields in the API, and will continue to return the existing field in its previous location, while removing it from our [API Reference](/documentation/api).
- Changing the order of properties in existing API responses.
- Changing the length or format of opaque strings, such as object IDs, error messages, and other human-readable strings. This includes adding or removing fixed prefixes on object IDs, which is done as a convenience but shouldn't be interpreted semantically or relied on. Strings that are marked as `const` or `enum` in our API Reference will not change.
- Adding new [Event](/documentation/api#events) categories.


Backwards compatibility


## Digital wallets

Increase's cards can be added to digital wallet apps like Google Pay and Apple Pay. The customer will see a card image and icon of your brand when they make purchases using tap-to-pay checkout options in stores. There are some rules and recommendations around how to format your digital card.

### Card Art image

The main card artwork must be a PNG image of 1536 x 969 pixels. This landscape image should look like a card but not include any features that only exist on physical cards like an image of the EMV card chip, an account number, or expiration date. The image should have square corners because the app platform will round the corners differently to match their design standards.

### Icon image

The icon image must be a PNG image of 100 x 100 pixels. It will be used for mobile notifications related to the card. The icon should be the primary brand associated with the card in the wallet.

### Text color

The text color parameter allows you to control the color of the last four digits that are dynamically added to the card art image. This parameter is three numbers between 0 and 255, representing the red, green and blue color channels. This is the same as the `rgb(_, _, _)` color definition in CSS.

### Example

This is an example of how a main image (top) and icon image (middle left) will appear in the Apple Pay digital wallet. The text color is black, or `rgb(0, 0, 0)`.

![Apple Pay Example](/images/apple_pay.png)


Digital card art


## Changelog

### Week of 2023-06-05

- You can now view the raw return code (`raw_return_reason_code` ) on a returned [ACH Transfer](/documentation/api#ach-transfer-object) including a brief description (`return_reason_code`).
- Dashboard now surfaces additional information in object lists including Transactions, Cards, Account Numbers, and Transfers lists.

### Week of 2023-05-29

- You can now view the interest rate earned by an Account in the [Accounts API](/documentation/api#accounts).
- Post Office Boxes are no longer accepted as valid Entity addresses, with the exception of Army Post Office (APO) and Fleet Post Office (FPO) addresses.

### Week of 2023-05-22

- If you have more than one [Program](/documentation/api#programs), you'll now need to specify a `program_id` when [creating a new Account](/documentation/api#create-an-account).
- You can now create [Programs in Sandbox](/documentation/api#create-a-program).

### Week of 2023-05-15

- New Entity views in Dashboard let you review and edit your information and give you access to quick actions, all in one place.
- With Programs, platforms can now report compliance data (such as metrics, complaints, and third-party risk reports) directly in Dashboard.

### Week of 2023-04-17

- You can now view detailed timelines for transfers in Dashboard.
- The new `pending_reviewing` status on a transfer indicates when a transfer is under review by Increase.
- The [ACH Transfer API](/documentation/api#ach-transfer-object) now includes multiple `notifications_of_change`, if they are sent by the receiving bank.

### Week of 2023-04-10

- You can now override webhook Event Subscriptions for Real-Time Decisions in the sandbox by specifying an `event_subscription_id` in the [simulation](/documentation/api#simulate-an-authorization-on-a-card). This is helpful when multiple developers are building in the same sandbox environment.
- Our new [Balance Lookups API](/documentation/api#balance-lookups) enables you to see the available and current balance of your accounts. This will soon replace the balance attribute on [Accounts](/documentation/api#account-object).
- Our new beta [Exports API](/documentation/api#exports) enables you to download your Increase data in batches. Check out the [Exports documentation](/documentation/exports) for more information.
- You can now update your Entity's address in Dashboard.

### Week of 2023-04-03

- We've written new guides to common [Networks](/documentation), such as ACH, Check 21, and Fedwire. [Let us know](mailto:support@increase.com) what networks you'd like us to write about next!
- You can now simulate an [Interest Payment](/documentation/api#simulate-an-interest-payment-to-your-account) to your Account.
- Transfer templates are now deprecated in favor of [External Accounts](/documentation/api#external-accounts).

### Week of 2023-03-27

- We've introduced [Programs](/documentation/api#programs) to guide the compliance and commercial terms for Accounts. You can also view your [Programs in Dashboard](https://dashboard.increase.com/settings/programs).
- `beneficiary_address_line1` is now a required field on [outbound wires](/documentation/api#create-a-wire-transfer) for transfers made through Blue Ridge Bank.
- We've launched [Java and Kotlin Software Development Kits](/documentation/software-development-kits).

### Week of 2023-03-13

- We've launched [Python and Node Software Development Kits](/documentation/software-development-kits)! We'd love for you to try them out and [give us feedback](mailto:support@increase.com) as you build your integration. Go, Java, and Kotlin are coming soon. Let us know if there's anothing language you'd like us to support.

### Week of 2023-03-06

- You can now require everyone in your Team to setup two-factor authentication on your [Team's settings page](https://dashboard.increase.com/settings/team).
- You can also view events related to your Team's security changes, such as password resets and two-factor authentication changes, on your [Team's settings page](https://dashboard.increase.com/settings/team).

### Week of 2023-02-27

- You can now create and revoke API keys in Dashboard.
- You can now simulate returning check deposits using the [Simulations API](/documentation/api#return-a-sandbox-check-deposit).
- You can now access the accompanying message that is printed on a [CheckTransfer](/documentation/api#check-transfers)'s letter.

### Week of 2023-02-20

- You can now return inbound ACH Transfers with our new [returns API](/documentation/api#inbound-ach-transfer-returns).

### Week of 2023-02-13

- We've made usability changes to Dashboard, including a refreshed Account page.

### Week of 2023-02-06

- We have a [new landing page](https://increase.com/)!
- We now include Visa specific fields in [card authorization requests](/documentation/api#real-time-decision-object) that can be used to differentiate between online and offline purchases.
- You can now receive and respond to inbound wire drawdown requests through our [API](/documentation/api#inbound-wire-drawdown-request-object).

### Week of 2023-01-30

- We now support notes on [CheckTransfers](/documentation/api#check-transfers) that will be printed on the letter included with the check.
- You can now schedule transfers with any interval in Dashboard.

### Week of 2023-01-23

- You can now link External Accounts using Stripe's Financial Connections through Dashboard.

### Week of 2023-01-16

- We now have a [status page](https://status.increase.com/)!
- You can now view images of deposited CheckTransfers in Dashboard and the [CheckTransfer API](/documentation/api#check-transfers).
- You can now simulate depositing a CheckTransfer with our [Simulations API](/documentation/api#deposit-a-sandbox-check-transfer).
- `beneficiary_name` is now a required field on [outbound wires](/documentation/api#create-a-wire-transfer).

### Week of 2023-01-09

- An Account's available balance, which represents the balance less any open Pending Transactions, is now available via the [Account API](/documentation/api#account-object).
- You are now able to download documents, such as IRS Form 1099-INT through our new [Documents API](/documentation/api#documents).

### Week of 2023-01-03

- You can now approve and require approval on specific transfers, rather than all or nothing, through our API.
- The [ACH Transfer API](/documentation/api#ach-transfer-object) now includes the time the transfer was submitted to FedACH, as well as beneficiary information.
- The [Wire Transfer API](/documentation/api#wire-transfer-object) now includes the time the transfer was submitted to Fedwire, as well as beneficiary information.
- Simulations now include richer data for [ACH Transfers](/documentation/api#simulate-an-ach-transfer-to-your-account), [Wire Transfers](/documentation/api#simulate-a-wire-transfer-to-your-account), and [Real Time Payments](/documentation/api#simulate-a-real-time-payments-transfer-to-your-account).
- You can now filter Transactions with specific source categories using the [Transactions List API](/documentation/api#list-transactions).

### Week of 2022-12-12

- Increase is now generally available and no longer requires an invite code to sign up! [Start building today](https://dashboard.increase.com/signup)!
- Our Real Time Payments API, built directly on top of The Clearing House network, now supports sending Requests for Payment. [Reach out](mailto:support@increase.com) if you'd like to try it out!
- You can now specify a return address on outbound checks with our [Check Transfers API](/documentation/api#create-a-check-transfer).
- Card settlement transactions now surface the presentment amount and currency.
- Transaction CSV exports from Dashboard now include the transaction type.
- The [Real Time Decisions API](/documentation/api#real-time-decisions) now includes the Card Profile ID if it was set by the Real Time Decision.

### Week of 2022-12-05

- You can now receive webhook events for Digital Wallet Tokens using the [Events API](/documentation/api#event-object).
- You can now simulate refunding a card transaction using the [Simulations API](/documentation/api#simulate-a-refund-on-a-card).
- Templates are being deprecated in favor of [External Accounts](/documentation/api#external-accounts), which are now available in Dashboard. Existing Templates will continue to work as expected, but you won't be able to create new ones.
- [Check Transfers](/documentation/api#check-transfer-object) now have a returned status to let you know if there was an issue with the receiver.

### Week of 2022-11-28

- You can now simulate card disputes using the [Simulations API](/documentation/api#simulates-advancing-the-state-of-a-card-dispute).
- You can now upload supplemental documents for your entity using the [Entity API](/documentation/api#create-a-supplemental-document-for-an-entity).
- You can now retrieve digital wallet tokens that are created when a user adds their Card to Apple Pay or Google Pay using the [Digital Wallet Tokens API](/documentation/api#digital-wallet-tokens).
- We now include additional originator information, such as name and address, on outbound wires.

### Week of 2022-11-14

- We have a new [platform integration guide](/documentation/platform-implementation) to help you get started when building your business with a compliance forward mindset!
- You can now use SMS to verify a card when adding it to a digital wallet using our [Cards API](/documentation/api#cards).
- You can now check if a routing number supports ACH, wire, and Real Time Payment transfers using our [Routing Number API](/documentation/api#routing-numbers).

### Week of 2022-10-31

- Receiving inbound Real Time Payments is now generally available.

### Week of 2022-10-24

- You can now specify an Entity's relationship to your group using the [Entities API](/documentation/api#entities).
- You can now create beneficial owners in the [Entities API](/documentation/api#entities) with out a passport.

### Week of 2022-10-10

- You can now add Increase cards to digital wallets such as Apple and Google Pay! If you'd like to do this for cards you issue to your users, we also support custom artwork and branding. [Reach out](mailto:support@increase.com) if you'd like to use this.
- Our updated [Check Deposits API](/documentation/api#check-deposits) give you access to details of a parsed check, such as the account number printed on the check.
- Users can now be re-added to a Group.

### Week of 2022-10-03

- Our new [Real-Time Decisions API](/documentation/api#real-time-decisions) lets you take actions in real-time for events such as card authorizations.
- Our new [Wire Drawdown Requests API](/documentation/api#wire-drawdown-requests) lets you request that someone else send you a wire transfer.
- There's a new [Entities API](/documentation/api#entities) that includes richer information about your legal entities.

### Week of 2022-09-05

- Check numbers are now available in Dashboard and the [Check Transfers API](/documentation/api#check-transfers).
- You can now [simulate inbound Real Time Payments](/documentation/api#simulate-a-real-time-payments-transfer-to-your-account) to your account. [Reach out](mailto:support@increase.com) if you'd like to use Real Time Payments in production.
- Our new company creation flow improves onboarding and entity creation.

### Week of 2022-08-29

- You can now filter transactions by direction and transaction type in Dashboard.

### Week of 2022-08-15

- Our new [External Accounts API](/documentation/api#external-accounts) lets you store external account details for reuse.
- You can now redirect cashback and interest to a specific account. [Reach out](mailto:support@increase.com) if you'd like to do this.

### Week of 2022-08-08

- You can now specify the `amount` in [card settlement simulations](/documentation/api#create-a-card-settlement).

### Week of 2022-08-01

- Our new Cards webhook, which enables you to make real time decisions in the authorization flow, is in private beta! [Reach out](mailto:support@increase.com) if you'd like to try it out!

- Cards now appear in search.

### Week of 2022-07-25

- [API logs](https://dashboard.increase.com/developers/logs) are now viewable under Developers.

### Week of 2022-07-18

- You can now validate routing numbers against our new [Routing Number API](/documentation/api#routing-numbers).

- Our new Real Time Payments API, built directly on top of The Clearing House network, is in private beta. [Reach out](mailto:support@increase.com) if you'd like to try it out!

- [Account Statements](/documentation/api#account-statements) are now available in the API.

- [Entities](https://dashboard.increase.com/settings/entities) now have their own tab under Settings.

- [Events](https://dashboard.increase.com/developers/events) are now viewable under Developers.

### Week of 2022-06-20

- You can download a PDF of wire routing details for an Account Number from Dashboard.

- If you need to stop payment on a Check Transfer, you may now [do so](/documentation/api#request-a-stop-payment-on-a-check-transfer) via the API.

### Week of 2022-06-06

- Our new Cards API, built directly on top of the Visa network, is now in public beta. [Try it out!](/documentation/api#cards)

### Week of 2022-05-30

- You can now [deposit checks](/documentation/api#check-deposits) in the API and Dashboard.

### Week of 2022-05-23

- You can now [simulate](/documentation/api#simulations) certain types of activity, such as inbound ACH transfers, in the sandbox.
- [OAuth applications](/documentation/oauth) are now generally available - you can make applications to work with data for other Increase users.

### Week of 2022-05-16

- Files (both sent by you to Increase, and generated by Increase for you) are now exposed in the API. You can listen to `file.created` webhooks to know when Increase generates certain Files (such as statement PDFs) for you.

- There are no longer limits on Account Number or Card creation in the sandbox.

### Week of 2022-05-09

- Webhooks now have more predictable payloads and work in the sandbox. There's a guide on how they work [here](/documentation/webhooks).

- There's now an [OpenAPI schema](/documentation/api#openapi) for our API.

- This changelog now exists!


Changelog


## Check 21

[Check 21](https://www.frbservices.org/financial-services/check) is the Federal Reserve’s electronic check clearing service. It’s an asynchronous network where batches of check images are sent to the Federal Reserve, sorted, and transmitted onwards to payers’ depository institutions. Check 21 settles within the financial institutions’ Federal Reserve accounts.

Check 21 submissions require images of the front and back of the check. Details like the amount, routing number, and account number are parsed and included in the submissions. Although much of the parsing can be automated, check processing is labor intensive.

As an alternative to Check 21, ACH supports converting checks to ACH transfers. These check conversions are limited to checks under USD 25k and can’t be used for checks with auxiliary on-us data (which is typically a check number).

### Returns

If a payer’s financial institution declines to accept a check (for, for example, insufficient funds or the account being closed), they can return it through Check 21.

### Disputes

Explicitly, Check 21 doesn’t intermediate disputes. This is different to the card networks.

### Schedule

The Federal Reserve’s Check 21 schedule is here:

https://www.frbservices.org/financial-services/check/check21.html

### Technical implementation

Check 21 uses a public format. The specifications are here:

https://www.frbservices.org/binaries/content/assets/crsocms/financial-services/check/setup/frb-x937-standards-reference.pdf

The format mixes ASCII and in-lined TIFF images.

### Operating a Check 21 integration

Check 21 doesn't have a positive feedback mechanism. You don't know if a check has been accepted by the payer's bank. You solely know if you haven't received a return yet.

There are specialized check scanners which scan the front and back of checks and parse the [Magnetic Ink Character Recognition (MICR)](https://en.wikipedia.org/wiki/Magnetic_ink_character_recognition) values. These can be useful if you’re accepting physical checks at scale.

Check 21 also supports Remote Deposit Capture (RDC). This allows account holders to submit images of checks.

While most returns are received through the regular return item channel, you’ll also want to watch for adjustments. They’re far more manual.


Check 21


## Compliance requirements

If you move money on behalf of your clients, this document is for you! This includes those opening For Benefit Of (FBO) accounts or those opening accounts on behalf of their underlying users. This does not include OAuth users. These users are agents of the entity they are moving funds on behalf of.

### Onboarding

For benefit of (FBO) account holders are Program Managers of the bank. You are required to maintain a full compliance program. This includes, but is not limited to, Bank Secrecy Act compliance and any applicable consumer protection regulation.

We’ll provide you with a compliance questionnaire and a document checklist. After you’ve submitted the documentation, we’ll assess your business’s risk. We might have some follow-up requests.

If you’re at the beginning of your journey, we’d strongly advise working with a consulting firm to help pull together a robust compliance program.

### Ongoing requirements

#### Customer information files

You collect and verify the information about your customers. You must share that with us, however. To do so, you create an `Entity`. You can differentiate between your customers’ entities, your entities, and any other kind of entity using the `relationship` property. In particular:

- Affiliated entities are entities you own and control.
- Unaffiliated entities are your customers’ entities. An unaffiliated entity must be on file for every client onboarded.
- Informational entities are when you’re submitting details to us but there’s no relationship or service provided by the bank to your customer. This is rarely used.

#### Transaction monitoring and suspicious activity reporting

As part of your compliance program, you’ll monitor transactions for signs of money laundering, terrorist financing, and other illicit financial activity. As you’re monitoring transactions and reviewing customer identification documents you’ll come across unusual activity. When you do, you must review it, validate that it is not expected behavior, and submit the details to [unusual-activity@increase.com](mailto:unusual-activity@increase.com).

We’ll acknowledge we’ve received your email but we won’t provide feedback or follow up unless we need help. This is a Bank Secrecy Act / Anti-Money Laundering requirement.

#### Standard Periodic Program Review

- Quarterly, we will discuss program updates and new risks with your Chief Compliance Officer.
- Annually, we will review your refreshed documents and any changes to your policies or procedures.
- We will periodically audit your identity verification procedures as needed.


Compliance


## Data Dictionary

Increase's [API documentation](/documentation/api) references several repeated concepts like dates, currencies, and countries.

### Dates

Dates are represented in the [ISO-8601](https://www.iso.org/iso-8601-date-and-time-format.html) date format, which is `YYYY-MM-DD`. For example, January 31, 2023 is `2023-01-31`.

### Times

Times are represented in the [ISO-8601](https://www.iso.org/iso-8601-date-and-time-format.html) time format at the UTC offset, which is `YYYY-MM-DD'T'HH:mm:ss'Z'`. For example, January 31, 2023 at 7:05:22 Pacific Time is `2023-02-01T03:05:22Z`.

### Object Identifiers

Object Identifiers are strings referencing objects and concepts within Increase's systems. They are always strings and are prepended with the type of object they refer to. For example, `account_123abc000` is a potential Account ID.

### Currencies

Increase will occasionally reference foreign currencies, for example, when an Increase Card is used at an international merchant. Currencies are represented in the Increase API as integers, using the minor unit of the currency. As an example, $12.34 will be represented by the integer `1234` and the symbol `USD`. Some common currencies are listed below.

---

| Symbol | Name            | Minor Unit Factor |
| ------ | --------------- | ----------------- |
| CAD    | Canadian Dollar | 2                 |
| CHF    | Swiss Franc     | 2                 |
| EUR    | Euro            | 2                 |
| GBP    | British Pound   | 2                 |
| JPY    | Japanese Yen    | 0                 |
| USD    | US Dollar       | 2                 |

### Countries

Increase references countries by their [ISO-3611-1](https://www.iso.org/iso-3166-country-codes.html) alpha-2 code, reproduced below.

---

| Code | Country Name                                         |
| ---- | ---------------------------------------------------- |
| AF   | Afghanistan                                          |
| AX   | Åland Islands                                        |
| AL   | Albania                                              |
| DZ   | Algeria                                              |
| AS   | American Samoa                                       |
| AD   | Andorra                                              |
| AO   | Angola                                               |
| AI   | Anguilla                                             |
| AQ   | Antarctica                                           |
| AG   | Antigua and Barbuda                                  |
| AR   | Argentina                                            |
| AM   | Armenia                                              |
| AW   | Aruba                                                |
| AU   | Australia                                            |
| AT   | Austria                                              |
| AZ   | Azerbaijan                                           |
| BS   | Bahamas                                              |
| BH   | Bahrain                                              |
| BD   | Bangladesh                                           |
| BB   | Barbados                                             |
| BY   | Belarus                                              |
| BE   | Belgium                                              |
| BZ   | Belize                                               |
| BJ   | Benin                                                |
| BM   | Bermuda                                              |
| BT   | Bhutan                                               |
| BO   | Bolivia (Plurinational State of)                     |
| BQ   | Bonaire, Sint Eustatius and Saba                     |
| BA   | Bosnia and Herzegovina                               |
| BW   | Botswana                                             |
| BV   | Bouvet Island                                        |
| BR   | Brazil                                               |
| IO   | British Indian Ocean Territory                       |
| BN   | Brunei Darussalam                                    |
| BG   | Bulgaria                                             |
| BF   | Burkina Faso                                         |
| BI   | Burundi                                              |
| CV   | Cabo Verde                                           |
| KH   | Cambodia                                             |
| CM   | Cameroon                                             |
| CA   | Canada                                               |
| KY   | Cayman Islands                                       |
| CF   | Central African Republic                             |
| TD   | Chad                                                 |
| CL   | Chile                                                |
| CN   | China                                                |
| CX   | Christmas Island                                     |
| CC   | Cocos (Keeling) Islands                              |
| CO   | Colombia                                             |
| KM   | Comoros                                              |
| CG   | Congo                                                |
| CD   | Congo (Democratic Republic of the)                   |
| CK   | Cook Islands                                         |
| CR   | Costa Rica                                           |
| CI   | Côte d'Ivoire                                        |
| HR   | Croatia                                              |
| CU   | Cuba                                                 |
| CW   | Curaçao                                              |
| CY   | Cyprus                                               |
| CZ   | Czechia                                              |
| DK   | Denmark                                              |
| DJ   | Djibouti                                             |
| DM   | Dominica                                             |
| DO   | Dominican Republic                                   |
| EC   | Ecuador                                              |
| EG   | Egypt                                                |
| SV   | El Salvador                                          |
| GQ   | Equatorial Guinea                                    |
| ER   | Eritrea                                              |
| EE   | Estonia                                              |
| ET   | Ethiopia                                             |
| FK   | Falkland Islands (Malvinas)                          |
| FO   | Faroe Islands                                        |
| FJ   | Fiji                                                 |
| FI   | Finland                                              |
| FR   | France                                               |
| GF   | French Guiana                                        |
| PF   | French Polynesia                                     |
| TF   | French Southern Territories                          |
| GA   | Gabon                                                |
| GM   | Gambia                                               |
| GE   | Georgia                                              |
| DE   | Germany                                              |
| GH   | Ghana                                                |
| GI   | Gibraltar                                            |
| GR   | Greece                                               |
| GL   | Greenland                                            |
| GD   | Grenada                                              |
| GP   | Guadeloupe                                           |
| GU   | Guam                                                 |
| GT   | Guatemala                                            |
| GG   | Guernsey                                             |
| GN   | Guinea                                               |
| GW   | Guinea-Bissau                                        |
| GY   | Guyana                                               |
| HT   | Haiti                                                |
| HM   | Heard Island and McDonald Islands                    |
| VA   | Holy See                                             |
| HN   | Honduras                                             |
| HK   | Hong Kong                                            |
| HU   | Hungary                                              |
| IS   | Iceland                                              |
| IN   | India                                                |
| ID   | Indonesia                                            |
| IR   | Iran (Islamic Republic of)                           |
| IQ   | Iraq                                                 |
| IE   | Ireland                                              |
| IM   | Isle of Man                                          |
| IL   | Israel                                               |
| IT   | Italy                                                |
| JM   | Jamaica                                              |
| JP   | Japan                                                |
| JE   | Jersey                                               |
| JO   | Jordan                                               |
| KZ   | Kazakhstan                                           |
| KE   | Kenya                                                |
| KI   | Kiribati                                             |
| KP   | Korea (Democratic People's Republic of)              |
| KR   | Korea (Republic of)                                  |
| KW   | Kuwait                                               |
| KG   | Kyrgyzstan                                           |
| LA   | Lao People's Democratic Republic                     |
| LV   | Latvia                                               |
| LB   | Lebanon                                              |
| LS   | Lesotho                                              |
| LR   | Liberia                                              |
| LY   | Libya                                                |
| LI   | Liechtenstein                                        |
| LT   | Lithuania                                            |
| LU   | Luxembourg                                           |
| MO   | Macao                                                |
| MK   | Macedonia (the former Yugoslav Republic of)          |
| MG   | Madagascar                                           |
| MW   | Malawi                                               |
| MY   | Malaysia                                             |
| MV   | Maldives                                             |
| ML   | Mali                                                 |
| MT   | Malta                                                |
| MH   | Marshall Islands                                     |
| MQ   | Martinique                                           |
| MR   | Mauritania                                           |
| MU   | Mauritius                                            |
| YT   | Mayotte                                              |
| MX   | Mexico                                               |
| FM   | Micronesia (Federated States of)                     |
| MD   | Moldova (Republic of)                                |
| MC   | Monaco                                               |
| MN   | Mongolia                                             |
| ME   | Montenegro                                           |
| MS   | Montserrat                                           |
| MA   | Morocco                                              |
| MZ   | Mozambique                                           |
| MM   | Myanmar                                              |
| NA   | Namibia                                              |
| NR   | Nauru                                                |
| NP   | Nepal                                                |
| NL   | Netherlands                                          |
| NC   | New Caledonia                                        |
| NZ   | New Zealand                                          |
| NI   | Nicaragua                                            |
| NE   | Niger                                                |
| NG   | Nigeria                                              |
| NU   | Niue                                                 |
| NF   | Norfolk Island                                       |
| MP   | Northern Mariana Islands                             |
| NO   | Norway                                               |
| OM   | Oman                                                 |
| PK   | Pakistan                                             |
| PW   | Palau                                                |
| PS   | Palestine, State of                                  |
| PA   | Panama                                               |
| PG   | Papua New Guinea                                     |
| PY   | Paraguay                                             |
| PE   | Peru                                                 |
| PH   | Philippines                                          |
| PN   | Pitcairn                                             |
| PL   | Poland                                               |
| PT   | Portugal                                             |
| PR   | Puerto Rico                                          |
| QA   | Qatar                                                |
| RE   | Réunion                                              |
| RO   | Romania                                              |
| RU   | Russian Federation                                   |
| RW   | Rwanda                                               |
| BL   | Saint Barthélemy                                     |
| SH   | Saint Helena, Ascension and Tristan da Cunha         |
| KN   | Saint Kitts and Nevis                                |
| LC   | Saint Lucia                                          |
| MF   | Saint Martin (French part)                           |
| PM   | Saint Pierre and Miquelon                            |
| VC   | Saint Vincent and the Grenadines                     |
| WS   | Samoa                                                |
| SM   | San Marino                                           |
| ST   | Sao Tome and Principe                                |
| SA   | Saudi Arabia                                         |
| SN   | Senegal                                              |
| RS   | Serbia                                               |
| SC   | Seychelles                                           |
| SL   | Sierra Leone                                         |
| SG   | Singapore                                            |
| SX   | Sint Maarten (Dutch part)                            |
| SK   | Slovakia                                             |
| SI   | Slovenia                                             |
| SB   | Solomon Islands                                      |
| SO   | Somalia                                              |
| ZA   | South Africa                                         |
| GS   | South Georgia and the South Sandwich Islands         |
| SS   | South Sudan                                          |
| ES   | Spain                                                |
| LK   | Sri Lanka                                            |
| SD   | Sudan                                                |
| SR   | Suriname                                             |
| SJ   | Svalbard and Jan Mayen                               |
| SZ   | Swaziland                                            |
| SE   | Sweden                                               |
| CH   | Switzerland                                          |
| SY   | Syrian Arab Republic                                 |
| TW   | Taiwan                                               |
| TJ   | Tajikistan                                           |
| TZ   | Tanzania, United Republic of                         |
| TH   | Thailand                                             |
| TL   | Timor-Leste                                          |
| TG   | Togo                                                 |
| TK   | Tokelau                                              |
| TO   | Tonga                                                |
| TT   | Trinidad and Tobago                                  |
| TN   | Tunisia                                              |
| TR   | Turkey                                               |
| TM   | Turkmenistan                                         |
| TC   | Turks and Caicos Islands                             |
| TV   | Tuvalu                                               |
| UG   | Uganda                                               |
| UA   | Ukraine                                              |
| AE   | United Arab Emirates                                 |
| GB   | United Kingdom of Great Britain and Northern Ireland |
| US   | United States of America                             |
| UM   | United States Minor Outlying Islands                 |
| UY   | Uruguay                                              |
| UZ   | Uzbekistan                                           |
| VU   | Vanuatu                                              |
| VE   | Venezuela (Bolivarian Republic of)                   |
| VN   | Viet Nam                                             |
| VG   | Virgin Islands (British)                             |
| VI   | Virgin Islands (U.S.)                                |
| WF   | Wallis and Futuna                                    |
| EH   | Western Sahara                                       |
| YE   | Yemen                                                |
| ZM   | Zambia                                               |
| ZW   | Zimbabwe                                             |


Data dictionary


## Exports

The Exports API allows you to export large amounts of data from your Increase account. This is useful if you want to analyze your account data in other tools or migrate to another service.

## Making an Export

You can create an Export in the API or dashboard. As preparing the Export can take a long time depending on what's requested, this process is asynchronous. When you create the Export, it will have `status: pending`. When it's ready, it will transition to `status: complete` and the `file_id` and `file_download_url` attributes will be set on the Export API object. We'll send you a webhook for this and optionally notify you via email.

## Types of Export

You can indicate what type of Export you'd like via the `category` API parameter. Right now the only publicly supported export type is `transaction_csv`, which exports your transactions and some of their metadata (optionally limited to a specified time range or account ID). We're working on more export types, but please [let us know](mailto://support@increase.com) if there's a field or type that would be helpful to you!

## Backwards compatibility

Exports are currently in beta, and we'll occasionally add or remove columns to our reports depending on user feedback. This might change the absolute ordering of columns. If you're automatically ingesting these CSVs in code, we recommend you not rely on column ordering and instead use the column headers to know how to parse each column.


Exports


## Fedwire

Fedwire is the dominant high-value transfer mechanism in the US. Fedwire is the Federal Reserve’s real-time gross settlement network. It has two variants: funds, for USD transfers, and securities, for transfers of [a limited group of securities](https://www.frbservices.org/financial-services/securities).

Fedwire is a ~synchronous network; the Federal Reserve — and in particular, the Federal Reserve Bank of New York — receives a wire and ~immediately debits the sending financial institution’s account and credits the receiving financial institution’s account.

Traditionally, wires have been labor intensive. There’s an assumption that there’ll be a manual exception process. As such, the messaging format allows a wide range of inputs. For example, a receiving account number isn’t strictly required by the specification.

### Reversals

When a receiving financial institution cannot allocate or otherwise decides to not accept a transfer, it sends a reversal.

A sender can request that a wire is reversed. The receiving financial institution has no obligation to honor the request, however.

### Drawdown requests

Although Fedwire doesn’t support pulling funds, there’s a network-level primitive to request payment. This is called a [drawdown request](https://increase.com/documentation/api#wire-drawdown-requests). There’s also a drawdown request payment network primitive which allows a transfer to be correlated with a drawdown request.

Support for drawdown requests is typically limited to corporate accounts and there’s usually setup required by the account holder. Common use-cases are for intra-company money movement or regular automated settlement. Settlement to Visa, for example, can be coordinated by drawdown request.

### Non-financial messages

Fedwire supports a messaging network. It’s typically used for wire department to wire department communication. Because wire processing can still be very manual, the messaging network is often used to request additional information.

### Schedule

The Fedwire schedule is here:

https://www.frbservices.org/resources/financial-services/wires/operating-hours.html

Notably, although Fedwire closes at 7pm ET, it re-opens at 9pm ET.

In practice, Fedwire can extend the operating hours. This typically happens in times of stress.

### Technical implementation

Fedwire uses a proprietary message format that’s comprised of tags. In 2024, Fedwire intends to move to ISO 20022.

Fedwire uses an IBM queuing product, MQ.

### Operating a wire integration

One notable detail about wire operations is how manual they are at many institutions. Many financial institutions assume that wires will have manual intervention and therefore aren’t as strict as they might be with details like account numbers.

Fedwire can be used for settling USD legs of non-US transfers. Fedwire therefore supports passing through a SWIFT Business Identifier Code (BIC).


Fedwire


## Information Security

This document outlines the areas we want you to consider. Which policies and procedures are right for your situation will depend on a number of factors, like your company size or whether or not you're storing consumer data.

In addition to asking for your information security policy, we interview new companies about their security posture. We understand that companies are making tradeoffs, and expect you to be able to defend your choices.

### Network Access Control

If you maintain internet-connected servers, you'll want to consider:

- What measures you have in place protecting your database or servers from unauthorized access
- What third parties can connect to your system
- Your management of secrets, keys, certificates

### Network diagram

We typically ask for a network diagram. Your network diagram should include:

- Network boundaries around your systems, clients, and partner systems
- All third parties which access to your system or your system depends on
- You should break out gateways and load balancers from API servers from databases

### Monitoring and alerting

You should monitor your production systems.

Web application firewalls are one tool; these are commonly bundled with Application Load Balancers.

You should consider alerting on security events, like failed sign-ins.

You should consider formalizing an incident response plan.

### Storing sensitive data

If users are trusting you with sensitive data, it's incumbent on you to take that trust seriously.

The Gramm-Leach-Bliley act specifically defines nonpublic personal information to include names, addresses, phone numbers, social security numbers, income, credit score, and information obtained through Internet collection devices (i.e., cookies).

You should consider what data you're storing and which systems have access to it.

Your databases likely have disk-level encryption. You'll want to consider column-level encryption for nonpublic personal information.

You should consider whether to allow your employees console access to production machines, and what kind of logging to put in place.

If your employees can impersonate users in your system, you should consider logging or placing limitations.

### Device management

Employee devices are a significant attack vector.

You should consider centralizing provisioning of those devices. Mobile device management is one tool.

You should consider formalizing policies around third-party software, password management, disk encryption, administrator privileges.

You should consider whether employee access to internal systems should happen over VPN.

You should consider asking employees to sign Confidentiality Agreements to protect customer information, as a condition of employment.

### Change management

You should carefully scrutinize your deployment pipeline.

You should consider automated testing and staging environments.

You should consider requiring approval for deployment, and which employees may grant such approval.

You should consider tracking infrastructure in code, and subjecting changes to infrastructure to a similar review process.

### User authentication

You should consider protecting user accounts, even against users' own lax security posture.

This section is most relevant to consumer applications.

You should consider multi-factor authentication.

You should have constraints on acceptable passwords. You should consider avoiding storing passwords yourself. If you do, you should learn about best practices.

You should consider tracking IP addresses associated with authentication events. In the right circumstances, you may consider allowlisting customer IP addresses.


Information Security


## Building an OAuth Application

If you're building an application for others to use with their Increase accounts, our API supports [OAuth 2.0](https://oauth.net/2/). The first step is to [create an OAuth application](https://dashboard.increase.com/applications/oauths) in the dashboard. You will set a `name` and a `redirect_url` and receive a `client_id` and a `client_secret`.

## The authorization flow

At a high level, onboarding users to your OAuth application looks like this:

1. The user begins on your site, where they're redirected to Increase's site and prompted to grant you access to their Increase data.
2. Upon granting access, the user is redirected back to your site with a short-lived OAuth code.
3. You use our API to exchange this code for a long-lived access token, which you use to authenticate to the API on subsequent requests on behalf of the user.

### Request access from your user

To request access from your user, build an OAuth authorization URL using the `client_id` and `client_secret` you received when creating your application and direct your user to it. You must also specify a `scope` of either `read_only` or `read_write` which is the permissions the user will be prompted to grant your application. You may also optionally include a `state` value which will be included when the user is redirected back to your site after approving access and can be used for tracking your user’s identity and preventing Cross-Site Request Forgeries (CSRFs). This [IETF draft article](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-security-topics#section-4.7) provides a good overview of the latter.

Your URL should be of the format:

```none
https://increase.com/oauth/authorization?client_id={client_id}&state={state}&scope={scope}
```

### Claim an Access Token

When a user grants you access they'll be redirected to `{redirect_url}?code={code}&state={state}`. You should then use our API to exchange this `code` for an access token. The `code` expires after 60 seconds. You’ll also need to provide your application’s `client_id` and `client_secret`, as well as a parameter `grant_type` with the constant value of `authorization_code`.

```curl
curl -X "POST" \
  --url "https://api.increase.com/oauth/tokens" \
  -H "Authorization: Bearer ${INCREASE_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d $'{
    "code": "CODE",
    "client_id": "CLIENT_ID",
    "client_secret": "CLIENT_SECRET",
    "grant_type": "authorization_code"
  }'
```

This will return an access token that looks like this:

```json
{
  "access_token": "RI5vGMbBv8UPqUhk0YHZ45hG2XpEDzDp",
  "token_type": "bearer"
}
```

You’ll need to store this access token in your application.

### Access the API on behalf of your user

Use the returned `access_token` in place of your own API key to access the user's account, and then make API requests as you normally would. If your application’s `scope` is `read_only`, only GET requests will be allowed.

```curl
curl \
  --url "https://api.increase.com/accounts" \
  -H 'Authorization: Bearer ACCESS_TOKEN'
```

### Create a sandbox token

If you need to access your user’s sandbox environment, you can create a separate sandbox access token to do so. You use your own sandbox token when making this request, and provide the `access_token` you received at the end of the authorization flow for the `production_token` parameter. You’ll also need to include the parameter `grant_type` with the constant value of `production_token`.

```curl
curl -X "POST" \
  --url "https://sandbox.increase.com/oauth/tokens" \
  -H 'Authorization: Bearer YOUR_SANDBOX_API_KEY' \
  -H 'Content-Type: application/json' \
  -d $'{
    "production_token": "ACCESS_TOKEN",
    "grant_type": "production_token"
  }'
```

## Webhooks

If you have an [Event Subscription](/documentation/api#event-subscriptions) configured, you’ll receive webhooks for activity on your own platform’s account as well as for activity on your connected accounts. You can distinguish the latter via the presence of the `Increase-Group-Id` header on the webhook request, which will be set to the ID of the Group the activity occurred on. Note that your Event Subscription should belong to your platform’s account, not your connected user’s account (in other words, you should create it with your normal API key, not an OAuth access token).

## Managing connected accounts

You can list all of the groups that have connected your application using the [OAuth Connections API](/documentation/api#oauth-connections). Note that this API, like the Event Subscriptions API, should be accessed with your platform’s API key and not with a user’s OAuth access token.

You can retrieve information for an individual connected account by calling the [Retrieve Group API](https://increase.com/documentation/api#groups) with a user’s OAuth access token.

Users can deauthorize your application at any time in their dashboard. When this happens, we’ll send your application an `oauth_connection.deactivated` webhook. Subsequent API calls with that user’s access token will return an `invalid_api_key_error` response with HTTP status code 401.


OAuth


## Platform Onboarding

At Increase, we believe you are in the best position to run your own compliance program. You know your business best, so you can judge what type of customer and transaction looks suspicious. This puts you in the driver’s seat when it comes to onboarding customers and monitoring transactions.

You are required to maintain a full compliance program. This includes, but is not limited to, Bank Secrecy Act compliance and any applicable consumer protection regulation.

If you’re at the beginning of your journey, we strongly advise working with a consulting firm to help pull together a robust compliance program. We’re happy to recommend firms to work with. If you have questions, please reach out to us at support@increase.com.

To better understand your business and compliance program, we’ll collect information on your business model and team, Bank Secrecy Act / Anti Money Laundering program, compliance and risk management, data & security, and consumer protection policies, if applicable. We may have some follow-up requests.

### Business Experience and Qualifications

We assess your company's legal and operational status, reviewing your business registration, licenses, and ownership structure. This ensures your organization has a solid foundation and meets the necessary criteria for providing financial services.

| Document                           | What we're looking for                                                                                                                                                              |
| ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Onboarding Questionnaire           | You can download the questionnaire [here](https://docs.google.com/spreadsheets/d/11VNqijwhdsU8KdK8eE8nN53iXFbYDpuz/edit?usp=sharing&ouid=111362576131596114684&rtpof=true&sd=true). |
| Manage biographies                 | Brief overview of your management team.                                                                                                                                             |
| Employee overview                  | Total headcount, background check of key team members.                                                                                                                              |
| Corporate organizational documents | Articles of incorporation.                                                                                                                                                          |
| Investor overview                  | Overview of your product, team and business model.                                                                                                                                  |

### Financial Health

We evaluate your platform's financial stability, focusing on aspects such as balance sheets, cash flow statements, and credit ratings. This allows us to confirm that your business is financially sound and able to manage potential risks.

| Document             | What we're looking for                                                                                                                                  |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Financial statements | If you have been in operation for under 2 years, you may not have audited financial statements. Please provide your financial projections in this case. |
| Audit report         | Report that evaluates your internal controls.                                                                                                           |
| Volume forecast      | Monthly origination volume (ACH credits, ACH debits, wires, card spend), expected balances, number of loans if applicable.                              |
| Funds flow diagram   | Diagram of your flow of funds showing the full transaction from beginning to end, including clearly labeled Increase accounts.                          |

### Risk Management and Controls

We examine your risk management policies and practices, including how you identify, measure, monitor, and control various risks associated with your financial services. This ensures your platform is prepared to mitigate potential issues and maintain a secure environment for users.

| Document                 | What we're looking for                                                                                                             |
| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- |
| Program risk assessment  | Risk assessment should evaluate your specific business model and identify vulnerabilities that are managed by subsequent policies. |
| Vendor management policy | Policy that outlines the requirements to conduct vendor onboarding due diligence and ongoing monitoring.                           |
| Vendor list              | List of vendors with risk ratings according to your Vendor Management Policy.                                                      |

### Regulatory Compliance

We review your adherence to relevant regulations and laws, including anti-money laundering (AML) and know-your-customer (KYC) procedures. This helps guarantee that your platform operates legally and ethically within the financial services sector.

| Document                         | What we're looking for                                                                                                                                                                                                                                                    |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Anti-money laundering policy     | Policy that outlines your approach to Know Your Customer (KYC) / Know Your Business (KYB), sanctions screening and transaction monitoring. You should ensure to designate a Bank Secrecy Act / Anti Money Laundering Officer in your policy.                              |
| Anti-money laundering procedures | Procedures that outline how you will operationalize your Bank Secrecy Act / Anti Money Laundering policy. You should name the third party vendor used for KYC/KYB and sanctions screening, and detail if you\'ll handle transaction monitoring in-house or with a vendor. |
| Compliance management policy     | Governance document for your compliance program that covers oversight, testing/monitoring, training.                                                                                                                                                                      |
| Complaints policy                | Policy that details process for handling complaints in an effective and fair manner.                                                                                                                                                                                      |
| End user terms of service        | Terms of service you share with your end users.                                                                                                                                                                                                                           |

### Information Security

We assess your platform's security measures for safeguarding sensitive data, such as encryption techniques, access control, and vulnerability management. This enables us to ensure your users' information is protected from unauthorized access and potential cyber threats.

| Document                    | What we're looking for                                                                                                                                                                                                   |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Information security policy | Policy that includes information on data management & security, controls related to physical and environmental security, detection and handling of security incidents, and other topics related to information security. |
| Network diagram             | Detailed systems diagram and accompanying write-up that shows your system architecture, data segmentation, system access controls, and connections to third parties.                                                     |

### Operational Resilience

We analyze your platform's ability to maintain critical functions during adverse events, such as system failures, natural disasters, or cyber attacks. This evaluation ensures that your platform can swiftly recover from disruptions and continue providing reliable services to users.

| Document                 | What we're looking for                                                                                                                                                                                                                                                                                  |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Business continuity plan | Document that outlines controls in place to mitigate failures such as system downtime or loss of data.                                                                                                                                                                                                  |
| Penetration test report  | Document that details the findings of a security assessment conducted using penetration testing, if you have completed this; otherwise a timeline of when you intend to complete this.                                                                                                                  |
| Insurance policies       | Certificate of insurance. Coverage must be in place by launch. Requirements: Commercial Liability $1mm/$2mm, Workers Compensation based on number of employees, Professional Liability $3mm minimum but up to $5mm dependant on number of users, Cyber Liability $3mm/$5mm, Crime/3rd party crime $3mm. |


Platform Onboarding


## Ongoing Oversight

### Customer Information Files

You will collect and verify information about your customers. You must share that information with us. To do so, you will create an `Entity`.

Note that if you are opening bank titled for benefit of (FBO) accounts, those accounts should be owned by one Entity in the name and tax identification number of one of our bank partners. The Entity you create for your end customer will not own any accounts.

### Transaction monitoring

As part of your compliance program, you’ll monitor transactions for signs of money laundering, terrorist financing, and other illicit financial activity. As you are monitoring transactions and reviewing customer identification documents, you may come across unusual activity. When you do, you must review it, validate that it is not expected behavior, and submit the details to unusual-activity@increase.com.

We’ll acknowledge we’ve received your email but we won’t provide feedback or follow up unless we need help. This is a Bank Secrecy Act / Anti-Money Laundering requirement.

### Ledgering

You will need to maintain a ledger to track and reconcile funds belonging to each end user. You can use Increase, your own in-house technology or a third party to maintain the ledger. If you’re not using Increase we’ll ask you submit the results at the end of each day through our Bookkeeping API.

### Reserve account

If you anticipate originating ACH debits, we will work with you to establish and maintain a Reserve Account.

### Standard periodic program review

- Annually, we will review your refreshed documents and any changes to your policies or procedures.
- Annually, we will review your website, terms & conditions and fees.
- Quarterly, we will discuss program updates and new risks with your Chief Compliance Officer.
- We will periodically audit your identity verification procedures as needed.
- We will periodically request audited financial statements, if applicable.
- If you receive any notice or criticism from a regulatory authority, you should alert Increase at support@increase.com and send a copy of the communication within 3 business days of receiving the complaint.

## Additional requirements for consumer businesses

### Marketing material review

We will review any initial marketing materials that reference the bank and/or payment services. We will work with you on proper guidelines for language used in future marketing materials. Any significant changes to your marketing materials may require additional review.

### Customer service

You will be responsible for providing customer service related to your program. You should establish and maintain a toll free number, and disclose this number in your terms and conditions.

You will perform quality monitoring of your customer service functions. We may periodically conduct call monitoring to assess your customer service quality.

### Complaints tracking

In accordance to your Complaints Management Policy, you will track complaints and handle resolutions. You will share a monthly report of your complaints tracking with Increase.


Ongoing Oversight


## How to build a payments company

If you’re looking to pull money from one party to pay another, you’re probably building a payments company.

## Basic funds flow

Most payments companies have the same basic funds flow: funds are pulled from the customer’s account, land in your Increase account, and then are pushed into the payee’s account.

Alternatively, payers can push funds to you.

Example 1: Zippy Payroll Inc

Zippy Payroll helps employers pay their employees. Here’s a basic funds flow where Zippy debits an employer for $100 and pays 4 employees $25 each.

![Payroll Diagram](/images/payroll_diagram.png)

Example 2: BillPayments R Us

BillPayments R Us helps companies pay their vendors. Here’s a basic funds flow where BillPayments R Us 1/ debits $750 from their customer and 2/ sends it on to Vendor Web Services.

![Bill Pay Diagram](/images/bill_payments_diagram.png)

## Onboarding customers

As a payments company, you’ll need to know your customers.

With Increase, you’re in charge of collecting and validating your customers’ information. When you’re getting set up, we’ll review your process. We’ll work with you to make sure everything looks reasonable.

You’ll [pass your customers’ information to us](/documentation/api#create-an-entity). We will periodically double-check your results, but you won’t need to block on our review.

## Collecting funds from customers

Now it’s time to move some money! When collecting funds from your customers, you’ll have a few options:

- Pull the money.

ACH debits pull funds from customers’ accounts. You‘ll initiate ACH debits by creating a transfer in the [API](/documentation/api#ach-transfers) or in the Dashboard. We like money movement to be speedy so we default to same day ACH whenever possible.

ACH debits can fail. The most common reason they fail is that the account and routing numbers are incorrect. They can also fail if you use an incorrect [Standard Entry Class (SEC) code](/documentation/api#create-an-ach-transfer) or your customer hasn’t added your ACH Company ID to their allowlist. The best way to know if transfers will succeed is testing! Try debiting $1 before you try debiting $10,000.

ACH debits can also be returned if there aren’t sufficient funds in the account or if the account holder says the transfer is unauthorized. This creates credit risk for your business. How much credit exposure you take is your business decision. We manage our credit exposure to you by having you keep a balance with us.

- Have your customer push the money.

Your customers can push funds to you by ACH or wire. While these require a bit more legwork from your user, it eliminates the credit risk associated with ACH debits.

Having a user push funds to you also often creates a reconciliation challenge. That’s why we’d strongly recommend creating separate [Accounts](/documentation/api#accounts) or [Account Numbers](/documentation/api#account-numbers) for each customer. This way you’ll always know that funds coming into account `12345` are from Customer Inc. because they are the only ones you gave that account number to.

Wire drawdowns, also called ‘reverse wires’, are requests for the receiving bank to send funds. Wires are irreversible. Wire drawdowns are most often used for large business to business transfers.

## Ledgering

As you’re moving money, you’ll want to track who’s owed what. We also need to know for Federal Deposit Insurance Corporation coverage. You can do this in one of two ways:

**1. Open separate accounts**

The easiest way to track customer’s money is to create customer-specific Accounts. Importantly, the Accounts won’t necessarily be owned by your customer if you’re using the For Benefit Of model. You’ll simply use the structure to keep track of customer funds.

**2. Pass ledger data**

If you're maintaining your own ledger, you can pass us the data through our bookkeeping API.

## Paying out to vendors

Once it’s time to send money out to your vendors, you’ll almost certainly want to push the funds. This means creating an [ACH Transfer](/documentation/api#create-an-ach-transfer) or [Wire Transfer](/documentation/api#create-a-wire-transfer).

That’s it! Bills are paid and your customers are happy.

## Regulation

No matter what product you’re building, if you’re moving money on behalf of customers you’ll want to talk to a lawyer.

One useful place to start may be getting some advice on how state and federal Money Transmission regulations may apply to you.

## Risk and compliance

Moving money typically comes with added risk and compliance requirements. Check out [our platform user compliance guide](/documentation/onboarding).

If you have any questions or want to get started, don’t hesitate to ping us at [sales@increase.com](mailto:sales@increase.com). We can’t wait to see what you build!


How to build a payments company


## Platform implementation guide

If you’re moving your customer’s money, you likely already know about some of the [compliance requirements](https://increase.com/documentation/onboarding). This guide addresses how to implement a few of these requirements.

You’ll need to:

- Know whose money you’re moving.
- Keep track of what money belongs to each of your customers.

You’ll also need to tell us these details.

Setting up your accounts correctly makes this easier.

First you’ll need to determine what account structure is right for you and who will legally own the accounts.

### Account structure

Typically we recommend spinning up an individual account for each of your customers. This prevents the need to keep a separate ledger. It also gives you maximum flexibility for account ownership. [Account creation](https://increase.com/documentation/api#accounts) is synchronous. There is no limit on the number of accounts you can create.

Alternatively you can have one commingled account. You’ll need to keep track of whose funds are whose.

In either structure, you can also create unique [account numbers](https://increase.com/documentation/api#account-numbers). These are particularly useful for tracking inbound payments.

### Account ownership

Every account is owned by an [entity](https://increase.com/documentation/api#entities).

When moving money on behalf of customers, there are three common options:

- Option 1: Accounts are owned by your own entity.
- Option 2: Accounts are owned by the bank’s entity for the benefit (FBO) of your customers.
- Option 3: Entities are created for individual customers, each of which owns their own account.

Options 1 and 2 work with either account structure. Option 3 only works if you create individual accounts.

In order for you to own the account, option 1, you’ll need to ensure you have the appropriate regulatory permissions. You’ll definitely want to chat with your legal team on this.

We typically recommend option 3, though there are lots of factors to consider here. We’re always happy to think through them with you.

Snapshot:

|                                                                        | Individual Accounts | Commingled Accounts |
| ---------------------------------------------------------------------- | ------------------- | ------------------- |
| You own accounts                                                       | Y                   | Y                   |
| Accounts are owned by the bank for the benefit (FBO) of your customers | Y                   | Y                   |
| Individual customers own accounts                                      | Y                   | N                   |

Okay! Now that we know how you’ll be structuring accounts and ownership, let’s talk implementation.

### Who are your customers

We’ll keep track of your customers using the information you submit to the [`entity`](https://increase.com/documentation/api#entities) API. Regardless of the legal account owners, we’ll need all of the required information for each of your customers.

| Account Ownership                                                      | Implementation                                                                                                                                                                                                                                             |
| ---------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| You own accounts                                                       | Each `account` will be created under your corporate entity. You’ll create an `informational` entity for each of your customers using the `relationship` parameter on `Post /entities`.                                                                     |
| Accounts are owned by the bank for the benefit (FBO) of your customers | Each `account` will be created under the bank’s entity (which we’ll create for you) and held for the benefit of your customers. You’ll create an `informational` entity for each of your customers using the `relationship` parameter on `Post /entities`. |
| Individual customers own accounts                                      | Each `account` will be created under the relevant `entity`. You’ll create `unaffiliated` entities for each of these customers as these entities are not owned or controlled by you.                                                                        |

## Customer Information Program

You’ll be responsible for verifying the identity of your customers through your own Customer Information Program. We’ll collect the data you receive from any identity verification provider using the `supplemental_documents` parameter on Entity creation. This should be include `id`s of one or more Files created via the [File API](https://increase.com/documentation/api#files). These files can be unstructured content: perhaps a PDF containing an identity document, or a JSON blob returned by the identity provider’s API.

## Tracking customer balances

We’ll also keep track of how much money each of your customers is holding. You can either keep track by creating individual customer accounts or by submitting your ledger balances at the end of each day.

| Account Structure            | Implementation                                                                                                                                                                                                                          |
| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Individual customer accounts | If your individual customers own their accounts, you’re done! If you’re holding your customer money in your own name or in the bank’s name, you’ll pass the `entity_id` associated with the `informational_entity` on account creation. |
| Commingled accounts          | You’ll need to pass the end of day balances and the associated `entity_id` for each of your customers to the `bookkeeping` API. The documentation for this API is currently gated. Please ping us for more details.                     |

If you have any questions don’t hesitate to reach out to [support@increase.com](mailto:support@increase.com).


Platform implementation guide


## Roles and permissions

Your group can have different levels of authorizations and permissions depending on the roles attributed to the group's members. Roles can be selected in the dashboard's [team settings](https://dashboard.increase.com/settings/team).

### Owner

The owner is the ultimate decision maker for the group. Owners are authorized to perform any action including transfer approval and team management. A group should only have one owner.

### Administrators

Administrators are able to perform all actions including transfer approval and team management. In the event of a dispute, the owner’s authority supersedes the administrator’s.

### Assistants

Assistants are able to create transfers for approval in the dashboard but are not able to approve transfers. They are not able to add or remove members from the group.

### Read only

Read only users are able to view and export data via both the API and the dashboard. They are not able to create transfers or access API keys.


Roles and permissions

## Software Development Kits

Increase's [API](/documentation/api) can be accessed via SDKs for several popular languages. The SDKs are generated from our OpenAPI 3 [specification](/openapi.json). The JSON specification may be helpful if you are looking to use a language we haven't implemented yet!

Our APIs are stable but we're just getting started with these SDKs, so some things might change in future versions. If you find them useful or have feedback, [please let us know](mailto:support@increase.com)!

Using an SDK can speed up your integration by providing an implementation for pagination, serialization, timeouts, retries, and error handling.

### Python

Install our Python SDK with `pip`. The source is on [GitHub](https://github.com/Increase/increase-python). Request parameters, response bodies, and error details are all typed with mypy.

```
$ pip install increase
```

### Node

Install our Node SDK with `npm` or `yarn`. The source is on [GitHub](https://github.com/Increase/increase-node). Request parameters, response bodies, and error details are all typed with Typescript.

```
$ npm install --save increase
# or
$ yarn add increase
```

### Java

Install our Java SDK with `maven` or `gradle`. The source is on [GitHub](https://github.com/Increase/increase-java) and the dependency is stored on [Maven Central](https://central.sonatype.com/artifact/com.increase.api/increase-java/0.1.0). Each request and response object is fully specified as a Java class.

```xml

<dependency>
    <groupId>com.increase.api</groupId>
    <artifactId>increase-java</artifactId>
    <version>0.1.0</version>
</dependency>
```

### Kotlin

Install our Kotlin SDK with `gradle` or `maven`. The source is on [GitHub](https://github.com/Increase/increase-kotlin) and the dependency is stored on [Maven Central](https://central.sonatype.com/artifact/com.increase.api/increase-kotlin/0.1.0). Each request and response object is fully specified as a Kotlin class.

```
// In your build.gradle file.
dependencies {
  implementation("com.increase.api:increase-kotlin:0.1.0")
}
```

### More coming soon!

Go and Ruby are coming soon. [Let us know](mailto:support@increase.com) if you'd like to be an early adopter of those libraries.

Software Development Kits


## Transfer approvals

Oftentimes it can be useful to have multiple people approve a transfer.

To help with that, your account can be configured to require all transfers to be initiated and approved by different people.

You can still create transfers by the API, of course, but those too will require approval.

If you’re interested, [let us know](mailto:support@increase.com)!


Transfer approvals


## Two-Factor Authentication

Two-Factor Authentication (2FA) is a security feature that requires users to provide two or more forms of authentication in order to access their accounts. By requiring multiple forms of authentication, 2FA significantly increases the security of your account and helps protect against unauthorized access.

Given the sensitive nature of the Increase product, we require the use of TOTP (Time-based One-Time Password) 2FA for all accounts. TOTP is a form of 2FA that generates a temporary code using an authenticator app that is only valid for a short period of time. This code is generated using a secret key that is known only to the user and the server. Since the code is only valid for a short period of time, it is much more difficult for an attacker to intercept and use it to gain access to your account.

We also strongly recommend using a password manager such as 1Password to store your Increase password.

To setup 2FA on your Increase account, first download an authenticator app on your smartphone. If you're using a password manager, this functionality is often included. Otherwise, we recommend [Authy](https://authy.com/download/). Use that app to scan the QR code we show you when setting up your account. Now, when you log into Increase, you'll be prompted for a code from your app.

### Other forms of 2FA

We're working on additional, more secure forms of 2FA including hardware tokens like Yubikeys. We have no plans to support 2FA over SMS, however. SMS 2FA is vulnerable to attacks such as [SIM Swapping](https://consumer.ftc.gov/consumer-alerts/2019/10/sim-swap-scams-how-protect-yourself) and the National Institute of Standards and Technology (NIST) has has [stated](https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-63b.pdf) that the use of SMS 2FA should be restricted due to these vulnerabilities.


Two Factor Authentication


## Events and webhooks

When something interesting happens on your Increase account, such as a new Transaction being created, Increase can reach out to your application so that you can take action (such as sending an email alert about the transaction to your user) automatically.

The first step is to create an Event Subscription in the [dashboard](https://dashboard.increase.com/applications/webhooks) or via the [API](/documentation/api). As part of this, you specify a URL on your own servers. Increase will then send HTTPS requests to that URL to notify you of activity.

When something noteworthy happens, Increase first generates an [Event object](/documentation/api#event-object). Next, we’ll send a POST request to your endpoint. The body of the POST request will be the same as the API representation of the Event, such as:

```json
{
  "id": "event_123abc",
  "created_at": "2020-01-31T23:59:59Z",
  "category": "transaction.created",
  "associated_object_type": "transaction",
  "associated_object_id": "transaction_abc123",
  "type": "event"
}
```

Note that you can make Event Subscriptions in the live API or in the sandbox. Sandbox Event Subscriptions will receive webhooks for Sandbox Events and vice versa.

### Consuming Events

Individual Events don’t contain very much information on their own. This is by design, as the API structure can remain extremely stable and avoid difficult webhook migrations in the future as the Increase API changes. If you need additional metadata, such as the amount of the Transaction in the above example, make a GET request to the API for that information. You can use the `associated_object_type` or `category` fields to determine what resource to fetch from the API.

If you don’t want to use webhooks, or need to do some batch processing, you can also request Events from the Increase API using the [List Events API](/documentation/api#list-events). Events will remain in our systems for up to 30 days.

### Failures and retries

In production, if your application returns anything other than a 20x HTTP status code, we’ll retry it up to 10 times with exponentially increasing backoffs. In your webhook endpoint implementation, we recommend you place inbound Events into your application’s own queuing system (such as Kafka, Resque, etc) for asynchronous event processing, and returning a 200 response from your endpoint as quickly as possible. Because we can't guarantee we'll receive your 200, your webhook implementation should gracefully handle receiving the same webhook multiple times.

To avoid queueing issues, we will not retry failed webhooks in the sandbox.

### Event Types

For a list of all of the possible actions that will result in an Event/webhook being generated, see our [API reference](/documentation/api).

### Securing your webhook endpoint (recommended)

Increase will include an `Increase-Webhook-Signature` header in each webhook request. This header will contain a timestamp and one or more signatures. The timestamp is prefixed by `t=`, and each signature is prefixed by a scheme. Schemes start with `v`, followed by an integer. Currently, the only valid live signature scheme is `v1`.

```none
Increase-Webhook-Signature: t=2022-01-31T23:59:59Z,v1=7ebfbadaa1856b9f1374f3e08453de3d760838344862344a103c28129d9173d1
```

Increase generates signatures using a hash-based message authentication code ([HMAC](https://en.wikipedia.org/wiki/Hash-based_message_authentication_code)) with [SHA-256](https://en.wikipedia.org/wiki/SHA-2). To prevent [downgrade attacks](https://en.wikipedia.org/wiki/Downgrade_attack), you should ignore all schemes that are not `v1`.
It is possible to have multiple signatures with the same scheme-secret pair. This can happen when you roll an endpoint’s secret from the Dashboard, and choose to keep the previous secret active for up to 24 hours. During this time, your endpoint has multiple active secrets and Increase generates one signature for each secret.

#### Step 1: Extract the timestamp and signatures from the header

Split the header, using the `,` character as the separator, to get a list of elements. Then split each element, using the `=` character as the separator, to get a prefix and value pair. The value for the prefix `t` corresponds to the timestamp, and `v1` corresponds to the signature (or signatures). You can discard all other elements.

#### Step 2: Prepare the signed_payload string

The `signed_payload` string is created by concatenating:

- The timestamp (as a string)
- The character `.`
- The actual JSON payload (that is, the request body)

#### Step 3: Determine the expected signature

Compute an HMAC with the SHA256 hash function. Use the endpoint’s signing secret as the key, and use the `signed_payload` string as the message.

#### Step 4: Compare the signatures

Compare the signature (or signatures) in the header to the expected signature. For an equality match, compute the difference between the current timestamp and the received timestamp, then decide if the difference is within your tolerance.

To protect against timing attacks, use a constant-time string comparison to compare the expected signature to each of the received signatures.
