
# 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-to-one, many-to-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.


A guide to implementing accounting for For Benefit Of (FBO) account users with commingled accounts.

Accounting


# Accounts and Account Numbers

Banking cores serve as systems of record, meticulously tracking funds down to the penny in real-time. Bank accounts provide a convenient way to segregate funds by customer. Typically, core systems associate each account with a unique account and routing number pairing, which the customer uses to move funds in and out of the account. The account number serves as the customer’s identifier with the bank, while the routing number identifies the bank with the Federal Reserve.

![Typical account number structure](/images/docs-account-numbers-typical.png)

A consequence of this one-to-one mapping of account and routing numbers is that reconciliation often needs to occur manually since all activity is associated with the same identifying information. Additionally, users have historically restricted access to their account credentials to protect against unexpected ACH debits.

## Increase’s model

Increase's core enables banks to separate the concept of an Account from an Account Number. Our `account` object represents a bucket of funds, while the `account_number` object acts as a pointer to that bucket of funds. This allows for a one-to-many mapping, providing much greater flexibility for new use cases. Importantly, these are building blocks for you to create and manage your own ledger or use Increase as your system of record.

![Increase account number structure](/images/docs-account-numbers-increase.png)

### Accounts

[Accounts](/documentation/api#accounts) are your bank accounts with the bank partner. They store money, receive transfers, and can send payments. They may earn interest. Accounts may also have different legal structures, subject to bank approval. For example, they can be configured as typical demand deposit accounts (DDA) or as a custodial “for the benefit of” (FBO) accounts. You can programmatically create as many Accounts as you need. However, each Account must be associated with a valid [Entity](/documentation/api#entities) and a [Program](/documentation/api#programs). This flexibility allows for better organization and oversight of funds.

### Account Numbers

[Account Numbers](/documentation/api#account-numbers) are unique identifiers that point to an Account. You can instantly create multiple Account Numbers for a single Account and manage them programmatically. This means you can generate unique Account Numbers for different transactions, departments, or projects, all pointing to a specific Account. You can also specify whether an Account Number can allow ACH debits. This flexibility provides more granular control of your funds, enhances tracking and reporting capabilities, and allows for fully programmatic reconciliation.

## Examples

### Tracking vendors

When setting up ACH debits to pay your bills (e.g., utility or rent bills), we recommend creating a unique Account Number for each vendor. This allows you to automatically associate each inbound transfer with that specific vendor, regardless of any missing descriptions or discretionary data, and enables you to disable debit access to your Account when needed.

![Account numbers for vendor payments](/images/docs-account-numbers-vendor-payments.png)

### Capital calls

There are many use cases that require the reconciliation of received funds at scale. One example is managing capital calls for investments. Historically, investors have independently wired funds into a bank account, requiring manual reconciliation of each transaction to each investor.

With Increase, you can issue each investor a unique Account Number. This allows for automatic reconciliation of any received funds from that investor, regardless of how they send funds (via Wire, RTP, ACH, or even Check).

![Account numbers for capital calls](/images/docs-account-numbers-capital-calls.png)


Increase's core enables banks to separate the concept of an Account from an Account Number. This allows for a many-to-one mapping, providing much greater flexibility for new use cases.

Accounts and Account Numbers

Learn more about ACH returns, when you can reinitiate returned transfers, and view a comprehensive list of return reason codes.

Returns


# ACH Reversals

Nacha has a number of conventions that have reached varying degrees of codification. One is reversals—reclaiming funds from an erroneous transfer. Importantly, reversals aren’t a network primitive; they’re regular transfers and therefore can be returned.

For reversals, Nacha requires all fields are the same as the original ACH transfer except for the Company Entry Description (which must be set to `REVERSAL`). A reversal must be sent within 24 hours of noticing the error, and no later than 5 business days from the settlement date of the original ACH transfer. Additionally, reversals will only be accepted for the following errors:

- A duplicate payment
- Specifying an incorrect recipient
- Specifying and incorrect amount
- Sending a Debit earlier than intended
- Sending a Credit later than intended

## How reversals work at Increase

If you need to send a reversal, you can duplicate your initial ACH Transfer with the same `account_number`, `routing_number`, `statement_descriptor`, and `amount` (with the opposite sign). However, you’ll need to include the `company_entry_description` with a value of `REVERSAL`. Because reversals are sent as separate ACH transfers, they will not be associated with the original Transfer object.

## Other Conventions

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


Learn more about ACH reversals, when they're allowed, and how you can initiate them.

Reversals


# Standard Entry Class (SEC) Codes

The Standard Entry Class (SEC) code is a three-letter code that identifies the type of ACH entry being made. It’s a required field used to classify transfers by their purpose or intended use. These codes are maintained by [Nacha](https://nacha.org/).

The most common selections are (PPD) Prearranged Payment and Deposit, (CCD) Corporate Credit or Debit Entry, and (WEB) Internet Initiated/Mobile Entry.

## Monetary messages

| Code  | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ARC` | **Accounts Receivable Entry** - This is for converting paper checks received in person, via mail, or at a dropbox location into electronic ACH debit transactions. The original check is used as source documentation for the ACH entry.                                                                                                                                                                                                                                                                                                                      |
| `BOC` | **Back Office Conversion Entry** - This is for converting paper checks received at retail or other point-of-sale locations into electronic ACH debit transactions. This process occurs in the back office of the merchant or retailer, rather than at the point of purchase. The conversion helps businesses more efficiently process paper checks.                                                                                                                                                                                                           |
| `CCD` | **Corporate Credit or Debit Entry** - This is for corporate-to-corporate transactions, facilitating the transfer of funds (either concentration or disbursement) and is often used for payroll, tax, and vendor payments.                                                                                                                                                                                                                                                                                                                                     |
| `CIE` | **Customer Initiated Entry** - This is for consumer initiated payments from the their account to a non-consumer account. This is typically used by a financial institution to allow a consumer to push payments to a merchant through an online banking service.                                                                                                                                                                                                                                                                                              |
| `CTX` | **Corporate Trade Exchange** - This allows businesses to include extensive remittance information with their corporate-to-corporate payments, supporting up to 9,999 addenda records within a single transaction. A common use is paying multiple invoices that are listed in the addenda records, although it may be used for a single invoice.                                                                                                                                                                                                              |
| `IAT` | **International ACH Transaction** - This is for for ACH entries that involve a financial agency outside the U.S. It's designed to provide additional information required for international payments.                                                                                                                                                                                                                                                                                                                                                         |
| `MTE` | **Machine Transfer Entry** - This is used for transactions initiated by consumers when they use an ATM. This code facilitates the electronic transfer of funds from the consumer's account to the account of the entity operating the ATM.                                                                                                                                                                                                                                                                                                                    |
| `POP` | **Point of Purchase Entry** - This is for immediately converting paper checks received at retail or other point-of-sale locations into electronic ACH debit transactions. Unlike with a Back Office Conversion Entry (BOC), the checks are used solely as a source document and must be converted to an ACH entry on site.                                                                                                                                                                                                                                    |
| `POS` | **Point of Sale Entry** - This is used for debit entries to a consumer account that are initiated at an “electronic terminal.” A common example is a consumer using a debit card at a retail point-of-sale terminal to complete a purchase or receive cash back.                                                                                                                                                                                                                                                                                              |
| `PPD` | **Prearranged Payment and Deposit** - This is used for credits or debits originated by an organization to a consumer. A few common examples are direct deposit of payroll, social security benefits, and recurring bill payments.                                                                                                                                                                                                                                                                                                                             |
| `RCK` | **Re-presented Check Entry** - This is used for the electronic re-presentation of a returned check due to insufficient funds. It allows businesses to attempt to collect on a bounced check electronically by initiating a debit.                                                                                                                                                                                                                                                                                                                             |
| `SHR` | **Shared Network Transaction** - This is for debit or credit transactions initiated through a shared electronic network. A common example is a consumer using their debit card at terminals or ATMs not directly operated by their own bank.                                                                                                                                                                                                                                                                                                                  |
| `TEL` | **Telephone-Initiated Entry** - For debits to consumer accounts where the authorization is obtained over the telephone. It's used by companies that receive payment instructions from consumers via phone.                                                                                                                                                                                                                                                                                                                                                    |
| `TRC` | **Truncated Entry** - This is used when converting paper checks into electronic transactions at the point of truncation, typically by the financial institution that first receives the check for deposit. Unlike the Back Office Conversion (BOC) and Point of Purchase (POP) entries that convert checks at the merchant's location, TRC transactions occur within the banking system. The original paper check is truncated, meaning it is removed from the physical processing flow after its electronic image is captured and processed as an ACH entry. |
| `WEB` | **Internet Initiated/Mobile Entry** - This is used for consumer payments initiated or authorized via the Internet. Debit WEB entries can only be initiated by non-consumers to debit a consumer’s account. Credit WEB entries can only be used for consumer to consumer (P2P) transactions. This code is commonly used for online bill payments and transactions initiated through a website or mobile app.                                                                                                                                                   |
| `XCK` | **Destroyed Check Entry** - This is used in situations where a physical check was destroyed or lost after a financial institution received it but before it could be processed. This allows the financial institution to process an ACH debit entry against the account on which the original check was drawn.                                                                                                                                                                                                                                                |

## Non monetary messages

Non-monetary Standard Entry Class (SEC) codes are used primarily to transfer information between financial institutions or Federal Government agencies. They do not transfer any funds. The most common non-monetary SEC code you will likely encounter is a Notification of Change (COR).

| Code  | Description                                                                                                                                                                                                                                                                                                       |
| ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ACK` | **ACH Payment Acknowledge** - This is used by the Receiver to send an acknowledgement of receipt of a CCD request to the originator. This allows the Receiver to confirm that the payment instructions have been received and are being processed.                                                                |
| `ADV` | **Automated Accounting Advice** - This is used by the Receiver to send an acknowledgement of receipt of a CCD request to the originator. This allows the Receiver to confirm that the payment instructions have been received and are being processed.                                                            |
| `ATX` | **Financial EDI Acknowledgment** - This is used by the Receiver to send an acknowledgement of receipt of a CTX request to the originator. This allows the Receiver to confirm that the payment instructions have been received and are being processed.                                                           |
| `COR` | **Notification of Change, or Refused Notification of Change** - This is used by the Receiver to inform the Originator that an entry has been posted to a receiver's account, but some of the information (such as account number or routing number) is incorrect and needs to be changed for future transactions. |
| `DNE` | **Death Notification Entry** - This is used by the Federal Government agency to notify financial institutions that an account holder has passed away.                                                                                                                                                             |
| `ENR` | **Automated Enrollment Entry** - This is used by a financial institution to electronically enroll an individual for direct deposit or payment services which will be originated by Federal Government agencies. A common example is enrolling in Social Security.                                                 |


View a glossary of every Standard Entry Class (SEC) code, a required field used to classify ACH transfers by their purpose or intended use.

Standard Entry Class codes


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


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.

Backwards compatibility


# Bookkeeping

## Tracking customer balances

We'll ask you to submit financial reporting to help us keep track of how much money each of your customers is holding. How this works depends on whether you're using individual or commingled accounts for your customers.

### Individual customer accounts

If your individual customers have their own accounts, you’re done! We already have all the information we need.

### Commingled accounts

If you're operating accounts commingling customer funds, you'll need to integrate against our Bookkeeping API. Read on.

## Chart of Accounts

You don’t need to bookkeep the entirety of your finances to be compliant. We expect you to keep track of customer balances and commingled cash.

At a minimum, you’re expected to create:

1. One bookkeeping account per customer. With these accounts, you should set `compliance_category` to `customer_balance` and additionally pass the `entity_id` of the customer.
2. One bookkeeping account per commingled Account (i.e. `account_123`). With these accounts, you should set `compliance_category` to `commingled_cash` and additionally pass the `account_id` of the relevant account.

To set up a `customer_balance` bookkeeping account
First, submit an informational entity for the customer whose balance you’re tracking. Then:

```curl
curl -X "POST" \
  --url "${INCREASE_URL}/bookkeeping_accounts" \
  -H "Authorization: Bearer ${INCREASE_API_KEY}" \
  -d '{
  "name": "John Funds",
  "compliance_category": "customer_balance",
  "entity_id": "entity_456", # a customer entity
}'

# Response
{
  id: "bookkeeping_account_123",
  name: "John Funds",
  compliance_category: "customer_balance",
  entity_id: "entity_456"
}
```

To set up a `commingled_cash` bookkeeping account:

```curl
curl -X "POST" \
  --url "${INCREASE_URL}/bookkeeping_accounts" \
  -H "Authorization: Bearer ${INCREASE_API_KEY}" \
  -d '{
  "name": "FBO Account",
  "compliance_category": "commingled_cash",
  "account_id": "account_abc" # a commingled account
}'

# Response
{
  id: "bookkeeping_account_456",
  name: "John Funds",
  compliance_category: "commingled_cash",
  account_id: "account_abc"
}
```

The above accounts will only be sufficient in narrow cases: you’ll likely need to create other Bookkeeping Accounts to handle situations where your customer balances do not match the commingled cash exactly. These accounts do not need to have a `compliance_category`. See the examples below.

### Invariants

You are expected to submit bookkeeping entries such that:

1. The customer balances reflected in each of their bookkeeping accounts matches your ledger. This should reflect what a customer would see in your own application interface.
2. The balance in the commingled account matches the current balance in the account at all times.

When submitting bookkeeping entry sets affecting commingled cash accounts, you should tag an entry set with the `transaction_id` for the Transaction which affected the cash balance.

## Examples

### A customer transfers in $100

Debit `customer_balance`, credit `commingled_cash`:

```curl
curl -X "POST" \
  --url "${INCREASE_URL}/bookkeeping_entry_sets" \
  -H "Authorization: Bearer ${INCREASE_API_KEY}" \
  -d '{
  "date": "2020-01-31T23:59:59Z", # date must match transaction.created_at
  "transaction_id": "transaction_123", # entries sum must match transaction.amount
  "entries": [
    {
      "bookkeeping_account_id": "bookkeeping_account_123", # customer balance account
      "amount": -100_00,
    },
    {
      "bookkeeping_account_id": "bookkeeping_account_456", # commingled cash account
      "amount": 100_00,
    }
  ]
}'
```

### One customer transfers funds to another

Debit one `customer_balance`, credit the other `customer_balance`.

### You charge a fee to a customer

First, you should create an AccountTransfer from the commingled Account to an Account you control (on your Commercial Banking program).

Credit `commingled_cash`, debit `customer_balance`, tag the `transaction_id`.

### You receive a bundled payout from Stripe containing some corporate cash

First, you’ll need to create an Bookkeeping Account to track corporate cash being held in the FBO.

```curl
curl -X "POST" \
  --url "${INCREASE_URL}/bookkeeping_accounts" \
  -H "Authorization: Bearer ${INCREASE_API_KEY}" \
  -d '{
  "name": "Corporate Cash"
}'

# Response
{
  id: "bookkeeping_account_789",
  name: "Corporate Cash"
}
```

Then, create an entry set (this example assumes you’re receiving a bundled payout for $230, $100 of which belongs to each of two customers and $30 of which belongs to you).

```curl
curl -X "POST" \
  --url "${INCREASE_URL}/bookkeeping_entry_sets" \
  -H "Authorization: Bearer ${INCREASE_API_KEY}" \
  -d '{
  "date": "2020-01-31T23:59:59Z", # date must match transaction.created_at
  "transaction_id": "transaction_123", # entries sum must match transaction.amount
  "entries": [
    {
      "bookkeeping_account_id": "bookkeeping_account_123", # customer balance account
      "amount": -100_00,
    },
    {
      "bookkeeping_account_id": "bookkeeping_account_abc", # another customer balance account
      "amount": -100_00,
    },
    {
      "bookkeeping_account_id": "bookkeeping_account_789", # corporate cash
      "amount": -30_00,
    },
    {
      "bookkeeping_account_id": "bookkeeping_account_456", # commingled cash
      "amount": 230_00,
    }
  ]
}'
```


Use Bookkeeping to track customer balances and manage your chart of Accounts.

Bookkeeping


# Physical cards

Increase produces and mails Visa cards connected to Increase accounts. Use [this API](https://increase.com/documentation/api#physical-cards) to create a card. You can provide two images to customize the card.

Increase Visa cards are white cards with black magstripe, text and images. Cards support EMV and NFC contactless payments.

## Card art image

The main card art is printed on the front of the card. The card is white plastic and the printing ink and magstripe are black.

- PNG
- 2100 x 1344 px
- 600 DPI
- No transparency
- No images within 2.54mm of card edge
- No images within 3mm of Visa logo
- No images within 3mm of chip edge

![Card Art Template](/images/card_art_template.png)

## Carrier image

The card carrier is a tri-fold letter included with the card when it's mailed to your user. The paper is white and the printing ink is black.

- PNG
- 2550 x 3300 px
- 300 DPI
- No transparency

![Carrier Template](/images/carrier_template.png)


Increase can manufacture and mail custom Visa cards.

Physical cards


# 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. The image needs to include a Visa logo, which can be downloaded from their [Brand Guidelines portal](https://www.merchantsignage.visa.com/brand_guidelines). Refer to page 21 of the [Visa Digital Brand Guidelines](<https://spponeimages.azureedge.net/prod/9470d134-2ea5-4efd-bf80-2c6fe9ef2fdbvisa_digital_brand_requirements(revised)_april_2024.pdf>) for a full explanation.

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

## Tokenization flow

Saving a card number in a wallet follows two main steps, where the first checks whether the card should be tokenized and the second performs two-factor verification of the cardholder using either phone or email. Both of these steps can be controlled dynamically using the [real-time decisions API](https://increase.com/documentation/api#real-time-decisions).

### Real-time decision: requesting a digital wallet token

The first step in the tokenization flow lets you decide whether the cardholder should be able to save a given card in their wallet at all, and if they should, what contact methods you would like to use to send them the one-time code to verify that they own the card. When no real-time decision handler is present, all cards can be saved in a wallet as long as they are active and have either `digital_wallet.phone` and/or `digital_wallet.email` populated. To action the `real_time_decision.digital_wallet_token_requested` you call the `/real_time_decisions/:id/action` endpoint like usual, populating the `digital_wallet_token` sub-hash with the contact details.

![Apple Pay choose verification method](/images/apple_pay_choose_verification.jpg)

### Real-time decision: authenticating a digital wallet token

Once the tokenization decision has been made, the customer will choose between the contact methods you provided in the previous step to decide how to receive a two-factor authentication code. Once chosen, we will either send the two-factor code to the cardholder on your behalf, or delegate the communication to you if a `real_time_decision.digital_wallet_authentication_requested` real-time decision handler is present. Once you receive the real-time decision, you would be responsible for sending the two-factor code to the requested email or phone number, followed by actioning the real-time decision once that's done.

![Apple Pay enter two-factor code](/images/apple_pay_verify.png)


Increase's cards can be added to digital wallet apps like Google Pay and Apple Pay. Learn more about how to set up digital wallets.

Digital wallets


# Card Payment lifecycle

Increase is an issuer processor and supports all flows that cards require. Unlike other Transfers (like ACH), Card Payments do not iterate through a series of statuses. Instead, a `card_payment` is composed of different entries which are closely modeled on the messages Visa sends. Together, these entries encompass the full lifecycle of a cardholder’s experience.

Entries are added to the `card_payment` object as they’re processed and you can receive [webhook Events](/documentation/real-time-decisions#real-time-decisions) when they’re received.

## Card Payment entries

![Card Payment entries](/images/docs-cards-lifecycle.png)

### card_authorization

Most Card Payments start with an authorization. At this stage, no money is moved. Instead, an authorization represents a message from the merchant and their acquirer that says “please hold $X for this transaction, as I intend to settle it later.” Increase creates a Pending Transaction for each authorization to model this hold.

### card_increment

Before a Card Payment clears, an authorization can be updated to a larger amount. This is called an increment, and is useful for things like a [tips at a restaurant](/documentation/card-payment-lifecycle#examples). An authorization can be incremented multiple times. Each time, Increase updates the Pending Transaction to modify the hold on the Account balance.

### card_reversal

An authorization can be either partially or fully reversed before the payment clears. An authorization can also be reversed multiple times. Reversals are often used for reducing holds of larger amounts (for example when checking out of a hotel room). When a reversal is received, Increase updates the Pending Transaction to modify the hold on the Account balance.

Additionally, since issuers often do not decline authorizations for things such as an invalid zip code, a common pattern is to immediately reverse an authorization after it has been created if it comes back with an invalid address validation status.

### card_settlement

Once an authorization clears, Increase creates a `card_settlement` entry to represent the settlement of funds. Predictably, each `card_settlement` maps to a single Transaction. However, there are some less intuitive aspects:

1. An authorization can be cleared multiple times. This means that a Card Payment can include multiple `card_settlement` entries for different amounts, and consequentially also map to multiple Transactions. For example, this is commonly used for settling individual line items from a single order as they ship.

2. An authorization can be cleared for a higher or lower amount than the original. For example, sometimes restaurant bills with tips are cleared for the full amount rather than incrementing the authorization first.

3. Card Payments do not technically need to be authorized. Therefore, its possible for a `card_settlement` to appear without any prior authorization or notice. This is referred to as a “force push." There are certain rules that allow issuers to dispute these with the reason that they should’ve been authorized first.

### card_refund

When a payment is refunded, Visa sends a separate `card_refund` message. Up until the last few years, refunds were always processed solely with clearing files, meaning they settled without any prior authorization. However, this was not an ideal cardholder experience since refunds often took days to appear on a statement. Recently, Visa started mandating the use of refund authorizations. This helps by showing a positive hold on the funds instantly, which is then turned into an actual refund later. While this is the new standard, refunds are still commonly processed without prior authorization. Visa unfortunately does not clearly associate refunds with the original payment. Therefore a `card_refund` is associated with its own `card_payment` object.

### card_decline

A payment can be declined for multiple reasons, including insufficient funds or incorrect card details (like the expiration). This message does not move funds, but does create a Declined Transaction on the Account. A `card_decline` is a singular, terminal entry.

### card_authorization_expiration

While a transaction can technically be cleared at any time, there are rules for how long it is considered “valid” after which the merchant pays more interchange and the transaction has different dispute rules. Increase follows Visa’s rules for expiring authorizations. For example, we release most authorizations after 7 days but wait 30 days for authorizations related to hotels and rental cars. However, per Visa’s recommendations, you (as an Issuer) can choose to release funds earlier to minimize insufficient funds declines.

### card_validation

A card validation sends a $0 authorization in order to check if a card number (and optionally its CVV2 or cardholder address) is valid. This message does not move funds. A `card_validation` is a singular, terminal entry.

### card_fuel_confirmation

A Fuel Confirmation is a special message sent by Visa explicitly for the use of incrementing holds at gas station pumps. Functionally, a `card_fuel_confirmation` acts like a `card_increment`, however it follows a different technical process. When a user swipes their card at a gas pump, Visa creates an initial $175 authorization. When pumping finishes, instead of directly updating the authorization, Visa sends an “Advice” message with details of the final amount prior to it clearing. Fuel Confirmations predate Card Increments and remain in common use due to a large network of legacy fuel pumps.

## Examples

### A typical payment

![Card flows: Typical payment](/images/docs-cards-flows-typical.png)

1. A user purchases an item for $10.
2. A `card_payment` is created. It includes a `card_authorization` entry for $10.
3. A `pending_transaction` for -$10 is created on the Account to hold the funds.
4. Once the merchant clears the payment, a `card_settlement` entry is created for $10.
5. The `pending_transaction` for -$10 completes.
6. A `transaction` is created for -$10 on the Account.

### An increment (Tipping)

![Card flows: Increments](/images/docs-cards-flows-increment.png)

1. A user purchases a coffee for $5.
2. A `card_payment` is created. It includes a `card_authorization` entry for $5.
3. A `pending_transaction` for -$5 is created on the Account to hold the funds.
4. The user adds a $1 tip.
5. A `card_increment` entry is received for $1.
6. The `pending_transaction` amount updates to -$6.
7. Once the merchant clears the payment, a `card_settlement` entry is created for $6.
8. The `pending_transaction` for -$6 completes.
9. A `transaction` is created for -$6 on the Account.

### A partial reversal (Hotel holds)

![Card flows: Reversals](/images/docs-cards-flows-reversal.png)

1. A user checks into a prepaid hotel. They provide a card for a $100 security deposit.
2. A `card_payment` is created. It includes a `card_authorization` entry for $100.
3. A `pending_transaction` for -$100 is created on the Account to hold the funds.
4. The user accumulates $20 of room charges and checks out.
5. A `card_reversal` entry is received for $80.
6. The `pending_transaction` amount updates to -$20.
7. Once the merchant clears the payment, a `card_settlement` entry is created for $20.
8. The `pending_transaction` for -$20 completes.
9. A `transaction` is created for -$20 on the Account.

### A refund (with authorization)

![Card flows: Refunds](/images/docs-cards-flows-refund.png)

1. A user returns a item for $10.
2. A `card_payment` is created. It includes a `card_authorization` entry for -$10.
3. A `pending_transaction` for +$10 is created to instantly credit the funds.
4. Once the merchant clears the payment, a `card_settlement` entry is created for -$10.
5. The `pending_transaction` for +$10 completes.
6. A `transaction` is created for +$10 on the Account.

### A multi-capture (shipping separate line items)

![Card flows: Multi-capture](/images/docs-cards-flows-multi-capture.png)

1. A user purchases two items ($50 and $70 respectively) for a total of $120.
2. A `card_payment` is created. It includes a `card_authorization` entry for $120.
3. A `pending_transaction` for -$120 is created on the Account to hold the funds.
4. The merchant ships the first item and clears payment for $50.
5. A `card_settlement` entry is received for $50.
6. A `Transaction` is created for -$50 on the Account.
7. The `pending_transaction` amount updates to -$70.
8. The merchant ships the second item and clears payment for $70.
9. A `card_settlement` entry is received for $70.
10. The `pending_transaction` for -$70 completes.
11. A `transaction` is created for -$70 on the Account.


Learn more about the lifecycle of a Card Payment.

Lifecycle


# Check 21

#### An introductory guide explaining Check 21, how it functions, and key concepts for operating a check integration.

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

## How Check 21 works

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. Here’s how it works:

![How Check 21 works](/images/docs-checks-flow.png)

**Check capture**: When a check is deposited at a bank, the bank captures an electronic image of the front and back of the check along with the Magnetic Ink Character Recognition (MICR) line data. The physical check is truncated (i.e., not sent to the paying bank). Instead, the electronic image and associated data are used for processing.

**Submission**: The bank creates an Image Cash Letter (ICL), which includes the electronic check images and associated data. The ICL is formatted according to the [X9.37 or X9.100-187 standards](https://www.frbservices.org/binaries/content/assets/crsocms/financial-services/check/setup/frb-x937-standards-reference.pdf). The ICL is transmitted over a secure network to the Federal Reserve for further processing.

**Federal Reserve processing**: The Federal Reserve receives the ICL and validates it for compliance with Check 21 standards. This includes checking for [image quality](https://www.frbservices.org/binaries/content/assets/crsocms/financial-services/check/setup/iqa-settings.pdf), completeness, and correctness of the MICR line data. The Federal Reserve routes the electronic check image to the paying bank (the bank on which the check is drawn) using the check's routing number.

**Acceptance**: The paying bank receives the check image and verifies it for accuracy, ensuring that the paying account is open and that there is a sufficient balance. If the check is accepted, the bank posts the transaction to the account holder's account, debiting the amount specified on the check.

**Funds transfer**: Upon validation, the paying bank notifies the Federal Reserve indicating the acceptance of the check. The Federal Reserve acknowledges the receipt of the notification and then facilitates the financial settlement between the banks involved. This typically occurs through the Federal Reserve's FedACH or Fedwire services.

**Funds availability**: The depositary bank's own funds availability policy will determine when the funds are available to the account holder.

**Returns and adjustments**: If a payer’s financial institution declines to accept a check (for example, insufficient funds or the account being closed), they can return it through Check 21. The paying bank creates a return ICL and sends it back to the depository bank through the Federal Reserve. Any discrepancies or issues identified during processing are handled through adjustments, which are processed similarly to the original transactions.

## Disputes

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

## Substitute checks

In the event a paper check is needed, the Federal law allows the creation and use of substitute checks. Substitute checks are used when the clearing or receiving bank either cannot process electronic images, or prefers a paper document. Occasionally, paper checks are used as a proof of payment or for legal or record keeping purposes. In these situations, the customer can request a substitute check to be provided.

## Alternatives

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

## 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 EBCDIC 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 is the Federal Reserve’s electronic check clearing service. Learn more about how Check 21 works and pitfalls to avoid.

Overview of Check 21


# Depositing checks

## Lifecycle

![Check Deposit statuses](/images/docs-check-deposit-status.png)

| Status      | Description                           |
| ----------- | ------------------------------------- |
| `pending`   | The Check Deposit is pending review.  |
| `submitted` | The Check Deposit has been deposited. |
| `rejected`  | The Check Deposit has been rejected.  |
| `returned`  | The Check Deposit has been returned.  |

## Depositing a Check with Increase

Depositing a Check via the Increase API kicks off several steps involving you, Increase, the Federal Reserve, and the receiving bank.

1. You make a `POST /check_deposits` call with the [details](/documentation/api#create-a-check-deposit) of the deposit amount and images of the check. A Check Deposit is created with a status of `pending`.
2. A Pending Transaction is immediately created for the full amount of the deposit.
3. The check images are processed and reviewed by an Increase operator. Upon successful processing, the Check Deposit object updates with its `deposit_acceptance` [details](/documentation/api#check-deposit-object.deposit_acceptance).
4. When the file is submitted to the Federal Reserve, Increase updates the Check Deposit object with its `deposit_submission` [details](/documentation/api#check-deposit-object.deposit_submission) and the status is updated to `submitted`.
5. A Transaction is immediately created for the full amount of the deposit and the Pending Transaction is marked as `complete`.
6. If a Return is received from the originating bank, the Check Deposit object is automatically updated with `deposit_return` [details](/documentation/api#check-deposit-object.deposit_return) and the status is updated to `returned`. A new Transaction is created to decrement funds from the Account.

## Reviews and rejections

All check deposit images are processed and reviewed by an Increase operator. This includes validation of the account number, routing number, amount, and serial number. If there is invalid information or an issue processing the check image, the Check Deposit object status is updated to `rejected`. The Pending Transaction updates to `complete`, no Transfer information is submitted to the network, and no additional Transactions are created.

## Lockboxes

You can also create [Lockboxes](/documentation/api#create-a-lockbox) to deposit checks automatically via the mail. Each Lockbox has a unique address and is associated with one of your Accounts. When mail arrives at one of your Lockboxes, an [Inbound Mail Item](/documentation/api#retrieve-an-inbound-mail-item) object will be created and an `inbound_mail_item.created` webhook will be sent. If the mail contains one or more checks, a Check Deposit object will be created for each included check and then proceed through the lifecycle as described above in "Depositing a Check with Increase".


Learn more about the lifecycle of a Check Deposit.

Depositing checks


# 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. Your code should treat them as opaque strings and not try to interpret the prefix.

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

## North American Industry Classification System codes

The North American Industry Classification System (NAICS) list of codes is a taxonomy of industries. Depending on your setup, you may be asked to submit the correct code for each of your users. Increase uses the [2022 version](https://www.naics.com/search/) of the NAICS codes.

You can download the 2022 NAICS codes in CSV format [here](/naics-2022.csv).

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


Increase's API documentation references several repeated concepts like dates, currencies, and countries. Read definitions for those concepts.

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.


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.

Exports


# Extended deposit insurance

#### Access multi-million-dollar FDIC insurance at participating IntraFi network banks.

## How does it work?

Standard Federal Deposit Insurance Corporation (FDIC) insurance provides protection of up to $250K per depositor, per insured bank, for each [account ownership category](https://www.fdic.gov/resources/deposit-insurance/financial-products-insured/). If you hold higher balances, you may want additional deposit insurance.

Increase connects to a deposit sweep network called [IntraFi](https://www.intrafi.com/). This allows depositors to automatically sweep funds over $250K into multiple accounts with other institutions, which are each fully FDIC insured. You'll be able to take advantage of the FDIC insurance across multiple banks without needing to open or manage separate bank accounts.

For example, imagine a business with $1M in deposits. Standard FDIC insurance would only insure the first $250k, leaving $750k uninsured. IntraFi’s sweep network distributes funds across 4 or more institutions, each holding a balance less than the $250K FDIC insurance limit. In the unlikely case of a bank failure, the full $1M of deposited funds are safely insured.

## How will my banking experience change?

Your banking experience will remain the same. You will not need to manage your funds with multiple institutions or experience any delays in accessing your funds.

## Can I prevent IntraFi from sweeping funds to a specific bank?

Yes! You can manage which banks are ineligible to hold your swept funds using the settings in the `Account Details` tab. This is typically useful when you hold funds at a participating bank and want to remain under the FDIC limit.

## Are there any fees?

Moving funds via IntraFi incurs a monthly fee equal to an annualized rate of 0.12% on your average monthly swept balance. Increase will charge this fee to your account at the end of each month.

## How do I opt in?

If you're interested in participating, you can opt in via the Dashboard by navigating to `Accounts`. For each Account, you can configure the Extended Deposit Insurance in the `Details` tab. You can enroll as many Accounts as you'd like.

Once your Account(s) are enrolled, any funds above $250k will be swept into IntraFi's depository network and receive extended FDIC insurance.

Email us at [support@increase.com](mailto:support@increase.com) if you have any questions!

---

###### ​​Deposit placement through IntraFi Cash Service (“ICS”) is subject to the terms, conditions, and disclosures in applicable agreements. Although deposits are placed in increments that do not exceed the FDIC standard maximum deposit insurance amount (“SMDIA”) at any one destination bank, a depositor’s balances at the institution that places deposits may exceed the SMDIA (e.g., before settlement for deposits or after settlement for withdrawals) or be uninsured (if the placing institution is not an insured bank). The depositor must make any necessary arrangements to protect such balances consistent with applicable law and must determine whether placement through ICS satisfies any restrictions on its deposits. A list identifying IntraFi network banks appears at https://www.intrafi.com/network-banks. The depositor may exclude banks from eligibility to receive its funds. IntraFi and ICS are registered service marks, and IntraFi Cash Service is a service mark, of IntraFi Network LLC.

###### Banking services provided by Grasshopper Bank, N.A. and First Internet Bank of Indiana, Members FDIC. Increase is a financial technology company, not a bank. Cards Issued by First Internet Bank of Indiana, pursuant to a license from Visa Inc. Deposits are insured by the FDIC up to the maximum allowed by law through Grasshopper Bank, N.A. and First Internet Bank of Indiana, Members FDIC.


Access multi-million-dollar FDIC insurance at participating IntraFi network banks directly in Increase.

Extended deposit insurance


# Overview of FedACH

#### An introductory guide explaining ACH, how it functions, and key concepts for operating an ACH integration.

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). [Electronic Payment Network (EPN)](https://www.theclearinghouse.org/payment-systems/ACH) is an alternative ACH network operated by [The Clearing House (TCH)](https://www.theclearinghouse.org/).

## How FedACH works

FedACH is an asynchronous network that sends files containing batches of transfers from the originating depository financial institutions (ODFI) to the Federal Reserve, and ultimately onward to the receiving depository financial institutions (RDFI). To understand how ACH works, we can discuss it in a few stages.

![How FedACH works](/images/docs-ach-process.png)

**Initiation**: An ACH transfer is created, which includes mandatory details of the account number, routing number, amount, and [Standard Entry Class (SEC) code](/documentation/ach-standard-entry-class-codes). 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 match the account holder name.

**Batching**: Unlike other payment methods, ACH transactions are batched and do not settle instantly. The originating depository financial institution (ODFI) consolidates all ACH transfers into a smaller set Nacha files for submission. A company operating at scale can sometimes request their transfers be batched into their own file.

**Submission**: The Nacha files are submitted to the Federal Reserve at specified times each day. As is expected, these align with specific submission windows and affect when funds are available at the receiving depository financial institutions (RDFI). If a file is successfully submitted, the Federal Reserve will respond with an acknowledgment. Increase publishes the [submission status of every ACH file](https://status.increase.com/). Additionally, ACH transfers can be submitted with different settlement timing (Same day or Standard). You can read more about settlement timing below.

**Clearing**: During a submission window, the Federal Reserve aggregates all transactions from various financial institutions, nets them out, and calculates the final amount owed by and to each participating financial institution.

**Funds transfer**: After clearing, the actual transfer of funds occurs during the settlement process. The Federal Reserve ensures that the appropriate amounts are debited and credited to the respective financial institution.

**Funds availability**: Even though the processing might happen on the same day (for Same Day ACH) or the next day (for Standard ACH), the funds might not be immediately available. This delay is often due to the financial institution’s policies on funds availability and the time needed for risk management and fraud prevention. A common example of this are [debit funds holds](/documentation/sending-ach-debit-transfers#debit-funds-holds).

**Returns**: An ACH transfer can be automatically returned by the receiving depository financial institution (RDFI) within 2 business days for non-consumer accounts, and 60 days for consumer accounts. A late return can be requested after these deadlines, but the originating depository financial institution (ODFI) can accept or reject them at their discretion. [Learn more about ACH Returns](/documentation/ach-returns).

**Reversals**: The originating depository financial institution (ODFI) can attempt to reclaim funds from an erroneous transfer by sending a second ACH Reversal. [Learn more about ACH Reversals](/documentation/ach-reversals).

## ACH directions

ACH supports both credit and debit origination. Credits allow you to push funds to a recipient. Debits allow you to pull funds from a recipient.

|            | You originate                           | You receive                             |
| ---------- | --------------------------------------- | --------------------------------------- |
| **Credit** | Funds are removed from your Account (-) | Funds are added to your Account (+)     |
| **Debit**  | Funds are added to your Account (+)     | Funds are removed from your Account (-) |

ACH credits, also known as a direct deposit, are commonly used for payroll, tax refunds, and pension payments. Sending an ACH credit is relatively simple since funds are pushed from a bank account you own. Funds availability is typically 1-2 days.

ACH debits are commonly used for bill payments, such as utility bills, mortgages, loans, and subscription services, where the originator pulls funds from the recipient’s account. However, since debits move funds not owned by the originator, they [require authorization](/documentation/sending-ach-debit-transfers#debit-authorizations) from the recipient and are accountable to [funds holds](/documentation/sending-ach-debit-transfers#debit-funds-holds).

When sending an ACH debit or credit, you must specify the [Standard Entry Class (SEC)](/documentation/ach-standard-entry-class-codes) code, which is used to classify the ACH transfer by the type of recipient account and intended use.

## Non-financial messages

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

## Timing

[FedACH operates](https://www.frbservices.org/resources/resource-centers/same-day-ach/fedach-processing-schedule.html) three same-day windows and six non same-day windows. Increase submits for every window and we can accept transfers up to an hour before the cut-offs. You can track [Increases ACH submission status](https://status.increase.com/) at any time.

Each FedACH window is made up of three parts:

- The Transmission Deadline is when FedACH must receive files.
- The Target Distribution is when FedACH aims to tell receiving depository institutions about the transfers.
- The Settlement Schedule is when FedACH will fund the financial institutions’ Federal Reserve accounts.

![ACH submission windows](/images/docs-ach-windows.png)

## Validating an account

To validate 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](/documentation/api#ach-prenotifications) but they’re less used in modern integrations.

## 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 to 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](/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.


Automated Clearing House (ACH) is the dominant low-value transfer mechanism in the US. Learn more about how ACH works and pitfalls to avoid.

Overview of FedACH


# Overview of Fedwire

#### An introductory guide explaining Fedwire, how it functions, and key concepts for operating an wire integration.

Fedwire, formally known as the Federal Reserve Wire Network, is a real-time gross settlement network owned and operated by the 12 U.S. Federal Reserve Banks. It is the dominant high-value transfer mechanism in the US, handling trillions of dollars in transactions daily. Fedwire has two variants: Funds (for USD transfers) and Securities (for transfers of [a limited group of securities](https://www.frbservices.org/financial-services/securities)).

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 to help wire desks properly allocate inbound wires. For example, a receiving account number isn’t strictly required by the specification. Normally this data is not visible to recipients. However, Increase exposes this raw data by default.

## How Fedwire works

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 originating financial institution’s account and credits the receiving financial institution’s account. Here’s how it works:

![How Fedwire works](/images/docs-wire-process.png)

**Submission**: A sender initiates a wire transfer with their institution. The institution debits funds from their account, and sends a payment order to a Federal Reserve Bank. The order includes the payment amount, the receiving institution's details, and any additional instructions for reconciling the payment.

**Verification**: The Federal Reserve Bank verifies the payment order, ensuring the originating institution has sufficient funds to cover the transaction.

**Settlement**: Upon verification, the funds are deducted from the originating institution and credited to the receiving institution. This process occurs in real-time and on a transaction-by-transaction basis, ensuring immediate finality and irrevocability of payments.

**Confirmation**: Both the originating and receiving institutions receive confirmation of the completed transaction, typically within seconds or minutes.

**Allocation**: The receiving institution uses the provided instructions to reconcile the payment with the correct recipient. Funds are deposited into their account.

**Reversal**: If the receiving institution cannot properly reconcile the payment, it is reversed. A new wire transfer is created to send the funds back to the originating institution.

## Reversals

Wire transfers are irrevocable. However, they can be reversed in a few instances. If a receiving financial institution cannot allocate or otherwise decides to not accept a transfer, it sends a reversal. Additionally, a sender can request that a wire is reversed. However, the receiving financial institution has no obligation to honor the request. [Learn more about wire reversals](/documentation/wire-reversals) and how they work with Increase.

## Drawdown requests

Although Fedwire doesn’t support pulling funds, there’s a network-level primitive to request payment. This is called a [drawdown request](/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. If you wish to use drawdown requests, contact support@increase.com.

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

## Timing

[Fedwire operates according to a set schedule](https://www.frbservices.org/resources/financial-services/wires/operating-hours.html), opening at 9:00 PM ET on the preceding calendar day and closing at 7:00 PM ET. In practice, Fedwire can extend the operating hours. This typically happens in times of stress. Wires transfers are processed within the window that they’re submitted.

![Fedwire submission windows](/images/docs-wire-windows.png)

These times are subject to change, and different financial institutions may have their own cut-off times. Depending upon the bank you work with at Increase, wires may only be submitted within restricted hours. Also, keep in mind that holiday schedules could affect these times.

## Technical implementation

Fedwire uses a proprietary message format that’s comprised of tags. For example, the tag {2000} corresponds with the amount of the transfer. Below is an example of a typical wire transfer to a third party.

![Fedwire file](/images/docs-wire-message.png)

| Tag      | Description                                                                                                                                                                                                                                       |
| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `{1500}` | **Sender Supplied Information -** This contains a number of required technical attributes to help when processing the transfer such as the format version.                                                                                        |
| `{1510}` | **Type and Subtype Code -** This is used to determine the type and purpose of the transfer. `1000` refers to a basic value transaction between two bank customers.                                                                                |
| `{1520}` | **Input message accountability data (IMAD) -** The IMAD is an identifier. It's composed of the date (YYYYMMDD), the endpoint ID, and the sequence number.                                                                                         |
| `{2000}` | **Amount** - The amount, up to $10 billion less one penny.                                                                                                                                                                                        |
| `{3100}` | **Sender's Routing Number** - This is originating bank’s routing number.                                                                                                                                                                          |
| `{3400}` | **Receiver's Routing Number** - This is the routing number of the receiving bank.                                                                                                                                                                 |
| `{3600}` | **Business Function Code** - This specifies the business purpose of the transfer. For example, `CTR` refers to a customer transfer where the beneficiary is not a bank.                                                                           |
| `{4200}` | **Beneficiary information -** This is information about the recipient including their account number, name, and address.                                                                                                                          |
| `{5000}` | **Originator identification** - This is an identification code or message used to describe the sender. This can take the shape of a SWIFT Bank Identifier Code (BIC), Fed Routing Number, Passport Number, Tax Identification Number, and others. |
| `{6000}` | **Originator to Beneficiary Information** - This is a message to the recipient.                                                                                                                                                                   |

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 in stitutions. 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 is the dominant high-value transfer mechanism in the US and is the Federal Reserve’s real-time gross settlement network. Learn more about how Fedwire works and pitfalls to avoid.

Overview of Fedwire


# Idempotency keys

Increase's APIs include an optional creation parameter called the `Idempotency-Key`. This string parameter should be a unique value you pre-allocate in your system _before_ invoking the creation method. For example, you could use your application's Invoice ID for an [ACH Transfer](/documentation/api#ach-transfers) or your application's User ID for an [Entity](/documentation/api#entities).

We recommend setting the value for all POST requests. The value should be transmitted as the HTTP header `Idempotency-Key`.

You cannot re-use an `Idempotency-Key` across two objects—passing `Idempotency-Key` guarantees that at most one object is created per key. If Increase receives a second request with the same arguments and `Idempotency-Key`, we will return the object created during the first request and set the an HTTP response header `Idempotent-Replayed` to the value `true`.

Attempting to create a second, different, object with an already used `Idempotency-Key` will result in an HTTP 409 Conflict error with the `type` field set to `idempotency_key_already_used_error` and the `resource_id` set to the ID of the Object that is associated with that key.

Idempotency keys are only used for `POST` requests. `PATCH`, `GET`, and `DELETE` endpoints are inherently idempotent.

You can retrieve objects by their `Idempotency-Key`, too. Each list endpoint has an optional filter parameter `idempotency_key`. Passing an `idempotency_key` there will return an empty list, if that key is unused, or a list containing exactly one matching result.

## Recovering from errors

You can use the `Idempotency-Key` header to automatically and safely retry ephemeral errors. As long as the `Idempotency-Key` is set to the same value and the request is valid, we will eventually return a successful object to you. We recommend building support for automatic retries, especially for important endpoints like transfer creation.

We do not recommend building automatic solutions using reads of the list endpoint: instead retry your requests with the same parameters and the same `Idempotency-Key` and rely on idempotency to eventually deliver you a successful response.

## Examples

On the first successful request, Increase creates the Account Transfer.

```curl
curl -X POST https://api.increase.com/account_transfers
  -H "Idempotency-Key: test_001"
  -d $'{
      "account_id": "account_1",
      "destination_account_id": "account_2",
      "description": "My great transfer!"
  }'

200 OK
{
  "id": "account_transfer_abc123",
  "idempotency_key": "test_001"
  // ...
}
```

On the second request with the same `idempotency_key`, Increase returns the same object and sets a header indicating this response was replayed.

```curl
curl -X POST https://api.increase.com/account_transfers
  -H "Idempotency-Key: test_001"
  -d $'{
      "account_id": "account_1",
      "destination_account_id": "account_2",
      "description": "My great transfer!"
  }'

200 OK with header `Idempotent-Replayed: true`
{
  "id": "account_transfer_abc123", # The same ID!
  "idempotency_key": "test_001"
  // ...
}
```

If an idempotency key is re-used for different request arguments, the POST will fail.

```curl
curl -X POST https://api.increase.com/account_transfers
  -H "Idempotency-Key: test_001"
  -d $'{
      "account_id": "account_1",
      "destination_account_id": "account_2",
      "description": "A different description"
  }'

409 Conflict
{
  "status": 409,
  "type": "idempotency_key_already_used_error",
  "title": "The idempotency key submitted has already been used. Fetch the created object or use a different idempotency key.",
  "detail": null,
  "resource_id": "account_transfer_abc123"
}
```

You can also access the object with the list endpoint.

```curl
GET https://api.increase.com/account_transfers?idempotency_key=test_001

200 OK
{
  "data": [
    {
      "id": "account_transfer_abc123",
      "idempotency_key": "test_001"
      // ...
    }
  ]
}
```

## Deprecation notice

Prior to 2024, this functionality was only available on a subset of requests and was called `unique_identifier`. [Learn more about the older implementation.](/documentation/unique_identifiers)


Increase's money movement APIs include an optional creation parameter called idempotency_key. This can be used to associate a Transfer with a specific Invoice, Order, or Payment.

Idempotency keys


# 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 your system or that your system depends on
- Broken 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, and 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.


Learn more about the required policies and procedures for setting up a platform banking Program.

Information security


# Integrations

There are multiple ways to pull data from Increase. The most straightforward method is using [Exports](/documentation/exports) to manually retrieve large amounts of data, either through the API or directly from the Dashboard. To export data via the Dashboard, simply click the "Export" button above eligible lists.

In addition to manual exports, we support integrations with key partners, including **QuickBooks** and **Plaid**.

## QuickBooks integration

To connect to QuickBooks Online, you’ll need to create an **app-specific password** for QuickBooks. This credential allows QuickBooks to access your Transactions and Accounts in a read-only format.

### Steps to generate an app-specific password:

1. Navigate to the [Applications](https://dashboard.increase.com/settings/applications) page in your Dashboard settings.
2. Click “Add application” to generate your password.

![Create app-specific password](/images/docs-integrations-app-password.png)

Once you’ve generated the password, [log in to QuickBooks](https://app.qbo.intuit.com/app/banking) in a separate tab and follow the steps below:

### Connecting to QuickBooks:

1. Go to the [Bank Connections](https://app.qbo.intuit.com/app/bankconnect) page in QuickBooks. You can also find this by selecting "Transactions" → "Bank Transactions" from the sidebar, then clicking "Connect."
2. Search for Increase and enter the email and app-specific password credentials you generated from the Dashboard. Please note that your regular Increase password will not work for this step.
3. Select the Increase Accounts you want to connect, then complete the import process. You can always repeat this process later to add more Accounts.
   ![QuickBooks Integration Example](/images/docs-integrations-quickbooks.png)

## Plaid integration

Plaid allows third-party applications to gain read-write access to your Increase Accounts and Transactions. Typically, third-party apps will provide an option to link a bank account, which initiates the Plaid authorization flow. For more information on how to use Plaid, [refer to their documentation](https://support-my.plaid.com/hc/en-us/articles/4420182496151-How-do-I-use-Plaid).

### Using Plaid with Increase:

1. When prompted to select a financial institution, search for Increase.
2. You will be redirected to the Increase site, where you can authenticate with your Increase login credentials. We do not share your credentials with Plaid or the third-party application.

![Plaid Integration Example](/images/docs-integrations-plaid.png)

After authentication, select the specific Accounts you want to share. By default, Account Numbers will not be shared to ensure security. You may explicitly choose to share an Account Number, allowing the third-party application to transfer funds to and from the selected Account(s). A unique, Plaid-specific Account Number will be created for each Account you authorize. You can disable these Account Numbers at any time.

**Note:** Plaid requires that at least one Account Number be shared.

## Revoking access

You can revoke access to any third-party application directly from your Increase Dashboard.

### Steps to revoke access:

1. Navigate to the [Applications](https://dashboard.increase.com/settings/applications) page in your Dashboard settings.
2. View your authorized applications and click “Revoke” to permanently disable access.

![Revoke authorized applications](/images/docs-integrations-revoke.png)


Learn how to pull data from Increase using Exports, QuickBooks, and Plaid integrations. Step-by-step instructions for connecting accounts and revoking third-party access via the Increase Dashboard.

Integrations


# 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/developers/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 ${INCREASE_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.


If you're building an application for others to use with their Increase accounts, our API supports OAuth 2.0. Learn more about creating an OAuth application.

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 dependent on number of users, Cyber Liability $3mm/$5mm, Crime/3rd party crime $3mm. |


Learn more about the requirements for maintaining a full compliance program. This includes, but is not limited to, Bank Secrecy Act compliance and any applicable consumer protection regulation.

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.


Increase requires ongoing oversight for certain integrations. Learn more about these requirements.

Ongoing oversight


# Originating checks

## Lifecycle

![Check Transfer statuses](/images/docs-check-status.png)

| Status               | Description                                                |
| -------------------- | ---------------------------------------------------------- |
| `pending_approval`   | The transfer requires approval from a member of your team. |
| `pending_reviewing`  | The transfer is pending review by Increase.                |
| `pending_submission` | The transfer is pending submission to the check printer.   |
| `pending_mailing`    | The physical check is queued for mailing.                  |
| `mailed`             | The physical check has been mailed.                        |
| `deposited`          | The physical check has been deposited.                     |
| `returned`           | The transfer has been returned.                            |
| `canceled`           | The transfer has been canceled.                            |
| `rejected`           | The transfer has been rejected.                            |
| `stopped`            | A stop-payment was requested for this check.               |
| `requires_attention` | The transfer requires attention from an Increase operator. |

## Sending a Check Transfer with Increase

Originating a Check Transfer via the Increase API kicks off several steps involving you, Increase, the Federal Reserve, and the receiving bank.

1. You make a `POST /check_transfers` call with the [details](https://increase.com/documentation/api#create-a-check-transfer) of how much you'd like to send and data about the recipient. A Check Transfer is created with a status of `pending_reviewing`.
2. A Pending Transaction is immediately created for the full amount of the transfer in order to hold funds.
3. Once the transfer passes through internal reviews, the status updates to `pending_submission`.
4. When the file is submitted to the check printer, Increase updates the Check Transfer object with its `submission` [](https://increase.com/documentation/api#real-time-payments-transfer-object.submission)[details](https://increase.com/documentation/api#check-transfer-object.submission) and the status is updated to `submitted`.
5. When the check is mailed by the printer, Increase updates the Check Transfer object with its `mailing` [details](https://increase.com/documentation/api#check-transfer-object.mailing) and the status is updated to `mailed`.
6. Once the recipient deposits the check, Increase creates an Inbound Check Deposit object and decides if the deposit should be allowed. If so, we populate the Check Transfer object’s `accepted_inbound_deposit_id` attribute and update its status to `deposited`. (For more on this, see “Evaluating deposit attempts” below.)
7. A Transaction is immediately created for the full amount of the transfer and funds are removed from your Account. The Pending Transaction is marked as `complete`.

## Printing your own Checks

By default Increase will print and mail your checks and you will be able to access all `physical_check` [details](https://increase.com/documentation/api#check-transfer-object.physical_check) on the Check Transfer object. A typical printed check will look like the image below:

![Physical Check image](/images/docs-check-image.png)

Alternatively, you can print your own checks by setting the `fulfillment_method` to `third_party` when creating a Check Transfer. When this is set, the Check Transfer status will be set to `mailed`and you will be responsible for printing and mailing a check with the provided account number, routing number, check number, and amount.

## Stop payment requests

You can make a stop-payment request on a Check Transfer any time before a check is deposited. After a request has been sent, the check is immediately voided and the Check Transfer status is updated to `stopped` with additional `stop_payment_request` [details](https://increase.com/documentation/api#check-transfer-object.stop_payment_request) provided. The Pending Transaction status updates to `complete`, and no additional Transactions are created.

## Evaluating deposit attempts

When a recipient deposits a check, we create an Inbound Check Deposit object and send an `inbound_check_deposit.created` webhook for it. This object will start in a `pending` status and have an `automatically_resolves_at` timestamp attribute (by default, 1 hour after the object’s `created_at`). After that time elapses, we evaluate a few conditions:

- Is either the Account Number or Account that this deposit points to closed or inactive?
- Has the Check Transfer been stopped?
- Has the Check Transfer already been successfully deposited?
- Does the Account have an insufficient current balance to cover the deposit?

If the answer to any of these questions is yes, we decline the deposit attempt:

- the Inbound Check Deposit transitions to `status: declined`
- a Declined Transaction with a `source.category` of `check_decline` is created.
- Under the hood, Increase sends a return to the depositing bank. The recipient will see a returned check and not receive funds. (They can also tell their bank to retry the deposit.)

Otherwise, we accept the deposit attempt:

- the Inbound Check Deposit transitions to `status: accepted`
- a Transaction with a `source.category` of `check_transfer_deposit` is created.
- the Pending Transaction associated with the Check Transfer is completed.

### Custom evaluation logic

You can use the delay between the Inbound Check Deposit’s `created_at` and `automatically_resolves_at` to fix any issues with the deposit - for example, you can just-in-time fund the underlying account via an Account Transfer if its balance is low. You can also use arbitrary logic inside your application to evaluate the deposit attempt yourself during that window. All of the information Increase receives about the check from the depositing bank, including deposit scan images, is included on the `inbound_check_deposit` object. You can decline the attempt via the API by making a `POST` to `/inbound_check_deposits/:id/decline`. (If you decide to approve the deposit, take no action and it will be automatically resolved as described above).

## Approvals

For transfers that require approval from another team member, the Check Transfer is created with a status of `pending_approval` and a Pending Transaction is created to hold funds.

If the transfer is approved, the Check Transfer object updates with its `approval` [details](https://increase.com/documentation/api#check-transfer-object.approval), the status is changed to `pending_reviewing`, and things progress normally.

If the transfer is not approved, the Check Transfer object updates with its `cancellation` [details](https://increase.com/documentation/api#check-transfer-object.cancellation) and the status is changed to `canceled`. The Pending Transaction status updates to `complete`, no transfer information is submitted, and no additional Transactions are created.

## Reviews and rejections

Occasionally a Check Transfer will need to be manually reviewed by an Increase operator. When this occurs the Check Transfer object status will be set to `pending_reviewing` .

Once reviewed, the status changes to `pending_submission` and things progress normally. However, rarely a Check Transfer may be rejected by Increase. When this occurs the Check Transfer object status updates to `rejected`, no transfer information is submitted to the printer, and no additional Transactions are created.

## Checks without Check Transfers

While for most cases we recommend using Check Transfers for ease of bookkeeping and fraud prevention, in some cases you may want to process checks where you don’t know the amount up front (such as printing your own checkbooks). To do this, all you need is an Account Number with the `inbound_checks.status` property set to `allowed`. Then, print and fulfill your own checks with that account and routing number (and whatever other details you need). When a recipient deposits one of these checks, we’ll create an `inbound_check_deposit` object as described above (the `check_transfer` property on this object will be null), run the same evaluation logic, and create a Transaction or Declined Transaction. If you pursue this approach, we recommend implementing advanced evaluation logic as described above to make sure the deposits you see are what you expect.


Learn more about the lifecycle of a Check Transfer and how to originate physical checks.

Originating checks


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

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

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


If you’re looking to pull money from one party to pay another, you’re probably building a payments company. Learn more about how to structure your funds flows.

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.
- Share these details with us.

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:

| Ownership                                                              | 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 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).


If you’re moving your customer’s money, you likely already know about some of the compliance requirements. This guide addresses how to implement a few of these requirements.

Platform implementation guide


# Programmatic card processing

Increase directly connects to the Visa Direct Exchange network, ensuring highly available processing of card transactions with no layers in-between Increase and Visa. You can start creating virtual and physical Increase cards as soon as you sign up. Each card is backed by the balance of its underlying account. By default, all valid card authorizations are approved as long as the underlying balance of the card’s account is sufficient. For more complicated use cases, where you would like granular control over which authorizations are approved and which are declined, we’ll send you a webhook and let you decide.

Throughout this guide we’ll walk through programmatically creating a card and testing it out, first without and then with real-time webhooks. As you go through the commands, you can follow the activity visually in your [Increase Dashboard](https://dashboard.increase.com/) by toggling on sandbox mode:

![Sandbox toggle](/images/sandbox-toggle.png)

## Set-up

To follow the `curl` commands, make sure to set the following environment variables:

```curl
export INCREASE_URL="https://sandbox.increase.com"
export INCREASE_API_KEY="<sandbox key from https://dashboard.increase.com/developers/api_keys>"
```

All cards belong to an `Account` so we’ll also need to create one of those:

```curl
curl -X "POST" \
  --url "${INCREASE_URL}/accounts" \
  -H "Authorization: Bearer ${INCREASE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d $'{
    "name": "Cards"
  }'

=> {"id": "sandbox_account_...", ...}

export INCREASE_ACCOUNT = "sandbox_account_..."
```

You can also do this in the Dashboard at https://dashboard.increase.com/accounts.

## Create a card

To create a card, we’ll provide the account the card belongs to, a description of the card, and a billing address.

```curl
curl -X "POST" \
  --url "${INCREASE_URL}/cards" \
  -H "Authorization: Bearer ${INCREASE_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d $'{
    "account_id": "account_...",
    "description": "Card for Ian Crease",
    "billing_address": {
      "line1": "33 Liberty Street",
      "city": "San Francisco",
      "state": "CA",
      "postal_code": "94132"
    }
  }'

=> {
  "id": "sandbox_card_oubs0hwk5rn6knuecxg2",
  ...
}
```

This gets us the Increase ID of the card, `card_oubs0hwk5rn6knuecxg2`. When we’re ready to show the card number to a customer, you’ll retrieve it with the `/cards/card_.../details` endpoint. For now, we’ll move on to simulating an authorization on the card.

## Simulating an authorization

To simulate an authorization we’ll first need to top up our account with funds. We’ll do that with the [ACH simulation endpoint](https://increase.com/documentation/api#simulate-an-ach-transfer-to-your-account). To simulate moving funds into an account we’ll first need an account number where the funds can land. Increase lets you create as many account numbers as you want for each of your accounts—a common strategy is for example to create one account number for each of your vendors.

```curl
# First create an account number where the ACH funds will land:
curl -X "POST" \
  --url "${INCREASE_URL}/account_numbers" \
  -H "Authorization: Bearer ${INCREASE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d $'{
    "account_id": "ACCOUNT_ID_GOES",
    "name": "Card payments"
  }'

=> {"id": "sandbox_account_number_...", ...}

# Then move some funds into the account:
curl -X "POST" \
  --url "${INCREASE_URL}/simulations/inbound_ach_transfers" \
  -H "Authorization: Bearer ${INCREASE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d $'{
    "account_number_id": "account_number_v18nkfqm6afpsrvy82b2",
    "amount": 100000
  }'
```

At this point we have funded our sandbox account and can simulate usage of the card at a store with the [card authorization simulation endpoint](https://increase.com/documentation/api#simulate-an-authorization-on-a-card):

```curl
curl -X "POST" \
  --url "${INCREASE_URL}/simulations/card_authorizations" \
  -H "Authorization: Bearer ${INCREASE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d $'{
    "amount": 1000,
    "card_id": "card_oubs0hwk5rn6knuecxg2"
  }'

=> {
  "pending_transaction": {
    // ...
    "id": "sandbox_pending_transaction_bxenyrfmlvpfcdhne1go"
  }
}
```

If we navigate to the [cards page](https://dashboard.increase.com/cards) in the Dashboard and click on our card we should now see the following:

![Card transactions](/images/card-transactions.png)

This is what you’ll see immediately after someone uses one of your cards. At this point the authorization is pending and should only be reflected in your available balance:

![Available balance](/images/available-balance-pending.png)

## Simulating a card settlement

Once the transaction clears, usually later that day, your current balance will go down as well. Since we’re in our sandbox environment we can speed up the process by [simulating a card settlement](https://increase.com/documentation/api#simulate-settling-a-card-authorization):

```curl
curl -X "POST" \
  --url "${INCREASE_URL}/simulations/card_settlements" \
  -H "Authorization: Bearer ${INCREASE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d $'{
    "card_id": "sandbox_card_imnigzlhgsgykpzzkcwc",
    "pending_transaction_id": "sandbox_pending_transaction_bxenyrfmlvpfcdhne1go"
  }'
```

Navigating back to your card detail page, the transaction should now show as a `Card Settlement` instead:

![Card transactions settled](/images/card-transactions-settled.png)

And your balance:

![Available balance](/images/available-balance-settled.png)

## Card payment flows

The majority of your card payments will likely follow these two steps: an authorization followed by a settlement. You will also sometimes see authorizations get reversed, e.g., in the event of a refund before a settlement, and even incremented when the original authorization amount needs to be increased. The `[/card_payments](https://increase.com/documentation/api#card-payments)` [API](https://increase.com/documentation/api#card-payments) is a useful way to keep track of the state of an authorization:

```curl
curl --url "${INCREASE_URL}/card_payments?account_id=sandbox_account_uhatomeo6ndzqhljge3z" \
  -H "Authorization: Bearer ${INCREASE_API_KEY}"

{
  "data": [
    {
      "id": "sandbox_card_payment_qctt5lw3zese8eujb4kr",
      "created_at": "2024-01-11T21:28:35Z",
      "account_id": "sandbox_account_uhatomeo6ndzqhljge3z",
      "card_id": "sandbox_card_imnigzlhgsgykpzzkcwc",
      "elements": [
        {
          "category": "card_authorization",
          "card_authorization": {
            "id": "sandbox_card_authorization_imbwqnss4l1jpefp01uj",
            "card_payment_id": "sandbox_card_payment_qctt5lw3zese8eujb4kr",
            "merchant_acceptor_id": "5200291094",
            "merchant_descriptor": "MBLREHXEWT",
            "merchant_category_code": "5734",
            "merchant_city": "SANFRANCISCO",
            "merchant_country": "US",
            "digital_wallet_token_id": null,
            "physical_card_id": null,
            "verification": {
              "cardholder_address": {
                "provided_postal_code": null,
                "provided_line1": null,
                "actual_postal_code": null,
                "actual_line1": null,
                "result": "not_checked"
              },
              "card_verification_code": {
                "result": "not_checked"
              }
            },
            "network_identifiers": {
              "transaction_id": "333325222528937",
              "trace_number": "454885",
              "retrieval_reference_number": "320337291607"
            },
            "amount": 1000,
            "class_name": "card_authorization",
            "currency": "USD",
            "direction": "settlement",
            "processing_category": "purchase",
            "expires_at": "2024-01-19T12:00:00Z",
            "real_time_decision_id": null,
            "pending_transaction_id": "sandbox_pending_transaction_bxenyrfmlvpfcdhne1go",
            "type": "card_authorization"
          },
          "created_at": "2024-01-11T21:28:35Z"
        },
        {
          "category": "card_settlement",
          "card_settlement": {
            "id": "sandbox_card_settlement_vqmulmnzjpapzufybqqa",
            "card_payment_id": "sandbox_card_payment_qctt5lw3zese8eujb4kr",
            "card_authorization": "sandbox_card_authorization_imbwqnss4l1jpefp01uj",
            "amount": 1000,
            "currency": "USD",
            "presentment_amount": 1000,
            "presentment_currency": "USD",
            "class_name": "card_settlement",
            "merchant_acceptor_id": "NBURKHVRKWCMLMQ",
            "merchant_city": "SANFRANCISCO",
            "merchant_state": null,
            "merchant_country": "US",
            "merchant_name": "BASKZBJO",
            "merchant_category_code": "5734",
            "transaction_id": "sandbox_transaction_sgi3pokksyuxjsrg51ug",
            "pending_transaction_id": "sandbox_pending_transaction_bxenyrfmlvpfcdhne1go",
            "interchange": null,
            "purchase_details": null,
            "network_identifiers": {
              "transaction_id": "353029890989561",
              "acquirer_reference_number": "08030532720715529117083",
              "acquirer_business_id": "93651339"
            },
            "type": "card_settlement"
          },
          "created_at": "2024-01-11T21:33:39Z"
        }
      ],
      "state": {
        "authorized_amount": 1000,
        "incremented_amount": 0,
        "reversed_amount": 0,
        "fuel_confirmed_amount": 0,
        "settled_amount": 1000
      },
      "type": "card_payment"
    }
  ]
}
```

Or in the Dashboard:

![Card payment](/images/card-payment.png)

## Real-time decisions

If you’re managing cards programmatically, you might also want to control the outcome of each authorization—e.g., to only allow payments at specific stores, or below certain limits. To do so you’ll use Increase’s [Real-Time Decisions](https://increase.com/documentation/api#real-time-decisions) API together with a webhook [event subscription](https://increase.com/documentation/api#create-an-event-subscription) for `real_time_decision.card_authorization_requested`.

Let’s look at an example. We’ll build a quick application where we’ll only approve authorizations with a merchant category code of 5812 (restaurants) with a merchant city of San Francisco. We’ll use our [Kotlin SDK](https://github.com/Increase/increase-kotlin).

**Set-up event subscription**
To begin, we’ll create an event subscription for `real_time_decision.card_authorization_requested`. We’ll use [localtunnel](https://localtunnel.me/) to expose our local server to the internet which will give us a URL we define:

```curl
lt --subdomain your-increase-webhook-testing-url --port 4567
```

Then we can create the event subscription pointing to this URL:

```curl
curl -X "POST" \
  --url "${INCREASE_URL}/event_subscriptions" \
  -H "Authorization: Bearer ${INCREASE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d $'{
    "url": "https://https://your-increase-webhook-testing-url.loca.lt"
    "secret": "your webhook secret",
    "category": "real_time_decision.card_authorization_requested"
 }'
```

This will make sure we only get events of the type `real_time_decision.card_authorization_requested`. For a fully fledged application there are other webhooks that can be useful as well, such as `card_payment.updated`, but we’ll start here.

**Webhook implementation**
We’ll aim to do the following:

1\. Verify the incoming webhook signature with our webhook secret

https://increase.com/documentation/webhooks#securing-your-webhook-endpoint-recommended

2\. Retrieve the real-time decision referenced in the event

https://increase.com/documentation/api#retrieve-a-real-time-decision

3\. Action the real-time decision with either an approval or decline

```kotlin
import com.google.common.collect.ImmutableListMultimap
import io.javalin.Javalin
import com.increase.api.client.okhttp.IncreaseOkHttpClient
import com.increase.api.models.Event
import com.increase.api.models.RealTimeDecisionActionParams
import com.increase.api.models.RealTimeDecisionRetrieveParams
import io.javalin.http.Context

const val MERCHANT_CATEGORY_CODE = "5812"
const val MERCHANT_CITY = "San Francisco"

fun main() {
    val client = IncreaseOkHttpClient.builder()
        .apiKey(API_KEY)
        .webhookSecret(WEBHOOK_SECRET)
        .build()

    Javalin.create()
        .post("/webhook", fun(ctx: Context) {
            val headers = ImmutableListMultimap.copyOf(ctx.headerMap().entries)
            val payload = client.webhooks().unwrap(ctx.body(), headers, null)
            val event = payload.convert<Event>()!!
            if (event.category() != Event.Category.REAL_TIME_DECISION_CARD_AUTHORIZATION_REQUESTED) {
                println("Ignoring other event types ${event.category()}")
                ctx.status(200)
                return
            }

            val realTimeDecision = client.realTimeDecisions().retrieve(
                RealTimeDecisionRetrieveParams.builder().realTimeDecisionId(event.associatedObjectId()).build()
            )

            val cardAuthorization = realTimeDecision.cardAuthorization()!!
            val isApproved = cardAuthorization.merchantCategoryCode() == MERCHANT_CATEGORY_CODE &&
                    cardAuthorization.merchantCity() == MERCHANT_CITY
            val decision =
                if (isApproved) {
                    RealTimeDecisionActionParams.CardAuthorization.Decision.APPROVE
                } else {
                    RealTimeDecisionActionParams.CardAuthorization.Decision.DECLINE
                }

            client.realTimeDecisions().action(
                RealTimeDecisionActionParams.builder().realTimeDecisionId(realTimeDecision.id()).cardAuthorization(
                    RealTimeDecisionActionParams.CardAuthorization.builder().decision(
                        decision
                    ).build()
                ).build()
            )

            ctx.status(200)
        })
        .start(4567)
}
```

**Testing our webhook**
To test our webhooks, we’ll want to simulate more authorizations—we’ll start with one we’ll be declining:

```curl
curl -X "POST" \
  --url "${INCREASE_URL}/simulations/card_authorizations" \
  -H "Authorization: Bearer ${INCREASE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d $'{
    "amount": 1250,
    "card_id": "sandbox_card_imnigzlhgsgykpzzkcwc",
    "merchant_category_code": "5942",
    "merchant_descriptor": "Books 📚",
    "merchant_city": "Seattle"
  }'

=> {
  "declined_transaction": {
    "account_id": "sandbox_account_uhatomeo6ndzqhljge3z",
    "amount": -1250,
    "currency": "USD",
    "created_at": "2024-01-12T04:23:48Z",
    "date": "2024-01-12",
    "description": "Books 📚",
    "id": "sandbox_declined_transaction_fimya9x1xdintmgyz5tu",
    "path": "/declined_transactions/sandbox_declined_transaction_fimya9x1xdintmgyz5tu",
    "route_id": "sandbox_card_imnigzlhgsgykpzzkcwc",
    "route_type": "card",
    "source": {
      // ...
      "id": "sandbox_card_decline_pmtriejsd1cn9vv853ls",
      "amount": 1250,
      "class_name": "card_decline",
      "reason": "webhook_declined",
      "merchant_acceptor_id": "0315399943",
      "merchant_descriptor": "Books 📚",
      "merchant_category_code": "5942",
      "merchant_city": "Seattle",
      "merchant_country": "US",
      "real_time_decision_id": "sandbox_real_time_decision_syxbufwmreypjo78ekag"
    },
    "type": "declined_transaction"
  },
  "type": "inbound_card_authorization_simulation_result"
}
```

And then one we’ll want our application to approve:

```curl
curl -X "POST" \
  --url "${INCREASE_URL}/simulations/card_authorizations" \
  -H "Authorization: Bearer ${INCREASE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d $'{
    "amount": 1250,
    "card_id": "sandbox_card_imnigzlhgsgykpzzkcwc",
    "merchant_category_code": "5812",
    "merchant_descriptor": "Z&Y 🍜",
    "merchant_city": "San Francisco"
  }'

=> {
  "pending_transaction": {
    "account_id": "sandbox_account_uhatomeo6ndzqhljge3z",
    "amount": -1250,
    "currency": "USD",
    "status": "pending",
    "type": "pending_transaction"
    // ....
  },
  "type": "inbound_card_authorization_simulation_result"
}
```

![Real time decisions](/images/real-time-decisions.png)


Increase directly connects to the Visa Direct Exchange network, ensuring highly available processing of card transactions with no layers in-between Increase and Visa. You can start creating virtual and physical Increase cards as soon as you sign up. Each card is backed by the balance of its underlying account. By default, all valid card authorizations are approved as long as the underlying balance of the card’s account is sufficient. For more complicated use cases, where you would like granular control over which authorizations are approved and which are declined, we’ll send you a webhook and let you decide.

Programmatic card processing


# Programs

#### Your Increase team can organize its Accounts into groups called Programs. Each Program can have unique compliance or commerical terms.

---

Every team has a Program called "Commercial Banking" that you can use to hold your company's own funds. If you are managing funds on behalf of your customers, we will work together to create additional Programs for you.

A Program controls much of the configuration for all of the Accounts belonging to it. Some of the things that a Program controls are:

- Fees
- Interest rates
- Required compliance reporting
- Transfer approval rules
- Account titling and structure

## Limiting data access

You can limit the account and transaction data a team member can access in the Dashboard. Data permissions are scoped by Program—you can select all or a subset.

For example, this can be helpful if you have a team managing an FBO program, but don’t want to provide access to your commercial accounts. To modify a team member’s data access, visit the [team page](https://dashboard.increase.com/settings/team) in the Dashboard settings.

![Limit data permissions](/images/permissions-data-access.png)

[Learn more about roles and permissions.](/documentation/roles)


Programs determine the compliance and commercial terms of Accounts.

Programs


# Real-Time Decisions

We recommend first reading our [Webhooks guide](https://increase.com/documentation/webhooks) for background.

## Overview

Occasionally Increase needs to know what action to take on a user-initiated request in real time. The canonical example of this is when a user tries to use their card and Increase has to decide to approve the authorization or not. When this happens, we'll create a [Real-Time Decision](https://increase.com/documentation/api#real-time-decisions) object in the API and send you a special real-time webhook.

## Real-time webhooks

Real-time webhooks behave generally similarly to regular webhooks, but are delivered with zero latency from when they’re initiated. Additionally, they’re only delivered to a single [Event Subscription](https://increase.com/documentation/api#event-subscriptions) webhook. You must explicitly create an Event Subscription with a [`selected_event_category`](https://increase.com/documentation/api#event-subscription-object.selected_event_category) of that specific event category, and only one Event Subscription with a [`selected_event_category`](https://increase.com/documentation/api#event-subscription-object.selected_event_category) that occurs in real-time can be active at once.

## Real-time decisions

Real-Time Decisions are a regular API resource in the Increase API. When we need a decision from your application, we will create one, create an [Event](https://increase.com/documentation/api#events) to indicate that it has been created, and send that Event to you in real-time via webhook as described above. At this point, your application will have 2-4 seconds (depending on the type of decision) to make a decision. You tell us your decision by `POST`ing to the Real-Time Decision action endpoint:

    POST https://api.increase.com/real_time_decisions/{real_time_decision_id}/action

Depending on the type of decision, additional metadata might be required. For example, if a user is trying to add their card to their Apple Pay Wallet, your application might need to reply with the artwork the user should see. These metadata fields are exposed as properties of the above API endpoint.

It’s currently required that your application complete this HTTP request _before_ responding to the webhook.

## Example: responding to card authorizations in real time

Start by [creating an Event Subscription](https://increase.com/documentation/api#create-an-event-subscription) via the API with `selected_event_category:` `real_time_decision.card_authorization_requested`. This webhook listener will only receive real-time authorization webhooks. The event payload your application will see looks like:

```
  {
    associated_object_id: string,
    associated_object_type: 'real_time_decision',
    category: 'real_time_decision.card_authorization_requested',
    created_at: string,
    id: string,
    type: 'event'
  }
```

This event references a Real-Time Decision object in our API.

In your webhook implementation, you should:

- Make a `GET` request to `https://api.increase.com/real_time_decisions/{id}`, replacing `{id}` with the value of `associated_object_id` in the webhook event payload. The response will look like:

  ```
  {
    id: string;
    created_at: string,
    timeout_at: string,
    status: 'pending',
    category: 'card_authorization_requested',
    card_authorization: {
      decision: null,
      card_id: string,
      account_id: string,
      presentment_amount: integer,
      presentment_currency: string,
      settlement_amount: integer,
      settlement_currency: string,
      merchant_category_code: string,
      merchant_acceptor_id: string,
      merchant_city: string | null,
      merchant_country: string,
      merchant_descriptor: string,
    },
    type: 'real_time_decision',
  }
  ```

- Decide if you want to approve or reject the authorization based on its properties.
- Make a `POST` request to `https://api.increase.com/real_time_decisions/{id}/action` to approve or decline the authorization with a JSON payload of:

  ```
  {
    "card_authorization": {
      "decision": "approve" | "decline"
    }
  }
  ```

- Respond with a 200 status code and any body. Note that you must synchronously wait for your approve/decline `POST` request to complete before your webhook responds with a 200.

## Notes

Because of the short timeout, we won't retry webhooks that don't respond with a 200.

An easy way to test your webhook is to create a Card in the Increase Dashboard and then try to charge it in the Stripe dashboard. If you don't feel like going over live payment networks, you can also [simulate an authorization](https://increase.com/documentation/api#simulate-an-authorization-on-a-card) via our API in the sandbox. (Note you'll need to create a separate Event Subscription in the sandbox before this will work.)


Occasionally Increase needs to know what action to take on a user-initiated request in real time. The canonical example of this is when a user tries to use their card and Increase has to decide to approve the authorization or not. When this happens, we’ll create a Real-Time Decision object in the API and send you a special real-time webhook.

Real-Time Decisions


# Overview of Real-Time Payments

#### An introductory guide explaining Real-Time Payments, how they function, and key concepts for operating an RTP integration.

Real-Time Payments is a USD only instant payment service developed by The Clearing House. It reaches roughly 65% of US depository accounts.

## How Real-Time Payments work

Each participating financial institution maintains a balance in a shared New York Federal Reserve account to fund their account holders’ activity. This allows interbank settlement to happen immediately. Unlike wires, Real-Time Payments doesn’t have a culture of manual intervention. This leads to more immediate and deterministic operations. Like wires, Real-Time Payments are irrevocable. To understand how Real-Time Payments work, we can discuss it in a few stages.

![Real-Time Payments process](/images/docs-rtp-process.png)

**Initiation**: A sender creates a Real-Time Payment, which includes mandatory details like the recipient account number, routing number, amount, and remittance information. Unlike other types of transfers, Real-Time Payments also require that the sender provide their own account number.

**Submission**: The originating financial institution verifies the transfer details, ensuring the sender has sufficient funds to cover the transaction. Then the transfer details are submitted to The Clearing House for review. Unlike ACH, these transfers are not batched and are submitted on a transaction-by-transaction basis.

**Verification**: The Clearing House verifies that the transfer details are correct and then forwards the information to the receiving financial institution. If they are unable to complete the transfer, it is rejected and the originating financial institution receives a notification of the failed transfer.

**Acknowledgement**: The receiving financial institution confirms they have received the message and accepts the transfer. The receiving institution can also reject the transfer for a variety of reasons.

**Settlement**: Following acknowledgement, The Clearing House immediately moves funds between the originating and receiving financial institutions' accounts.

**Confirmation**: After the transfer is processed, both the sender and the receiver receive immediate notifications about the transaction. This entire process happens within a matter of seconds.

## Rejections, not reversals

Real-Time Payments transfers can fail. Common reasons are that the receiving account number details aren’t valid or the account has been closed. Once they succeed, Real-Time Payments cannot be reversed or returned.

## Request for Payment

Real-Time Payments supports a "Request for Payment" mechanism. This feature allows beneficiaries to request funds from another party. The user experience varies by institution.

## Availability

The network is always available, excepting scheduled downtime for maintenance. Transactions are confirmed by receiving institutions in real-time.

## Support

Real-Time Payments works well but because support isn’t as widespread as ACH you need a fallback. You can see if a routing number supports Real-Time Payments using our [Routing Number endpoint](/documentation/api#routing-numbers)).

## Message format

Real-Time Payments use the [ISO 20022 messaging format](https://en.wikipedia.org/wiki/ISO_20022), which defines a wide ontology of financial services metadata. The FedNow service uses the same format.

## Limits

Real-Time Payments are subject to limits by The Clearing House. As of August 2023, [the per-transaction limit is $1,000,000](https://www.theclearinghouse.org/payment-systems/Articles/2022/04/TCH_Raise_RTP_Network_Transaction_Limit_1Million_04-06-2022), the same as the Nacha same-day clearing.

## Zelle and related networks

Zelle is a digital payments network with a similar profile. [Zelle payments can be settled over the Real-Time Payments network](https://www.theclearinghouse.org/payment-systems/articles/2021/02/02252021_zelle-over-rtp-network), but they are not interoperable.


Real-Time Payments is a instant payment service developed by The Clearing House. It reaches roughly 65% of US depository accounts. Learn more about how Real-Time Payments work and pitfalls to avoid.

Overview of Real-Time Payments


# Receiving an ACH transfer

An ACH transfer sent to your Increase account creates an [Inbound ACH Transfer](/documentation/api#inbound-ach-transfers). When an Inbound ACH Transfer is created or updated, your application can receive a [webhook Event](/documentation/webhooks#consuming-events). You can action on these events to decline or return the Inbound ACH Transfer as needed. This means you can verify these transfers and manage funds when you see an Event come in.

Details about creating an ACH Transfer are described [here](/documentation/sending-ach-transfers).

## Lifecycle

![Inbound ACH Transfer statuses](/images/docs-ach-inbound-status.png)

| Status     | Description                                                                                          |
| ---------- | ---------------------------------------------------------------------------------------------------- |
| `pending`  | The Inbound ACH Transfer is awaiting action. It will transition automatically if no action is taken. |
| `declined` | The Inbound ACH Transfer has been declined.                                                          |
| `accepted` | The Inbound ACH Transfer is accepted.                                                                |
| `returned` | The Inbound ACH Transfer has been returned.                                                          |

## Actioning

The Inbound ACH Transfer is created in a `pending` state. There's a one hour window where you can decline the transfer.

After an hour if you don’t take any action the transfer will automatically resolve. If the transfer moves into an `accepted` state, money moves in your Increase Account and a [Transaction](/documentation/transactions-transfers#transactions-and-transfers) is created. Conversely, the transfer could be automatically rejected for a variety of reasons (insufficient funds, incorrect account details, etc.) and move into a `declined` state. If the transfer is accepted, you can also action to return it.

## Declining

When an Inbound ACH Transfer is in the `pending` state, you can decline it by using the `POST /inbound_ach_transfers/:inbound_ach_transfer_id/decline` [endpoint](/documentation/api#decline-an-inbound-ach-transfer).

It’s useful to note that you’ll have a window of an hour by default to action on a `pending` transfer before it automatically resolves to the next status and is no longer eligible to be declined. You can listen for the Inbound ACH Transfer created webhook Event, run application logic, and hit this endpoint as needed.

## Returning

When an Inbound ACH Transfer is in the `accepted` state, you can return it by using the `POST /inbound_ach_transfers/:inbound_ach_transfer_id/transfer_return` [endpoint](/documentation/api#return-an-inbound-ach-transfer).

It’s useful to note that Inbound ACH Transfers can only be returned up to a cutoff date of 2 days after the transfer’s effective date. You can listen for the Inbound ACH Transfer updated webhook Event, run application logic, and hit this endpoint as needed.

## Examples

### Preventing an insufficient funds Inbound ACH Return

Your vendor sends you an ACH Debit for $100.

- An Inbound ACH Transfer is created in a `pending` state for $100.
- An Inbound ACH Transfer created Event is sent to your webhook subscription.

Upon receiving the Event, your application identifies that your account lacks the required funds (you only have $30) to complete the transfer. If you did nothing the transfer would be returned for insufficient funds. You decide to transfer $70 into the account to bring the balance up to $100.

- A Transaction is created for $70 into your account.

After the hour cutoff, the Inbound ACH Transfer automatically resolves.

- The Inbound ACH Transfer moves to an `accepted` state.
- A Transaction is created for -$100 to pay the vendor.

### Rejecting an unauthorized transfer

An unauthorized party sends you an ACH Debit for $100.

- An Inbound ACH Transfer is created in a `pending` state for $100.
- An Inbound ACH Transfer created Event is sent to your webhook subscription.

Your application listens for the Event and sees the unexpected transfer. You decide to decline the transfer and no money movement in your Increase account occurs.

- The Inbound ACH Transfer moves to a `declined` state.

### Returning a duplicate transfer

A buyer wants to settle a $100 bill, but instead of sending one ACH Credit two are accidentally sent.

- An Inbound ACH Transfer is created in a `pending` state for $100.
- An Inbound ACH Transfer created Event is sent to your webhook subscription.
- An Inbound ACH Transfer is created in a `pending` state for $100.
- An Inbound ACH Transfer created Event is sent to your webhook subscription.

An hour passes and no action is taken, the transfers resolve to `accepted` and money moves.

- The Inbound ACH Transfer moves to an `accepted` state and an updated Event is sent to your webhook subscription.
- A Transaction is created for $100 to settle the buyer's bill.
- The second Inbound ACH Transfer moves to an `accepted` state and an updated Event is sent to your webhook subscription.
- A second Transaction is created for $100.

Your application listens for the updated Event and notices the duplicate transfer. You decide to return the duplicate to your buyer.

- The second Inbound ACH Transfer moves to a `returned` state.
- A transaction for -$100 is created.


When an Inbound ACH Transfer is created or updated, your application can receive a webhook Event. You can use these Events to automatically decline or return the Inbound ACH Transfer as needed.

Receiving


# Receiving a Real-Time Payment

When a Real-Time Payment is sent to your Account, Increase will immediately create a Transaction as long as the Account is `open`, and the Account Number is `active` and can receive deposits. If you’d like to programmatically approve or decline inbound Real-Time Payments using webhook Events, please reach out to support@increase.com


Learn more about receiving Real-Time Payments.


# Receiving a wire transfer

A wire transfer sent to your Increase Account creates an [Inbound Wire Transfer.](/documentation/api#inbound-wire-transfers)

## Lifecycle

![Inbound Wire Transfer statuses](/images/docs-wire-inbound-status.png)

| Status     | Description                                                                                                                                       |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `pending`  | The transfer remains in a pending state for a very short period of time while details are verified by Increase. It will auto resolve to accepted. |
| `accepted` | The transfer was accepted and funds were added to your Account                                                                                    |
| `declined` | The transfer was immediately declined and automatically reversed.                                                                                 |
| `reversed` | The transfer was reversed by Increase after funds initially settled.                                                                              |

## Receiving a wire transfer with Increase

Initially an Inbound Wire Transfer has status of `pending` for a very short period of time. While pending, Increase checks to see if the transfer should be automatically declined. This will occur if:

- The Account Number is not active
- The Account can’t receive deposits
- The Account is closed.

If a wire transfer is declined, the Inbound Wire Transfer status is updated to `declined` and the funds are sent back to the originating institution. No Transactions are created on your Account.

If the Inbound Wire Transfer is not declined, it’s status is updated to `accepted` and a Transaction crediting your Account is immediately created.

If an Inbound Wire Transfer is reversed after the funds have settled, its status will update to `reversed`. If you’d like to reverse an Inbound Wire Transfer, contact support@increase.com.

## Actioning inbound wires

Increase provides the ability to programmatically approve or reverse Inbound Wire Transfers. When an Inbound Wire Transfer is created or updated, your application can receive a [webhook Event](/documentation/webhooks#consuming-events). You can action on these Events to approve or reverse the Inbound Wire Transfer as needed. This allows you to verify transfers and manage funds when you see an Event come in.

This feature is currently gated. Please contact support@increase.com if you’re interested in enabling it for you team.


Learn more about the lifecycle of an Inbound Wire Transfer.


# Reliability

#### You rely on us as a critical service provider. This guide is to be transparent about how seriously we take that responsibility.

---

## Infrastructure

We use Google Cloud in `us-west1` (Oregon). We’re multi-zonal so we’re designed to be robust against the loss of a data center.

We use Google Cloud-managed load balancers in front of a Google-managed Kubernetes cluster.

Our Federal Reserve, The Clearing House, and Visa connections require physical routers. They’re kept in an Equinix collocation facility in Seattle, WA. We maintain redundant hardware, power, and network connectivity.

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

## Data

We use Google Cloud SQL as our primary data store. We use a regional high-availability configuration with automated multi-region back-ups. We test our back-up restoration process daily.

## Monitoring

We use Google Cloud Monitoring for our infrastructure. We use [UptimeRobot](https://uptimerobot.com/) for independent monitoring. We run continuous database state checks to ensure all operational data is as expected.

## Operations

We maintain Business Continuity and Disaster Recovery Plans. By policy they’re tested at least annually but, in practice, they’re tested far more frequently.

## Status

We maintain a status page here:

https://status.increase.com/

## Security

We maintain security and compliance standards here:

https://increase.com/security


You rely on us as a critical service provider. This guide is to be transparent about how seriously we take that responsibility.

Reliability


# 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 acts as the ultimate decision maker and should be unique per group. Both Owners and Administrators possess equal permissions and are authorized to perform any action including Account creation, Transfer approvals, and team management. However, only Owners are able to configure two-party approval settings for moving money and modifying the team.

### Administrators

Administrators are able to perform all actions including Account creation, Transfer approvals, and team management. Access to API keys is restricted to Administrators and Owners. In the event of a dispute, the Owner holds overriding power. Although there's no limit to the number of Administrators, we recommend cautiously providing access.

### Developers

Developers are able to perform most write actions necessary to creating and managing an integration. This includes creating Accounts and Transfers. However, Developers will not be able to approve Transfers if they are required. They can also view Logs, Events, and Entities across all Programs.

### Finance managers

Finance managers are able to perform all actions related to moving money. This includes approving Transfers, a responsibility shared only with Owners and Administrators. However, Finance managers cannot view API keys, Events, Logs, or Entity information. This is useful for providing finance members with the ability to move money while restricting access to sensitive or irrelevant information.

### Clerks

Clerks can initiate Transfers in the Dashboard, but they will always require approval from a Finance manager, Administrator, or Owner. Clerks have access to view Account information and are capable of executing simple tasks, such as generating Account Numbers and creating External Accounts. Like Finance managers, they cannot view API keys, Events, Logs, or Entity information. This role is useful for providing finance members with restricted access to money movement, notably for accounts payable (AP) activities.

### Compliance officers

Compliance Officers are given unique access to Entity and compliance related information. They are able to view all Entity data, create new Entities, view document requests, and create document submissions. However, they are not able to access API keys, create Transfers, or perform any other write actions.

### Viewers

Viewers have full read-only access. This includes permission to view Logs, Events, and Entities across all Programs. They are not able to move money, access API keys, or perform any write actions.

### Accountants

Accountants have limited, read-only access. This role is especially useful for third parties or for users who primarily need to view transaction data. Accountants are able to view and export data related to Accounts, Cards, Account Numbers, and External Accounts. They are not able to move money, access API keys, access any Entity information, or perform any write actions.

## Limiting data access

You can limit the account and transaction data a team member can access in the Dashboard. Data permissions are scoped by Program—you can select all or a subset. This can be particularly helpful if you have a team managing an FBO program, but don’t want to provide access to your commercial accounts. To modify a team member’s data access, visit the [team page](https://dashboard.increase.com/settings/team) in the Dashboard settings.

![Limit data permissions](/images/permissions-data-access.png)


Learn more about the different levels of authorizations and permissions you can attribute to your team members within Increase.

Roles and permissions


# Sandbox routing numbers

Because sandbox transfers and transactions don't move any real-world money, there are some artificial routing numbers to act as counterparty banks.

You can use these routing numbers for test ACH, Wire, and Real Time Payments transfers.

| Routing Number | Bank Name            |
| -------------- | -------------------- |
| `110000000`    | Example Bank         |
| `790000006`    | Alpha Bank           |
| `790000019`    | Bravo Bank           |
| `790000022`    | Charlie Bank         |
| `790000035`    | Echo Bank            |
| `790000048`    | Foxtrot Bank         |
| `790000051`    | No Transactions Bank |

If you'd like to test the behavior of a bank that, for example, doesn't allow Real Time Payments transfers, send a request using the routing number `790000051`. That Routing Number will have the value `"not_supported"` for all [transfer methods](/documentation/api#routing-number-object.ach_transfers).


Increase's sandbox provides a test area for financial products.

Routing Numbers


# Sandbox

When building your application, you'll want to test in sandbox with pretend money, then pilot in production using real money.

Every API and dashboard feature is available in Sandbox.

To simulate external effects you can use special [Simulation APIs](/documentation/api#sandbox-simulations), which are only available in Sandbox. They can be helpful to quickly test events that might take several hours in the real world (like receiving a wire or ACH). They're also great for testing edge cases, like returned ACHs and card refunds.

If you have a sandbox Event Subscription configured, calling these APIs will also result in the appropriate webhooks being sent to your endpoint.


Sandbox


# Sending an ACH debit transfer

ACH debits allow you to pull funds from a recipient and are commonly used for bill payments, such as utility bills, mortgages, loans, and subscription services. However, since debits move funds not owned by the originator, they require authorization from the recipient and are accountable to funds holds.

## Sending an ACH debit with Increase

Originating an ACH debit via the Increase API kicks off several steps involving you, Increase, the Federal Reserve, and the receiving bank.

1. You make a `POST /ach_transfers` call with the details of how much you'd like to debit and data about the recipient.
2. A Transaction is immediately created for the full amount of the transfer.
3. Simultaneously, Increase automatically creates a funds hold to help you avoid double-spending funds received by an ACH debit. The funds hold is released when the 2 business day return window has passed.
4. When the file is submitted to the Federal Reserve, Increase updates the ACH Transfer object with its `submission` details.
5. When the Federal Reserve acknowledges the file (usually within fifteen minutes of file submission), Increase updates the ACH Transfer object with its `acknowledgement` details.
6. The Federal Reserve forwards transfer details to the receiving bank several times per day. The predicted settlement time is in `submission.expected_funds_settlement_at`. There may be delays and processing time required at the receiving bank, however.
7. If a Return is received from the receiving bank, the ACH Transfer object is automatically updated with `return` details and a new Transaction is created to decrement funds.

## Debit Authorizations

Before you originate an ACH debit, you need to collect an authorization from the person you’re debiting. The goal is to make sure funds aren’t being pulled out of a customer’s account without their consent. Depending on your use case and who you’re debiting you’ll need to meet different requirements when collecting your authorization.

If you’re debiting a business, the process is fairly straightforward. You need to obtain legally enforceable authorization. Most likely, this looks like including a clear description of the expected debits (both amounts and timing) in your terms of service. In the standard case, you’ll also set the [Standard Entry Class (SEC) code](/documentation/ach-standard-entry-class-codes) to Corporate Credit or Debit (CCD).

If you’re debiting a consumer, the requirements are more nuanced. There are three types of authorizations for consumer debits: one time, recurring, and standing authorization.

The most straightforward is a one time debit which Nacha calls a Single Entry [0]. A Single Entry is exactly as it sounds: a one time debit for a specified amount.

The second is for Recurring Entries. These are always for the same amount (or within a communicated range of amounts) at a predictable time. This your rent payment for $2,500 on the first of every month. If you ever need to change the amount or the timing, you’ll need to give your customer 10 days notice [1].

If you’re planning to debit at variable times or for variable amounts, you’ll need a Standing Authorization but you’ll also need to ensure affirmative action for each Subsequent Entry. A Standing Authorization has to include specifics on which actions the consumer might take to trigger Subsequent Entries. For example, if you own an acupuncture practice, your patient might agree to be debited each time they come in for an appointment. The debit is triggered by an action on the consumers part.

Regardless of the type, all consumer authorizations must include:

(a) Language regarding whether the authorization is for a Single Entry, Recurring Entries, or one or more Subsequent Entries initiated under the terms of a Standing Authorization;

(b) The amount, or logic for how the amount will be determined;

(c) The timing (including the start date), number, and/or frequency of the Entries;

(d) The name or identity of the person being debited;

(e) The account to be debited;

(f) The date of the authorization; and

(g) Language on how to revoke the authorization (including the time and manner in which the communication must occur).

The authorization must be obtained in writing [2]. The user needs to affirmatively agree to the authorization. A signature always works, but other generally acceptable forms of electronic consent can work as well. The definitive requirements are those laid out in the [Electronic Signatures in Global and National Commerce Act](https://uscode.house.gov/view.xhtml?path=/prelim@title15/chapter96&edition=prelim). It hopefully goes without saying, but you should always rely on the advice of counsel when determining whether your consumer flow meets the requirements here.

In addition to holding on to the authorization yourself, you’ll also need to give a copy to the receiver.

## Debit funds holds

Initiating an ACH debit via Increase adds money to an Increase account's balance and decreases the balance of your counterparty at their financial institution. There is no positive acknowledgement for this type of transfer; the counterparty bank only sends an ACH Return message if they reject the transfer. Transfers can be rejected for many reasons, but most commonly: insufficient funds, incorrect account details, or a lack of authorization.

In general, most rejected transfers are returned by the end of the second business day after the ACH is sent. To prevent accidentally spending money that ultimately gets reversed, Increase places a hold on funds received via ACH debit.

### Understanding the hold

The hold is visible in several ways in the Increase API and Dashboard. A [Pending Transaction](/documentation/api#pending-transactions) with a category of `inbound_funds_hold` and a negative amount offsetting the amount of the ACH debit is allocated to the account. The Inbound Funds Hold has a field `automatically_resolves_at` indicating when the hold will expire. You can query for ongoing or historical Inbound Funds Holds using the `GET /pending_transactions` [endpoint](/documentation/api#list-pending-transactions). You can also receive a webhook Event when the Pending Transaction resolves.

![Dashboard funds holds](/images/docs-ach-holds-timeline.png)

An Account's available balance is decreased by the sum of all the negative Pending Transactions. The Account's current balance will include the value of the ACH Transfers that may still be returned and have Inbound Funds Holds against them.

### Avoiding holds

If you'd like faster access to ACH debits, email us at [support@increase.com](mailto:support@increase.com) to set up a reserve account that fits the transaction behavior of your business.

[0] Nacha Operating Rules Subsection 2.3.2.2 Debit Entries to Consumer Accounts

[1] Nacha Operating Rules Subsection 2.3.2.8 Notices of Variable Recurring Debit Entries to Consumer Accounts

[2] There are guidelines around oral authorizations but we don’t recommend these since they are hard to prove. Feel free to reach out to us if that’s something you’d like to discuss!


Learn more about ACH debits, how debit funds holds are created, why they‘re important, and when you can avoid them.

Debits and funds holds


# Sending an ACH Transfer

[ACH Transfers](/documentation/ach#ach) are the dominant low-value transfer mechanism in the US. Increase processes billions of dollars of ACH transfers each year using our [ACH Transfer API](/documentation/api#ach-transfers).

## Lifecycle

![ACH Transfer statuses](/images/docs-ach-status.png)

| Status               | Description                                                                                        |
| -------------------- | -------------------------------------------------------------------------------------------------- |
| `pending_approval`   | The transfer requires approval from a member of your team.                                         |
| `pending_reviewing`  | The transfer is pending review by Increase.                                                        |
| `pending_submission` | The transfer is pending submission to the Federal Reserve.                                         |
| `submitted`          | The transfer has been submitted to the Federal Reserve                                             |
| `returned`           | The transfer has been returned by the receiver. There will be a second Transaction for the return. |
| `canceled`           | The transfer has been canceled.                                                                    |
| `rejected`           | The transfer has been rejected by Increase.                                                        |
| `requires_attention` | The transfer requires attention from an Increase operator.                                         |

You can find additional details about [sending an ACH Debit Transfer](/documentation/sending-ach-debit-transfers) and [receiving an ACH Transfer](/documentation/receiving-ach-transfers).

## Sending an ACH credit with Increase

Originating an ACH credit via the Increase API kicks off several steps involving you, Increase, the Federal Reserve, and the receiving bank.

1. You make a `POST /ach_transfers` call with the [details](/documentation/api#create-an-ach-transfer) of how much you'd like to send and data about the recipient.
1. A Transaction is immediately created for the full amount of the transfer.
1. When the file is submitted to the Federal Reserve, Increase updates the ACH Transfer object with its `submission` [details](/documentation/api#ach-transfer-object.submission).
1. When the Federal Reserve acknowledges the file (usually within fifteen minutes of file submission), Increase updates the ACH Transfer object with its `acknowledgement` [details](/documentation/api#ach-transfer-object.acknowledgement).
1. The Federal Reserve forwards the transfer details to the receiving bank several times per day. The predicted settlement time is in `submission.expected_funds_settlement_at`. There may be delays and processing time required at the receiving bank, however.

ACH transfers work based on a principle of assumed success. There's no positive acknowledgement from a receiving bank confirming that they've received and allocated the transfer to one of their customer's accounts.

## Approvals

For transfers that require approval from another team member, the ACH Transfer is created with a status of `pending_approval` and a Pending Transaction is created to hold funds.

If the transfer is approved, the ACH Transfer object updates with its `approval` [details](/documentation/api#ach-transfer-object.approval) and the status is changed to `pending_reviewing`. Once the transfer is submitted, the Pending Transaction status updates to `complete` and a new Transaction is created to remove funds from your Account. After this point, the transfer cannot be canceled.

If the transfer is not approved, the ACH Transfer object updates with its `cancellation` [details](/documentation/api#ach-transfer-object.cancellation) and the status is changed to `canceled`. The Pending Transaction status updates to `complete` but no additional Transaction is created.

## Reviews and rejections

Occasionally an ACH Transfer will need to be manually reviewed by an Increase operator. When this occurs the ACH Transfer object status will be set to `pending_reviewing`.

Once reviewed, the status changes to `pending_submission` and things progress normally. However, rarely an ACH Transfer may be rejected by Increase. When this occurs the ACH Transfer object status updates to `rejected` and no Transaction is created on your Account.


Learn more about the lifecycle of an ACH Transfer.

Sending


# Sending a Real-Time Payment

[Real-Time Payments](/documentation/api#cards) can be sent at any time during the day and funds will settle instantly. However, its important to remember that Real-Time Payments are only reachable at ~65% of US financial institutions. You can use the [Routing Numbers API](/documentation/api#cards) to confirm whether an institution supports Real-Time Payments.

## Lifecycle

![Real-Time Payments statuses](/images/docs-rtp-status.png)

| Status               | Description                                                                        |
| -------------------- | ---------------------------------------------------------------------------------- |
| `pending_approval`   | The transfer requires approval from a member of your team.                         |
| `pending_reviewing`  | The transfer is pending review by Increase.                                        |
| `pending_submission` | The transfer is queued to be submitted to The Clearing House.                      |
| `submitted`          | The transfer has been submitted and is pending a response from The Clearing House. |
| `complete`           | The transfer has been sent successfully and funds have settled.                    |
| `canceled`           | The transfer has been canceled.                                                    |
| `rejected`           | The transfer was rejected by Increase, the network, or the recipient's bank.       |
| `requires_attention` | The transfer requires attention from an Increase operator.                         |

## Sending a Real-Time Payment with Increase

Originating a Real-Time Payment via the Increase API kicks off several steps involving you, Increase, The Clearing House, and the receiving bank.

1. You make a `POST /real_time_payments_transfers` call with the [details](/documentation/api#create-a-real-time-payments-transfer) of how much you'd like to send and data about the recipient. A Real Time Payments Transfer is created with a status of `pending_reviewing`.
2. A Pending Transaction is immediately created for the full amount of the transfer in order to hold funds.
3. Once the transfer passes through internal reviews, the status updates to `pending_submission`.
4. When the file is submitted to The Clearing House (usually within seconds), Increase updates the Real-Time Payment Transfer object with its `submission` [details](/documentation/api#real-time-payments-transfer-object.submission) and the status is updated to `submitted`.
5. The Clearing House forwards transfer details to the receiving bank. The receiving bank responds with an acknowledgement. Once the acknowledgement is received, funds are settled instantly and the Real-Time Payment Transfer object status updates to `complete`.
6. A Transaction is immediately created for the full amount of the transfer and funds are removed from your Account. The Pending Transaction is marked as `complete`.
7. If the network is unable to complete the transfer, it responds with a rejection and the transfer status updates to `rejected`. The Pending Transaction is marked as `complete` and no additional Transactions are created on your Account.

The entire process usually completes within seconds.

## Approvals

For transfers that require approval from another team member, the Real-Time Payment Transfer is created with a status of `pending_approval` and a Pending Transaction is created to hold funds.

If the transfer is approved, the Real-Time Payment Transfer object updates with its `approval` [details](/documentation/api#real-time-payments-transfer-object.approval), the status is changed to `pending_reviewing`, and things progress normally.

If the transfer is not approved, the Real-Time Payment Transfer object updates with its `cancellation` [details](/documentation/api#real-time-payments-transfer-object.cancellation) and the status is changed to `canceled`. The Pending Transaction status updates to `complete`, no Transfer information is submitted, and no additional Transactions are created.

## Reviews and rejections

Occasionally a Real-Time Payment Transfer will need to be manually reviewed by an Increase operator. When this occurs the Real-Time Payment Transfer object status will be set to `pending_reviewing`.

Once reviewed, the status changes to `pending_submission` and things progress normally. However, rarely a Real-Time Payment Transfer may be rejected by Increase. When this occurs the Real-Time Payment Transfer object status updates to `rejected`, no Transfer information is submitted to the network, and no additional Transactions are created.


Learn more about the lifecycle of a Real-Time Payments Transfer.


# Sending a wire transfer

[Wire Transfers](/documentation/api#wire-transfers) allow you to send money ~instantaneously. Wires are generally preferred for high value payments that benefit from being irrevocable.

## Lifecycle

![Wire Transfer statuses](/images/docs-wire-status.png)

| Status               | Description                                                                                                                                                                                                                      |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `pending_approval`   | The transfer requires approval from a member of your team.                                                                                                                                                                       |
| `pending_reviewing`  | The transfer is pending review by Increase.                                                                                                                                                                                      |
| `pending_creating`   | The transfer has been created but has not been submitted to the Federal Reserve for processing. Although it is pending, the transfer still cannot be canceled. For example, a transfer is submitted outside of a Fedwire window. |
| `complete`           | The transfer has been submitted to the Federal Reserve and funds have settled.                                                                                                                                                   |
| `reversed`           | The transfer has been reversed by the receiver. There will be a second transaction for the reversal.                                                                                                                             |
| `canceled`           | The transfer has been canceled.                                                                                                                                                                                                  |
| `rejected`           | The transfer was rejected by Increase.                                                                                                                                                                                           |
| `requires_attention` | The transfer requires attention from an Increase operator.                                                                                                                                                                       |

## Sending a wire transfer with Increase

Originating a Wire Transfer via the Increase API kicks off several steps involving you, Increase, the Federal Reserve, and the receiving bank.

1. You make a `POST /wire_transfers` call with the [details](/documentation/api#create-a-wire-transfer) of how much you'd like to send and data about the recipient.
2. A Transaction is immediately created for the full amount of the transfer and your Account balance is reduced.
3. When the file is submitted to the Federal Reserve (usually within minutes), Increase updates the Wire Transfer object with its `submission` [details](/documentation/api#wire-transfer-object.submission).
4. The Federal Reserve forwards transfer details to the receiving bank and funds are settled ~instantly. There may be delays and processing time required at the receiving bank, however.
5. If a Reversal is received from the receiving bank, the Wire Transfer object is automatically updated with `reversal` [details](/documentation/api#wire-transfer-object.reversal) and a new Transaction is created to increment your Account balance.

## Approvals

For transfers that require approval from another team member, the Wire Transfer is created with a status of `pending_approval` and a Pending Transaction is created to hold funds.

If the transfer is approved, the Wire Transfer object updates with its `approval` [details](/documentation/api#wire-transfer-object.approval) and the status is changed to `pending_reviewing`. Once the transfer is submitted, the Pending Transaction status updates to `complete` and a new Transaction is created to remove funds from your Account.

If the transfer is not approved, the Wire Transfer object updates with its `cancellation` [details](/documentation/api#wire-transfer-object.cancellation) and the status is changed to `canceled`. The Pending Transaction status updates to `complete` but no additional Transaction is created.

## Reviews and rejections

Occasionally a Wire Transfer will need to be manually reviewed by an Increase operator. When this occurs the Wire Transfer object status will be set to `pending_reviewing`.

Once reviewed, the status changes to `pending_creating` and things progress normally. However, rarely a Wire Transfer may be rejected by Increase. When this occurs the Wire Transfer object status updates to `rejected` and no Transaction is created on your Account.


Learn more about the lifecycle of a Wire Transfer.

# Software Development Kits (SDKs)

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.

# Breaking changes

We always preserve backwards compatibility in the Increase API per our [versioning policy](https://increase.com/documentation/backwards-compatibility). We'll never make a breaking change without explicitly contacting you first to make sure your integration won't be affected.

Our SDKs and OpenAPI specification are pre-1.0 and do not include deprecated fields that we're preserving for backwards compatibility. This means that if you're using a typed language, upgrading your SDK version can sometimes lead to type-checking errors in development. We encourage you to do this from time to time as an easy way to stay up-to-date with API changes.

Our API, however, is always backwards compatible with older versions of the SDKs. If you choose not to upgrade your SDK version, the code won't crash communicating with the API at runtime.

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

## Go

Install our Go SDK with `go get`. The source is on [GitHub](https://github.com/Increase/increase-go).

```
go get 'github.com/increase/increase-go'
```

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

Ruby is the next SDK we're working on. [Let us know](mailto:support@increase.com) if you'd like to be an early adopter or if there's another language we should support.

Increase's API can be accessed via SDKs for several popular languages including Python, Node, Go, Java, and Kotlin.

Software Development Kits


# Transactions and Transfers

#### Our APIs separate the concepts of Transactions and Transfers. This guide will help you understand their distinctions and how to use them successfully.

---

[Transactions](/documentation/api#transactions) are the immutable record of financial interaction. You can think of them as the line items on your bank statement. A Transaction with a positive amount means there's more money in your account. A Transaction with a negative amount means there's less money in your account. You can't directly create a Transaction, and they never change after they are made. Anything that causes money to move around your Increase account results in a Transaction - initiated or received transfers, card payments, earned interest, and more.

[Transfers](/documentation/api#ach-transfers)- which includes ACH Transfers, Wire Transfers, etc - are the most common way to initiate money movement over external networks with Increase. Transfers are one-to-many with Transactions, which they create as side-effects. Unlike Transactions, Transfers are stateful and transition through a lifecycle of different statuses as they move across the network.

### Example: Creating an ACH Transfer

Let’s examine the lifecycle of a hypothetical ACH Transfer.

##### Day 1

- You make an ACH Transfer (via the API or Dashboard) to pay a vendor $100.
- As a side effect, this immediately creates a -$100 Transaction (as you now have $100 less in your account).
- The ACH Transfer has a status of `pending_submission`. A few minutes later, Increase submits it to the Federal Reserve and changes its status to `submitted`.

![Creating an ACH Transfer, step 1](/images/transfers-transactions-e1-1.png)

Now let’s say that unfortunately you entered the wrong account number for the vendor. The next day, the receiving bank recognizes the error and returns the ACH Transfer, which means we give you your $100 back.

##### Day 2

- The ACH Transfer transitions to status `returned`.
- We make a second Transaction for +$100 to indicate that you now have 100 additional dollars.

![Creating an ACH Transfer, step 2](/images/transfers-transactions-e1-2.png)

## Pending Transactions

Some more complicated funds flows at Increase also create [Pending Transactions](/documentation/api#pending-transactions). These represent potential future credits or debits of money into your account and are a separate resource from Transactions. Notably, while Transactions are immutable, Pending Transactions are not, as they don’t guarantee the movement of money. For example, Pending Transactions are created for card authorizations (which can mutate or timeout) and also when placing a hold on an account (which can be removed). Pending Transactions do not affect your current balance (which is the balance you earn interest on), but may affect your available balance (which is the amount you’re able to move out of Increase).

### Example: Creating an ACH Transfer that requires approval

In this example, your account has [Transfer Approvals](/documentation/transfer-approvals) enabled, which means that your teammate needs to approve a Transfer before it actually goes out.

##### Day 1

- You make an ACH Transfer (via the API or Dashboard) to pay a vendor $100.
- Transfer approvals are required, so the Transfer status is set to `pending_approval`.
- A Pending Transaction is created for -$100. (You’re still earning interest on the $100, but we’ve set it aside.)

![Approving an ACH Transfer, step 1](/images/transfers-transactions-e2-1.png)

##### Day 2

- Your teammate approves the ACH Transfer in the Dashboard.
- The transfer’s status is updated to `pending_submission` as above.
- The existing Pending Transaction for -$100 transitions to `status: complete`, meaning it no longer affects your available balance.
- A Transaction is created for -$100 to reflect the money permanently leaving your account.

![Approving an ACH Transfer, step 2](/images/transfers-transactions-e2-2.png)

##### Denying approval for an ACH Transfer

Had your teammate instead blocked the ACH Transfer, Day 2 would have instead looked like:

- Your teammate blocks the ACH Transfer in the Dashboard.
- The transfer’s status is updated to `canceled`.
- The existing Pending Transaction for -$100 transitions to `status: complete`, meaning it no longer affects your available balance.
- No Transaction is created.

![Denying an ACH Transfer](/images/transfers-transactions-e2-3.png)

## Dashboard

In Dashboard, you’ll be able to see the relationship between a Transfer and all of its Transactions and Pending Transactions as a timeline.

![Dashboard ACH timeline](/images/transfers-transactions-dashboard.png)


Increase’s APIs separate the concepts of Transactions and Transfers. This guide will help you understand their distinctions and how to use them successfully.

Transactions and Transfers


# 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 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 Increase, 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. 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 have no plans to support 2FA over SMS. 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 [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


# Deprecated unique identifier field

The `unique_identifier` parameter to create Transfers was renamed to `Idempotency-Key` in January 2024. The functionality of `unique_identifier` is now available across all Increase API objects.

Learn more about [Increase idempotency](/documentation/idempotency-keys).

We'll still respect the value of `unique_identifier` if your implementation sends that data on POST requests for:

- Account Transfers
- ACH Transfers
- Check Transfers
- Real-Time Payments Transfers
- Wire Transfers

We recommend using the HTTP header based implementation and using Idempotency across all requests you send to Increase.


Increase's money movement APIs include an optional creation parameter called unique_identifier. This can be used to associate a Transfer with a specific Invoice, Order, or Payment.

Transfer unique identifiers


# Visa

Visa is the largest payment card network in the US. Visa writes the rules and operates the technology supporting their network.

A payment card transaction has two major components: authorization, the synchronous approval of a transaction, and clearing, the asynchronous confirmation of the transaction.

Visa has built a wide range of functionality — debit, credit; push-to-card; bank-to-bank communication; card updates; wallets — on their network. This overview covers a tiny amount and is a simplification.

Card payments’ unique economic structure has driven evolution. Significant fees, called interchange, are paid by the merchant and shared between card issuers and Visa. Sophisticated business on both sides pull various levers to drive up or down their interchange rates and avoid fraud liability.

## Authorization

A payment authorization request originates from the merchant to the issuing bank. The authorization request has required details of the Primary Account Number (PAN), expiry, and amount. There are optional and conditional details also. The issuing bank synchronously responds with an approval or a decline.

## Clearing

A merchant batches authorizations into a clearing file submitted to Visa. Visa re-batches the transactions for onward transmission to issuing banks. Settlement is to Visa’s account at JPMorgan.

## Disputes

A distinctive feature of card payments is that disputes are adjudicated. A cardholder can dispute a transaction either because it was unauthorized or the service wasn’t delivered as expected. The first-line adjudicator is the issuing bank though there are also escalation mechanisms.

## Refunds

A card transaction can be refunded by the merchant. Recently Visa introduced an optional authorization step for refunds. More often, however, merchants simply include refund details in the clearing file.

## Card validations

When a merchant will keep a card number on file for future transactions, they can originate a zero-dollar or one-dollar authorization request to confirm the card number is valid. These transactions aren’t usually cleared but instead the authorization is reversed.

## Tokenization

Card numbers can be tokenized; the resulting unique identifier can be used in place of the card number in authorization and clearing. This process underpins digital wallets like Apple Pay and is common for online subscriptions. Token validity persists across replacement cards.

## Level 2 / Level 3 data

Merchants can opt to share transaction data with Visa at clearing to reduce their interchange rates. Level 2 data includes tax, customer, and shipping information. Level 3 data provides even finer details like item descriptions, quantities, and product codes.

## Schedule

Visa authorizations are always open.

Visa transmits clearing files on business days at a time coordinated between Visa and the issuing bank.

## Technical implementation

Authorizations use an [ISO 8583](https://en.wikipedia.org/wiki/ISO_8583) message format. It’s a fascinating format containing a bitmap table to minimize size and field-level encodings. Visa's authorization network is called BASE I (which used to expand to Bank of America System Engineering).

Clearing uses a proprietary fixed-width flat file format. Visa's clearing network is called BASE II.


Visa is the largest payment card network in the US with a wide range of functionality including debit, credit, push-to-card, bank-to-bank communication, and more. Learn more about how Visa works and pitfalls to avoid.

Overview of Visa


# 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/developers/webhooks) or via the [API](/documentation/api/#event-subscriptions). 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 if you need batch processing, you can also request Events from the Increase API using the [List Events API](/documentation/api#list-events). In fact, we recommend polling over webhooks for data synchronization.

You can access Events 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 7 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#event-object.category).

## IP addresses

We currently send webhooks from these IP addresses:

- 34.83.67.223
- 35.247.122.129

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


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

Events and webhooks


# Reversals

Wire transfers are final and irrevocable. However, they can be reversed by the receiving depository financial institution in rare circumstances. Reversals can also be requested by the originator, but the receiving institution is under no obligation to approval them. If a wire transfer is reversed, the original transfer is not altered. Instead a separate wire transfer is initiated in the other direction.

It’s worth noting that there are no rules for reversing wire transfers. Common and acceptable reasons include:

1. Incorrect account or beneficiary details were provided
2. The receiving depository institution is unable to reconcile the transfer to a beneficiary
3. The beneficiary has refused the wire
4. The sender has requested a reversal due to an unauthorized transfer

## How Reversals work with Increase

### Receiving a reversal

When a Wire Transfer is submitted to the Federal Reserve, it’s status updates to `complete`. If the transfer is reversed by the receiving depository institution, the status updates to `reversed` and a `reversal` [property](/documentation/api#wire-transfer-object.reversal) is added to the transfer object. Additionally, a second transaction is created for the reversal to debit the funds. The Transaction is linked in the `transaction_id` [attribute](/documentation/api#wire-transfer-object.reversal.transaction_id) of the `reversal` property.

### Requesting a reversal

If you’d like to request that a Wire Transfer be reversed, please contact support@increase.com


Learn more about Wire reversals, when they're allowed, and how you can initiate them.