
## 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


## 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-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


## 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


## 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


## 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/platform-compliance).

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 compliance

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.

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.

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.

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. We’re happy to recommend firms to work with. If you have questions, please reach out to us at support@increase.com.

## Onboarding

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. We’ll ask for the following:

## Business overview

- Answers to our due diligence questionnaire about your business and management team.
- Funds flow showing how money is moving between accounts.
- Copy of your end user terms & conditions.
- Insurance requirements, as applicable.

## Bank Secrecy Act / Anti Money Laundering (BSA / AML) program

- Customer Identification Program overview, showing how you verify the identity of your customers.
- Bank Secrecy Act / Anti Money Laundering Policies and Procedures, including third-party vendors you work with for identity verification and transaction monitoring.

## Compliance & risk overview

- Risk Management Policy that demonstrates how you evaluate and manage vulnerabilities.
- Vendor Management Policy and a list of covered vendors with risk rating.
- Compliance Management Policy that outlines oversight, testing/monitoring, and employee training.
- Complaints Policy that details how you track and resolve complaints from your customers.

## Data & security overview

- Information Security Policy that addresses your systems, technology infrastructure and reliance on any third parties.
- Disaster Recovery and Business Continuity Plans that outline procedures to safeguard data and resume operations.
- Data Security information, including:
  - Results from penetration testing, or plans for penetration testing within your first year of launching a financial technology product.
  - Payment Card Industry Data Security Standards attestation of compliance (as applicable).
  - Results from most recent Independent Service Auditor’s Report – SOC1 Type II, or plans for undergoing this audit within your first year of launching a financial technology product.

## Consumer protection policies (if applicable)

- If your business serves consumers, we’ll request Reg E and E-sign policies, as well as monthly complaints tracking.

# Ongoing requirements

## 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.


Platform compliance


## 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/platform-compliance). 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
```

### More coming soon!

Go, Java and Kotlin 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


## 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

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.

### 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.
