
# Lockboxes

## Overview

Instead of creating Check Deposits directly via the API, [Lockboxes](/documentation/api/lockboxes#create-a-lockbox) offer a convenient way to deposit checks received via mail into your Increase account. Each Lockbox is associated with a specific Account and has a unique physical mailing address. You can create Lockboxes using either the Dashboard or the API.

## Processing mail

When mail arrives at your Lockbox, the following process occurs:

1. An [Inbound Mail Item](/documentation/api/inbound-mail-items) object is created to represent the received mail, triggering an `inbound_mail_item.created` webhook.
2. A human operator reviews the mail to determine if it contains one or more checks. For each valid check, a `Check Deposit` object is created.
3. If the Lockbox's `check_deposit_creation` setting is `automatic`, the `Check Deposit` object is created with a status of `pending` and follows the standard deposit lifecycle as described in [Depositing checks](/documentation/check-deposits).
4. If the Lockbox's `check_deposit_creation` setting is `require_approval`, the `Check Deposit` object is created with a status of `pending_approval` and will not be deposited until explicitly approved via the Dashboard or the API. To approve a pending deposit, make a `POST` request to `/check_deposits/:id/approve`.
5. Mail that does not contain valid checks or check-related documents will still create an Inbound Mail Item but with a status of `rejected`.

You can adjust mail receipt settings and the `check_deposit_creation` behavior for a Lockbox at any time using the Update Lockbox API. For more information on creating and managing Lockboxes, refer to the [Lockboxes API Reference](/documentation/api/lockboxes).


Learn more about using Lockboxes to deposit checks received via mail.

Lockboxes


# 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 mismatched transactions when reconciling. Any discovered mismatches 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 supervision 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.

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

ACH 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


# Address Verification System codes and overrides

The Address Verification System (AVS) is used during card authorization to validate that the billing address provided by the cardholder matches the address on file with the issuing bank.

At Increase, AVS codes sent in authorizations are either:

1. **Determined by Increase** — Increase calculates AVS codes by comparing the **cardholder address on file** to the **postal code** and **street address (line1)** that the merchant sent in the authorization network message. The address parts can be defined or undefined in any combination.
2. **Determined by customer-provided overrides** — Optional AVS code overrides customers specify in responses to Real-Time Decision requests.

If no AVS code overrides are provided during the Real-Time Decision request, Increase applies its own AVS code determination logic when generating the authorization response.

## Visa's simplified AVS codes

Historically, AVS had return codes that would distinguish between many more granular scenarios. Specifically, they used to have separate codes to distinguish between "address not checked because it was not provided" and "address provided but did not match". Visa has since **collapsed the set into fewer codes**.

This simplification means certain distinctions no longer exist. Now, "address no match" covers both the case where the address was not provided and the case where the address was provided but did not match.

### Overview of current Visa AVS codes

| Code | Definition                               | Increase Representation              | Notes                                                                                                                                         |
| ---- | ---------------------------------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `Y`  | Postal code matches, address matches.    | `match`                              | Full match. Will only be returned if both postal code and address were provided and matched.                                                  |
| `A`  | Postal code no match, address matches.   | `postal_code_no_match_address_match` | Postal code was provided and does not match or was not provided. Address was provided and matched.                                            |
| `Z`  | Postal code matches, address no match.   | `postal_code_match_address_no_match` | Postal code was provided and matched. Address was provided and did not match or was not provided.                                             |
| `N`  | Neither postal code nor address matches. | `no_match`                           | Both postal code and address were not provided or did not match what was provided. If both were not provided, would be `not_checked`.         |
| `R`  | Indeterminate outcome. Retry.            | `retry`                              | The outcome could not be determined. All invalid AVS code values are treated as `retry`.                                                      |
| `U`  | Unable to verify.                        | `not_checked`                        | Address verification was not possible. Used when neither postal code nor address were provided. Blank AVS codes are treated as `not_checked`. |

If an issuer returns any retired AVS codes, Visa will convert them to the appropriate simplified code and will not notify the issuer of the replacement. This means that issuers that are still using retired AVS codes should not see any change in their AVS outcomes and can continue to use their deployed logic. So for example, if an issuer were to return `postal_code_match_address_not_checked`, Visa would automatically convert it to `postal_code_match_address_no_match`.

Here at Increase, we've rolled forward to the new simplified codes.

## Address matching

A key consideration of Increase's implementation of AVS is how the address parts on file are compared to the address parts sent in the authorization request. Visa **does not recommend exact string comparison**. Instead, they emphasize **numeric matching**: the digits of the address are considered the most reliable indicators of matching.

**Increase normalization & matching rules (summary):**

- Trim/normalize white spaces.
- Ignore casing.
- Ignore unit numbers when determining the numeric **prefix**.
- Normalize postal codes.
- Treat blank/omitted request fields as **not provided** (affects code determination as described below).
- Support "compressed numeric" (e.g., `123 SE Greenville Blvd, Ste 456-789` can match `12345` via numeric concatenation/prefix).

## Default AVS code determination logic

Increase compares the cardholder address on file to the request's `postal_code` and `line1` per the rules above. See the examples below for more details.

### Examples of default AVS code determination Logic

| Scenario                                 | Cardholder details                           | Authorization request details | Increase AVS code                    |
| ---------------------------------------- | -------------------------------------------- | ----------------------------- | ------------------------------------ |
| Nothing matches                          | `123 cool st, 97701`                         | `8583 payments ave, 94110`    | `no_match`                           |
| Exact match                              | `123 cool st, 97701`                         | `123 cool st, 97701`          | `match`                              |
| Case-insensitive                         | `123 cool st, 97701`                         | `123 COOL st, 97701`          | `match`                              |
| White space insensitive                  | `123 cool st␣␣, 97701`                       | `123 cool st, 97701␣`         | `match`                              |
| Postal code white space → no postal sent | `123 cool st, 97701`                         | `123 cool st, ␣`              | `postal_code_no_match_address_match` |
| Postal code mismatch                     | `123 cool st, 97701`                         | `123 cool st, 94110`          | `postal_code_no_match_address_match` |
| Street number mismatch                   | `321 cool st, 97701`                         | `123 cool st, 97701`          | `postal_code_match_address_no_match` |
| No street address, zips match            | `123 cool st, 94110`                         | `nil, 94110`                  | `postal_code_match_address_no_match` |
| No postal sent at all                    | `123 bank st, (any)`                         | `nil, nil`                    | `not_checked`                        |
| No addresses, zips do not match          | `nil, 00000`                                 | `nil, 00001`                  | `no_match`                           |
| Ignore unit number                       | `123 cool street #333, 97701`                | `123 cool st, 97701`          | `match`                              |
| Compressed address numeric               | `123 SE Greenville Blvd, Ste 456-789, 97701` | `12345, 97701`                | `match`                              |
| Visa non-UK example 1                    | `123 1st Street, 91234-0615`                 | `123, 912340615`              | `match`                              |
| Visa non-UK example 2                    | `1 Elm Street, 91234`                        | `1, 91234`                    | `match`                              |
| Visa non-UK example 3 (leading numeric)  | `22 Walnut street #23, 70433-0123`           | `22, 704330123`               | `match`                              |
| Visa non-UK example 3 (first five)       | `22 Walnut street #23, 70433-0123`           | `2223, 704330123`             | `match`                              |
| Visa UK example (first five)             | `5678 LONDONCOURT #99, 5S76D`                | `56789, 576`                  | `match`                              |

## Acquirer use of AVS codes

Neither Increase nor Visa decline authorizations as a result of a mismatching AVS code—they are purely a signal to the acquirer and the merchant. The most common way they're used are through $0 verifications, where an invalid address verification check might result in the merchant preventing the customer from saving their card for future use. Beyond $0 verifications they often feed in to fraud systems on the merchant and acquirer's side. A merchant that receives an approved authorization with an invalid address check might show the payment as declined to their customer to avoid the fraud risk, at which point they'll usually reverse the authorization within a few minutes of the original authorization.

## Customer-provided overrides

Customers can supply overrides to control how AVS codes are determined. The conversion from the provided overrides to the final AVS code considers two signals **for each field**:

- Was the field **provided** in the network message?
- Was the override for that field a `match` or `no_match`?

If both `postal_code` and `line1` are provided and match, the result is `match`. If a field is not provided, the result for that field is always `no_match` regardless of the provided override.

Increase will not check the cardholder address on file when determining the final AVS code if the user has provided overrides in the Real-Time Decision response. Note that per the API, if you wish to provided any overrides, both overrides must be provided.

The table below comprehensively shows the AVS code used based on the provided overrides and whether the associated address part was provided in the authorization request.

### Full override matrix

| Postal code override | Postal code provided? | Line1 override | Line1 provided? | AVS code                             |
| -------------------- | --------------------- | -------------- | --------------- | ------------------------------------ |
| `match`              | ✅                    | `match`        | ✅              | `match`                              |
| `match`              | ✅                    | `match`        | ❌              | `postal_code_match_address_no_match` |
| `match`              | ✅                    | `no_match`     | ✅              | `postal_code_match_address_no_match` |
| `match`              | ✅                    | `no_match`     | ❌              | `postal_code_match_address_no_match` |
| `match`              | ❌                    | `match`        | ✅              | `postal_code_no_match_address_match` |
| `match`              | ❌                    | `match`        | ❌              | `not_checked`                        |
| `match`              | ❌                    | `no_match`     | ✅              | `no_match`                           |
| `match`              | ❌                    | `no_match`     | ❌              | `not_checked`                        |
| `no_match`           | ✅                    | `match`        | ✅              | `postal_code_no_match_address_match` |
| `no_match`           | ✅                    | `match`        | ❌              | `no_match`                           |
| `no_match`           | ✅                    | `no_match`     | ✅              | `no_match`                           |
| `no_match`           | ✅                    | `no_match`     | ❌              | `no_match`                           |
| `no_match`           | ❌                    | `match`        | ✅              | `postal_code_no_match_address_match` |
| `no_match`           | ❌                    | `match`        | ❌              | `not_checked`                        |
| `no_match`           | ❌                    | `no_match`     | ✅              | `no_match`                           |
| `no_match`           | ❌                    | `no_match`     | ❌              | `not_checked`                        |

## Summary

- If a user provides AVS match/no match overrides, Increase will use them in combination with what address parts were provided in the authorization request to compute the final appropriate AVS code.
- If a user does not provide AVS match/no match overrides in an approved Real-Time Decision request, Increase will use its own AVS code determination logic to compute the AVS code.
- Increase's default AVS code determination logic computes AVS codes by comparing the cardholder address on file to the authorization's `postal_code` and `line1`, using normalization and numeric matching rules.
- Visa's simplified AVS codes mean "not checked" and "no match" are no longer distinguished, and any missing address parts will always be treated as `no_match`.
- If both `postal_code` and `line1` are not provided, the result is always blank (`not_checked`).


Explains Increase’s default Address Verification System (AVS) code determination logic, how address matching is performed, how Visa has simplified AVS codes, and how customer-provided AVS match/no match overrides interact with network-provided data.

Address Verification System codes and overrides


# 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


# Account balances

#### Increase tracks the balance of your account in real-time.

---

### Current balance

The current balance is the amount of money in the account. If the account is eligible for interest, it's the amount of money earning interest.

The balance is calculated as the sum of all [Transactions](/documentation/transactions-transfers) in the account. It is updated at the same moment a Transaction is created. Transactions are immutable, so once a Transaction is created, it will never be altered or removed.

### Available balance

The available balance is the amount of money in the account that is available to be spent or transferred. It is calculated as the current balance minus the sum of all negative Pending Transactions.

Pending Transactions represent expectations about upcoming financial activity that may or may not occur. A negative Pending Transaction reflects money that may be removed from your account in the future, like a card charge that has not yet been settled or a hold against an ACH debit that may be returned.

Positive Pending Transactions represent money that may be added to your account in the future, like a card refund that has not yet been settled. A positive Pending Transaction does not affect the available balance.

### API access

You can access the current balance and available balance of an account via the [Retrieve an Account Balance](/documentation/api/accounts#retrieve-an-account-balance) endpoint.

You can list all transactions and pending transactions for an account via the [List Transactions](/documentation/api/transactions#list-transactions) and [List Pending Transactions](/documentation/api/pending-transactions#list-pending-transactions) endpoints.


Increase’s APIs track the balance of your account in real-time.

Account balances


# How to build a bill pay program with Increase

Every year, platforms like Ramp use Increase to move tens of billions of dollars through bill pay flows, making it one of the most common use cases we support. In this guide, we'll walk through the high level of what building a bill pay program consists of. Increase offers low-level APIs to access payment networks in the US, following a principle we call ["no abstractions"](https://increase.com/articles/no-abstractions). As a result, there are often several ways to build a particular flow of funds with us. This article suggests best practices, but there are places where you'll want to think about what's best for your business—we'll highlight some of these decision points below.

---

## Onboarding your platform to Increase

### Program setup

Every platform begins with a Program. This is where Increase and our bank partners work with you to define what your money movement product will do—what kinds of accounts you need, what rails you'll move money over, and how the underlying bank will treat your business. This includes Increase performing Know Your Business (KYB) checks on your company.
[Learn more about platform onboarding](https://increase.com/documentation/onboarding#platform-onboarding)

There’s often a few weeks of contracting at the beginning of an integration. During that time, you can build and test your integration using our sandbox environment, or in production using your own corporate funds to see how money actually moves. This lets you make technical progress in parallel, and can significantly shorten the time to launch.

### Opening accounts

Typically, we recommend creating individual bank accounts for each of your customers. This avoids the need to build and maintain your own ledger, simplifies ownership, and gives you maximum flexibility. Account creation is synchronous and unbounded—you can create as many as you need. You can also assign each account unique account numbers for easier tracking of inbound transfers. Most platforms validate external bank accounts via Plaid or microdeposits.

Increase also supports commingled For Benefit Of (FBO) accounts if that’s a requirement for your business. You’ll need to integrate with our [Bookkeeping API](https://increase.com/documentation/bookkeeping#bookkeeping) to ledger funds as they move through Increase.

[Learn more about account structures](https://increase.com/documentation/platform-implementation#account-structure)

---

## Onboarding your users

### Know Your Customer (KYC)

You must operate a KYC program. Increase provides primitives, not policies, and as such you are responsible for fraud and risk controls. Most platforms use a third-party provider like [Alloy](https://www.alloy.com/), and integrate directly with Increase to automatically ingest those results.

[Learn more about KYC requirements](https://increase.com/documentation/onboarding)

### Creating entities

Once you’ve verified your customer, you’ll create an Entity in Increase to represent them. This can be a business or an individual. This is a prerequisite to account creation. You can do this using the [Create Entity API](https://increase.com/documentation/api/entities#create-an-entity).

### Collecting bank account details

If users will fund payments from their own bank accounts, you’ll need to collect account and routing numbers. Many platforms use [Plaid](https://plaid.com) or similar providers to validate account ownership and reduce issues during onboarding.

### Creating accounts

After onboarding, depending the account structure highlighted above [create an account](https://increase.com/documentation/api/accounts#create-an-account) for the customer in Increase.

---

## Initiating payments

Most bill pay use-cases contain the same basic funds flow: fund the bill payment (typically from the customer’s external bank account) and then disburse it into the payee’s account.

![Initiating payments](/images/docs-outbound-payment.png)

### Fund the bill payment

Most platforms use ACH debits to pull funds from customer bank accounts. With Increase this is a single API call to the [Create ACH Transfer API](https://increase.com/documentation/api/ach-transfers#create-an-ach-transfer). This works well but comes with the risk of returns—for example, due to insufficient funds or revocation. When a return happens, we recommend monitoring it via our API and notifying your operations team. Our API surfaces return codes that can help you investigate. You'll decide how to handle those cases in your product experience.

If you want to avoid returns entirely, you can ask users to push funds in via ACH credit or wire. This slows things down but reduces operational risk.

[Learn more about FedACH returns](https://increase.com/documentation/fedach#overview-of-fedach)

Most platforms start by funding bill payments via the customer’s external account, but some platforms issue fully-featured bank accounts via Increase from which they directly initiate payments. This can speed up money movement, reduce costs, and create opportunities to monetize funds held on-platform.

[Learn more about creating bank accounts for your customers](https://increase.com/products/bank-accounts)

---

### Disburse the bill payment

Increase can push funds over every major payment rail in the US, including ACH (same-day or next-day), wires, checks, Real-Time Payments (RTP), and Visa Direct. While ACH is the standard rail for most payments companies, your choice of payout rail may vary depending on your industry and the needs of your vendors or customers. You can fund and disburse the bill payment on different rails.

Some platforms allow the payor or the payee to select a faster option in exchange for a fee. For example, you might use RTP or wire transfers (which settle in seconds) instead of ACH, or send a check via FedEx instead of first-class mail.

As in the previous section, initiating most payments on Increase is a single API call, such as:

- [Create an ACH Transfer](/documentation/api/ach-transfers#create-an-ach-transfer)
- [Create a Check Transfer](/documentation/api/check-transfers#create-a-check-transfer)
- [Create a Wire Transfer](/documentation/api/wire-transfers#create-a-wire-transfer)
- [Create a Real-Time Payments Transfer](/documentation/api/real-time-payments-transfers#create-a-real-time-payments-transfer)
- [Create a Card Push Transfer](/documentation/api/card-push-transfers#create-a-card-push-transfer)

For platforms looking to deepen their suite of financial services, you can also issue cards as part of your bill pay solution.

[Learn more about building a card issuing program on Increase](/products/cards)

---

While many options exist, payment initiation often reduces down to a few API calls with Increase. You can see this in action with our [Postman collection for bill payments](https://www.postman.com/increaseapi/increase-workspace/collection/65t18kg/sample-bill-payment-workflow-via-ach).

This guide is a broad overview. The specifics of your bill pay product will depend on what you're building and who you're serving. If you have questions, please reach out to support@increase.com - we’d be excited to talk to you!


Learn more about what goes into building a bill pay program with Increase.

Building a bill pay program


# 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 your operating accounts commingle customer funds, you will need to integrate against our [Bookkeeping API](/documentation/api/bookkeeping-accounts). 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 create an [informational entity](/documentation/api/entities) for the customer whose balance you are tracking. Then create a bookkeeping account for that entity:

```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
- Clear zone of 0.5mm of white bleed, evenly around the image

![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/brandguidelines). 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 Disputes

An unavoidable part of running a card issuing program is the need to handle occasional disputes between a merchant and a cardholder about a transaction. Dispute processes are essentially conversations between cardholders and merchants mediated by the network until the cardholder eventually wins or loses the dispute. Most of the complexity of disputes arises from the fact that different dispute types require different required information and rules throughout such a conversation. To help you build a great dispute experience for your cardholders by providing the best possible evidence, Increase’s Card Disputes API fully models these rules for each dispute category the card networks expose.

## Starting a Card Dispute

To start a Card Dispute with Increase, you make a `POST /card_disputes` call with the disputed transaction, the amount you want to dispute, and other required details including any attachments you have as evidence backing your dispute. For example, to start a Card Dispute for a transaction processed with Visa in a case where services weren't received as promised:

```curl
curl -X POST https://api.increase.com/card_disputes
  -d $'{
    "amount": 20000,
    "disputed_transaction_id": "transaction_uyrp7fld2ium70oa7oi",
    "network": "visa",
    "visa": {
      "category": "consumer_services_not_received",
      "consumer_services_not_received": {
        "cancellation_outcome": "merchant_cancellation",
        "last_expected_receipt_at": "2025-11-05",
        "merchant_cancellation": {
          "canceled_at": "2025-11-08"
        },
        "purchase_info_and_explanation": "Contractor was supposed to perform job, then canceled three days after without refunding"
      }
    }
  }'

200 OK
{
  "id": "card_dispute_h9sc95nbl1cgltpp7men",
  "status": "pending_user_submission_reviewing",
  "visa": {
    "network_events": [],
    "required_user_submission_category": null,
    "user_submissions": [
      {
        "category": "chargeback",
        "chargeback": {
          "category": "consumer_services_not_received",
          "consumer_services_not_received": {
            "cancellation_outcome": "merchant_cancellation",
            "last_expected_receipt_at": "2025-11-05",
            "merchant_cancellation": {
              "canceled_at": "2025-11-08"
            },
            "purchase_info_and_explanation": "Contractor was supposed to perform job, then canceled three days after without refunding"
          }
        },
        "status": "pending_reviewing",
        // ...
      }
    ]
  },
  // ...
}
```

_Note: card networks generally require the cardholder and merchant to attempt to resolve any dispute between themselves before escalating to starting a Card Dispute. To present the strongest case possible, make sure the cardholder made a reasonable effort to resolve the issue first._

Our API refers to this cardholder-provided evidence as a User Submission. Increase then submits the User Submission to the merchant via the card network. The merchant will then have an opportunity to reply. Our API refers to these replies as Network Events. After they reply, you can then provide the cardholder’s response (as a second User Submission), and this conversation continues back and forth like this until the dispute is won or lost.

## Lifecycle of a Card Dispute

![Lifecycle of a Card Dispute](/images/docs-card-dispute-status.png)

| **Status**                           | **Description**                                                                                     |
| ------------------------------------ | --------------------------------------------------------------------------------------------------- |
| `pending_user_submission_reviewing`  | The most recent User Submission is being reviewed.                                                  |
| `pending_user_submission_submitting` | The most recent User Submission is being submitted to the network.                                  |
| `user_submission_required`           | A User Submission is required to continue with the Card Dispute.                                    |
| `pending_response`                   | The Card Dispute is pending a response from the network.                                            |
| `pending_user_withdrawal_submitting` | The user’s withdrawal of the Card Dispute is being submitted to the network.                        |
| `won`                                | The Card Dispute has been won and no further action can be taken.                                   |
| `lost`                               | The Card Dispute has been lost and funds previously credited from the acceptance have been debited. |

## User Submissions

To ensure the greatest chance of winning a Dispute, Increase reviews each User Submission before sending it to the merchant via the card network. If further information is needed before submission, such as, say, a copy of a receipt, Increase will request this before continuing with the dispute process.

![Lifecycle of a User Submission](/images/docs-card-dispute-user-submission-status.png)

| **Status**                      | **Description**                                                                                                                                                                                                                                                                     |
| ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `pending_reviewing`             | The User Submission is pending review by Increase.                                                                                                                                                                                                                                  |
| `accepted`                      | The User Submission has been accepted and will be transmitted to the card network.                                                                                                                                                                                                  |
| `further_information_requested` | Further information is requested from the cardholder. Details about what information is requested is contained in the `further_information_requested_reason` property on the User Submission. As outlined below, the status of the Card Dispute will be `user_submission_required`. |
| `abandoned`                     | The User Submission has been abandoned, either because a new User Submission was made, or because the Card Dispute was lost due to a timeout or the cardholder withdrawing the dispute.                                                                                             |

User Submissions are created when a Card Dispute is first created with `POST /card_disputes` and when subsequent User Submissions are submitted with `POST /card_disputes/:card_dispute_id/submit_user_submission`.

User Submissions are card network specific. See for example the API reference for the [various User Submissions](/documentation/api/card-disputes#card-dispute-object.visa.user_submissions) that can be made for a Visa dispute and the Visa disputes section for more details about when these are used.

## User Submission categories

As a dispute progresses, different categories of User Submissions are required. When a Card Dispute is in the `user_submission_required` status, the category of User Submission required can be determined from the `required_user_submission_category` property of the network-specific sub-object of the Card Dispute, such as `visa.required_user_submission_category`.

If Increase requests further information for a User Submission, you should rely on the `further_information_requested_reason` property of the most recent User Submission to determine the information needed. In this scenario, the category of submission requested from the user will be the exact same as the submission for which information was requested.

## User Submission deadlines

Every step of a dispute has a required deadline (enforced by the card network) for when a response from the next party is due. When it’s the cardholder’s turn to reply, this deadline will be populated in the `user_submission_required_by` property of the Card Dispute. If you do not submit an approved User Submission by the deadline, the cardholder automatically loses the dispute. Note that the merchant may also miss a deadline, in which case the cardholder automatically wins the dispute.

You can also always withdraw an active Card Dispute for a cardholder (causing it to be lost) by calling `POST /card_disputes/:card_dispute_id/withdraw`.

## Network Events

Network Events represent card network level activity by either the cardholder, the merchant or the network itself due to deadlines. These will contain details of the merchant’s response.

Network Events are card network specific. See for example the API reference for the various Network Events that can occur for a Visa dispute and the Visa disputes section for more details about when these are used.

Putting it all together, a typical dispute flow looks like this:

1. User submits a Card Dispute with the initial User Submission by calling `POST /card_disputes`, which starts out with the status `pending_user_submission_reviewing`.
2. Increase reviews the User Submission and either accepts the submission (`pending_user_submission_submitting`), or requests further information from the user (`user_submission_required`).
   1. The user submits a new User Submission for the Card Dispute with the additional information requested by Increase by calling `POST /card_disputes/:card_dispute_id/submit_user_submission`, and Increase reviews this new submission as in step 2.
3. Increase submits the submission to the card network, and adds the submission as a Network Event to the Card Dispute. The status is now `pending_response`, pending response from the network.
4. Once a response comes back from the network, it is added as a Network Event on the Card Dispute.
   1. If the Network Event means that a dispute was either lost or won, Increase will transition the Card Dispute to the appropriate status (`lost` or `won`).
   2. If the Network Event needs a response from the user, the Card Dispute transitions back to the `pending_user_submission_reviewing` status and the process continues from step 2 onwards again. The user relies on the most recent Network Event for details about the merchant’s response, such as any explanation or evidence they may have provided. The user must provide a User Submission in response and have it accepted by a specific deadline.

## Dispute Financial Transactions

As a Dispute progresses, money will move as result. When exactly money moves depends on the network and card type. For example, for a Visa credit card transaction, money will immediately be credited to the cardholder when a dispute is submitted to the network. If the merchant responds in disagreement, money will be debited from the cardholder until the next submission from the user is made.

These money movements are represented by Dispute Financial transactions. If a given Network Event has caused money movement, a Dispute Financial transaction will be present by reference in the `dispute_financial_transaction_id` property on the Network Event.

## Example dispute types

Visa broadly categorizes their dispute processes into two types:

- Allocation. This is when a payment was not initiated by a cardholder at all, such as in cases of fraud or unauthorized card-on-file transactions.
- Collaboration. Used for all other disputes such as processing errors and consumer disputes, which are a broad category of dispute related to the merchandise or service rather than the payment itself.

Both processes start by submitting a Card Dispute with chargeback information using `POST /card_disputes`, but the Network Events and subsequent User Submission categories depend on the process.

### The Allocation dispute process

In this process, the cardholder is effectively assumed right from the onset. If the merchant does not agree with the dispute, they must initiate “pre-arbitration”, which has higher fees and evidence requirements.

The flow of User Submissions and Network Events for an Allocation dispute is as follows, ignoring the User Submission review flow with Increase:

![Visa Allocation dispute process](/images/docs-card-dispute-visa-allocation-flow.png)

See the API reference for more details about the individual [Network Events](/documentation/api/card-disputes#card-dispute-object.visa.network_events) and [User Submissions](/documentation/api/card-disputes#card-dispute-object.visa.user_submissions).

### The Collaboration dispute process

In this process, the merchant is given the opportunity to fully or partially disagree with the cardholder’s dispute without escalating to pre-arbitration by re-presenting the transaction along with evidence. If the cardholder still disagrees with the merchant at this point, they can initiate pre-arbitration.

The flow of User Submissions and Network Events for a Collaboration dispute is as follows, ignoring the User Submission review flow with Increase:

![Visa Collaboration dispute process](/images/docs-card-dispute-visa-collaboration-flow.png)

See the API reference for more details about the individual [Network Events](/documentation/api/card-disputes#card-dispute-object.visa.network_events) and [User Submissions](/documentation/api/card-disputes#card-dispute-object.visa.user_submissions).


Learn more about how disputes of Card Payments work

Card Disputes


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

Card Payment Lifecycle


# Card Push Transfers Integration

_To use Card Push Transfers, reach out to [support@increase.com](mailto:support@increase.com)._

Integrating with the Increase API for Card Push Transfers involves three main
concepts:

- [Card Tokens](/documentation/api/card-tokens), which are card numbers collected from your customers that you aim
  to push funds to
- [Card Validations](/documentation/api/card-validations), which are $0 network messages sent to the issuer to ensure
  that the card number is valid and that the cardholder is who they claim to be
- [Card Push Transfers](/documentation/api/card-push-transfers), which push funds to eligible cards

From a high level, your integration would do the following:

1. Collect a customer’s card number. If you’re Payment Card Industry Data
   Security Standards (PCI-DSS) compliant you can do this directly, otherwise
   you’ll likely make use of a tokenization provider. You then forward the card
   number to us at https://vault.increase.com/card_tokens.
2. Check that the card number belongs to a BIN/card range that supports
   push-to-card by calling the [Card Token
   Capabilities](/documentation/api/card-tokens#retrieve-the-capabilities-of-a-card-token)
   endpoint.
3. If it does, you then proceed by confirming with the issuing bank that the
   card number is valid and that the name and address of the cardholder matches
   what they’ve provided you, using the [Card Validation
   creation](/documentation/api/card-validations#create-a-card-validation)
   endpoint.
4. Once confirmed, you push funds to the card with the [Card Push Transfer
   creation](/documentation/api/card-push-transfers#create-a-card-push-transfer)
   endpoint.

If you later want to push funds to the same card again you only need to
repeat step 4.

## Tokenization providers

Increase is fully PCI-DSS compliant and can receive card numbers either directly from
you or from your tokenization provider. By utilizing a tokenization provider you
collect card numbers from your customers using the tokenization provider’s
frontend components, before relying on their forwarding endpoints to pass
through the raw card details to Increase. This ensures that your systems never
see raw card details.

Examples of tokenization providers are:

- Stripe: https://docs.stripe.com/payments/vault-and-forward
- Basis Theory: https://developers.basistheory.com/docs/guides/share/process-card-payments
- Very Good Security: https://www.verygoodsecurity.com/docs/guides/outbound-connection

Increase supports any tokenization provider that can send a JSON payload
over HTTPS.

## Card Tokens

A [Card Token](/documentation/api/card-tokens) is a representation of a card
number encrypted and stored in Increase’s Payment Card Industry (PCI)
environment. The https://vault.increase.com/card_tokens endpoint is the only
endpoint that accepts raw card numbers; everything else uses an Card Token. As
such, the `/card_tokens` endpoint exists at https://vault.increase.com instead
of the regular https://api.increase.com URL.

To authenticate with the `/card_tokens` endpoint you create a special bearer
credential that can only be used for this purpose in the Increase dashboard:
https://dashboard.increase.com/developers/api_keys (`Create API key` → `Create
Production Card Tokenization Key`).

```curl
$ curl -X POST https://vault.increase.com/card_tokens \
  -H "Authorization: Bearer BEARERCREDENTIAL" \
  -H "Content-Type: application/json" \
  -d ’{
    "primary_account_number": "4444440000001234",
    "expiration_month": 3,
    "expiration_year": 2030,
    "card_verification_value2": "123"
  }’

=> {"card_token":"card_token_ooy8ebisb1p71o6lpbbd"}%
```

If you use a tokenization provider like Basis Theory you’ll want to use their
proxy endpoint to forward the request to us:

```curl
$ curl 'https://api.basistheory.com/proxy' \
  -X 'POST' \
  -H 'BT-API-KEY: <API_KEY>' \
  -H 'BT-PROXY-URL: https://vault.increase.com/card_tokens' \
  -H 'Authorization: Bearer BEARERCREDENTIAL' \
  -H 'Content-Type: application/json' \
  -d '{
      "primary_account_number": "{{ token: d2cbc1b4-5c3a-45a3-9ee2-392a1c475ab4 | json: \"$.data.number\" }}",
      "expiration_month": "{{ token: d2cbc1b4-5c3a-45a3-9ee2-392a1c475ab4 | json: \"$.data.expiration_month\" }}",
      "expiration_year": "{{ token: d2cbc1b4-5c3a-45a3-9ee2-392a1c475ab4 | json: \"$.data.expiration_year\" }}",
      "card_verification_value2": "{{ token: d2cbc1b4-5c3a-45a3-9ee2-392a1c475ab4 | json: \"$.data.cvc\" }}",
    }'
```

### Capabilities

Once you’ve tokenized a card number you can fetch its capabilities with the
[Card Token
capabilities](/documentation/api/card-tokens#retrieve-the-capabilities-of-a-card-token)
endpoint. The capabilities are based on routing files provided by the card
networks and return a point-in-time view of the card number at the time of
fetching. Note that retrieving the capabilities of a Card Token only lets you
know that the card number belongs to a valid Account Range on the issuer’s side
and whether it supports actions such as push-to-card transfers; it does not tell
you whether the card number itself is valid. The capabilities can change over
time.

### Sandbox

Real card numbers are not usable in sandbox. Instead you can create
sandbox-specific card tokens using the [Create a Card Token simulation](/documentation/api/card-tokens#sandbox-create-a-card-token).

## Card Validations

[Card Validations](/documentation/api/card-validations) are $0 account
verifications sent to the card network that are used to verify the validity of a
given card number. They also let you validate the cardholder’s information, such
as their name and their address. Since push-to-card transfers are non-reversible
it is crucial to validate that you are pushing funds to the expected cardholder
to prevent fraud.

Similar to other Increase APIs, the [Card Validation
creation](/documentation/api/card-validations#create-a-card-validation) endpoint
creates a `Card Validation` that then moves through an asynchronous state
machine. To retrieve the outcome of a Card Validation you can either use the
[Card Validation
retrieval](/documentation/api/card-validations#retrieve-a-card-validation)
endpoint or listen for
[`card_validation.created`](/documentation/api/events#event-object.category.card_validation.created)
webhooks.

![Card Validations](/images/card-validations-flow.png)

## Card Push Transfers

The [Card Push Transfer
creation](/documentation/api/card-push-transfers#create-a-card-push-transfer)
endpoint initiates a push-to-card transfer. Similar to other Increase transfers
these are asynchronous and move through a state machine in real-time once
created. Card Push Transfers can be declined by the issuer.

The Card Push Transfer input fields depend on your use case. An employee
reimbursement transfer would for example use `business_application_identifier:
funds_disbursement`. To discuss your use case, please reach out to [support@increase.com](mailto:support@increase.com).

Initiating a Card Push Transfer creates a `PendingTransaction` on your Increase
account with a hold for the funds. The `PendingTransaction` is completed as soon
as the Card Push Transfer is either accepted or declined by the issuing bank.
Accepted Card Push Transfers result in a `Transaction`.

![Card Push Transfers](/images/card-push-transfers-flow.png)


Card Push Transfers Integration


# Overview

Card Push Transfers move funds between your Increase account and an eligible
Visa or Mastercard payment card within seconds. The funds are available
instantly on the recipient’s end.

## Target reach

Card Push Transfers can be used to push funds to billions of eligible Visa and
Mastercard cards, both domestically and internationally. Supported cards are
primarily debit cards.

## Use cases

Visa Direct and Mastercard Send support dozens of use cases for sending funds to
both consumers and businesses.

Examples include:

- Worker payouts, such as instant payroll, contractor payments, or tip
  disbursements
- Consumer payouts, such as employee reimbursements and insurance claim
  repayments
- Small business payouts, such as merchant settlements, marketplace payouts, and
  loan disbursements
- Overall money movement between two consumers

## Networks

Increase utilizes our direct card network connections over redundant, leased
line connectivity[0] to provide a best-in-class push-to-card experience directly
with the card networks. This ensures full support of any card network features
and complete pass-through of the information available in the acquiring
messages.

## Underlying implementation

Push-to-card transfers, often called Original Credit Transactions (OCTs), are
implemented as additional functionality on top of the authorization, clearing,
and settlement functionality that the card networks already support for regular
purchase processing. You can think of them as instantaneous refunds, with a few
key differences:

- Whereas a regular purchase or refund can be sent as either an 0100
  authorization message followed by a clearing message or an 0200 full financial
  message depending on the acquirer, a push-to-card transfer is always a 0200
  full financial, with the funds moving instantly.
- Push-to-card 0200s are not reversible, as the issuer is required to make the
  funds available within seconds.

Under the hood, even though the issuer makes funds available as soon as they receive the 0200
message from the network, actual movement of funds still happen daily over
Fedwire using Visa’s regular net settlement process.

[0] https://increase.com/articles/visa-redundancy


Card Push Transfers move funds between your Increase account and an eligible Visa or Mastercard payment card within seconds. The funds are available instantly on the recipient’s end.

Overview of Card Push Transfers


# 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 available from the [Federal Reserve Bank](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/check-deposits#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-deposits#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-deposits#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-deposits#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

If you'd like to deposit checks received via mail, see the [Lockboxes guide](/documentation/lockboxes).


Learn more about the lifecycle of a Check Deposit.

Depositing checks


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


# Embedded card component

Increase offers an embeddable card component that can render a Card’s details within an `<iframe />` component on your website. This can allow you to display sensitive information like the Card’s `primary_account_number` and `verification_code` without having the information ever pass through your systems.

Not accessing the Card's Primary Account Number is a good practice to help comply with the Payment Card Industry Data Security Standards (sometimes abbreviated as “PCI”).

## Usage

Start by getting the `iframe` URL. You’ll need the ID of the [Card](/documentation/api/cards#cards) you wish to render. The URL you generate will be accessible for one hour.

```curl
$ curl --url "https://api.increase.com/cards/${card_xx}/create_details_iframe" \
  -H "Authorization: Bearer ${INCREASE_API_KEY}" \
  -H "Content-Type: application/json"
```

```json
{
  "iframe_url": "https://site.increase.com/card_details_iframe/index.html?token=abc123",
  "expires_at": "2025-01-01T00:00:00.00Z"
}
```

Once you have an `iframe` URL, you can embed an `<iframe />` in your UI:

```jsx
<iframe
  style="width: 312px; height: 200px; border: none"
  src={iframe_url}
  allow="clipboard-write" {/* Necessary for copy buttons to work. */}
/>

```

The above code will render something like this:

![Embedded component](/images/card-component.png)

## Physical cards

By default, the embedded component will render your virtual card art. To render an image including your [Physical Card](/documentation/api/physical-cards#physical-cards) artwork instead, pass the Physical Card ID as a parameter when creating the `iframe` URL. The component will also include the chip and Visa logo.

```curl
curl --url "https://api.increase.com/cards/${card_XXX}/create_details_iframe" \
    -H "Authorization: Bearer ${INCREASE_API_KEY}" \
    -H "Content-Type: application/json" \
    -d '{"physical_card_id": "${physical_card_XXX}"}'
```


Embedded Card Component


# Exports

#### Exports allow you to generate and download files from your Increase account. This includes data reports (like transaction CSVs and account statements) as well as documents (like verification letters and tax forms). They are useful for analyzing your account data in other tools, migrating to another service, or for information gathering purposes.

---

## Making an Export

You can create an Export in the [API](/documentation/api/exports) or Dashboard. Once you create an 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.

## Lifecycle

![Export statuses](/images/docs-export-status.png)

| Status     | Description                                                    |
| ---------- | -------------------------------------------------------------- |
| `pending`  | The Export file is being created and is not ready to download. |
| `complete` | The Export file has been created and is ready to download.     |
| `failed`   | The Export file failed to be created.                          |

## Types of Export

When you create an Export, you'll need to indicate what `category` you want. 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!

### Data Reports

These exports allow you to download large amounts of data from your Increase account. You can filter by specifying time ranges, accounts, and programs.

| Category                          | Description                                                                                            |
| --------------------------------- | ------------------------------------------------------------------------------------------------------ |
| `account_statement_ofx`           | An Open Financial Exchange (OFX) file of transactions and balances for a given time range and Account. |
| `balance_csv`                     | A CSV of account balances for the dates in a given range.                                              |
| `bookkeeping_account_balance_csv` | A CSV of bookkeeping account balances for the dates in a given range.                                  |
| `dashboard_table_csv`             | Certain dashboard tables are available as CSV exports. This export cannot be created via the API.      |
| `entity_csv`                      | A CSV of entities with a given status.                                                                 |
| `transaction_csv`                 | A CSV of all transactions for a given time range.                                                      |
| `vendor_csv`                      | A CSV of vendors added to the third-party risk management dashboard.                                   |

### Documents

These exports generate PDF documents for specific purposes.

| Category                      | Description                                                                                         |
| ----------------------------- | --------------------------------------------------------------------------------------------------- |
| `account_verification_letter` | A PDF letter verifying account ownership, often used when demonstrating ownership to a third party. |
| `funding_instructions`        | A PDF with instructions for funding an account, including routing and account numbers.              |
| `form_1099_int`               | A PDF of an IRS Form 1099-INT for interest income.                                                  |
| `form_1099_misc`              | A PDF of an IRS Form 1099-MISC for miscellaneous income.                                            |

## Backwards compatibility

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


Exports allow you to generate and download files from your Increase account, including data reports and documents like verification letters and tax forms.

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.

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

###### Increase is not a bank. Banking products and services are offered by Grasshopper Bank, N.A., Member FDIC and First Internet Bank of Indiana, Member FDIC. 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., Member FDIC and First Internet Bank of Indiana, Member FDIC. FDIC deposit insurance only covers the failure of the FDIC insured bank.


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 destination 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). To learn more, view our tutorial on [how to set up ACH debits](/documentation/setting-up-ach-debits).

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 future-dated windows. Increase submits transfers in every window. You can track [Increase's ACH submission status](https://status.increase.com/) at any time.

Each FedACH window is made up of three parts:

- The _Transmission Deadline_ is the cutoff. FedACH must receive files before this moment.
- The _Target Distribution_ is when FedACH aims to tell receiving depository institutions about the transfers. FedACH may occasionally miss this deadline.
- The _Settlement Schedule_ is when FedACH will fund the financial institutions’ Federal Reserve accounts.

Increase submits throughout the day and makes a best effort to submit your ACH transfers to the next available window. To guarantee delivery to FedACH for a specific window, submit your transfers 1 hour before the FedACH window. Increase will still process most transfers submitted less than 60 minutes before a FedACH cutoff before that deadline.

![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-transfers#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.

## Operating a wire integration

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

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


Fedwire 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`. Idempotency keys can be up to 200 characters long.

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


# Connecting to QuickBooks and Plaid

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.

Connecting to QuickBooks and Plaid


# Interest and referral bonus

Increase’s bank partner may pay interest on your deposits and your customers’ deposits. The bank may also pay you a bonus for referring depositors to the bank. The calculation and rates will be specified in your agreement with the bank.

Interest is accrued daily based on the current balance of the account at midnight UTC.

Payments are made on the first of each month for interest and bonus amounts that accrue during the preceding month. For example, on February 1st, you’ll receive a payment based on balances for the 31 days of January.

# Using the API

In the API, these payments are [Transactions](/documentation/api/transactions#transaction-object) with the `category` of `interest_payment`. You can read more about what specific fields are available in the [API reference](/documentation/api/transactions#transaction-object.source.interest_payment).

When a payment is posted, you’ll receive an [Event](/documentation/api/events#event-object.category.transaction.created) webhook with the type `transaction.created`.

[This simulation](/documentation/api/accounts#sandbox-create-an-interest-payment) allows you to generate a payment in Sandbox. Besides this simulation, interest and bonus are not created in Sandbox.

## Configuration

To help with accounting, you’ll receive a monthly payment per account. We recommend leveraging [as many accounts](/documentation/accounts-and-account-numbers#accounts) as you need to best organize your use case.

You can configure one of two payment schemes.

- Receive each Account’s payment to that Account.
- Receive each Account’s payment to one designated income account.

Most platforms opt to receive the payments into one income account.


Interest and referral bonus


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

You can retrieve an API Key's associated `group_id` by using the [Retrieve Group API](/documentation/api/groups#retrieve-group-details).

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

## 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 supervision for certain integrations. Learn more about these requirements.

Ongoing supervision


# 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](/documentation/api/check-transfers#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. By default, the Pending Transaction is for the full amount of the transfer in order to hold funds. (For more on this, see "Pending transaction options" below.)

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` [details](/documentation/api/check-transfers#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](/documentation/api/check-transfers#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 checks

By default Increase will print and mail your checks and you will be able to access all `physical_check` [details](/documentation/api/check-transfers#check-transfer-object.physical_check) on the Check Transfer object. A typical printed check will look like the below image. Please note that fields have been annotated by their field names for documentation purposes. The overlays will not be printed.

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

For custom printing needs, Increase can design a check template for you. If you're interested, contact [support@increase.com](mailto:support@increase.com).

By default checks are fulfilled via USPS First Class mail. Checks will be printed by the end of the next business day after they're ordered. Our printer is located near a major airport in the center of the US and checks typically arrive in 3-5 business days depending on the destination.

For higher-priority checks, you can use FedEx Overnight by setting the [`shipping_method`](/documentation/api/check-transfers#create-a-check-transfer.physical_check.shipping_method) to `fedex_overnight`. Orders received by 2pm ET (on business days) will be shipped that day and typically arrive the following morning. Note that FedEx does not ship to P.O. boxes.

You may also include an "attachment" with your check, which is a document that will be included in the envelope. This must be a US-letter-sized PDF with a maximum of 5 pages for USPS First Class and a maximum of 50 pages for FedEx Overnight. Attachments will be printed in greyscale. Content within 1/8" of the document edge will not be printed. To do this, first [create a File](/documentation/api/files#create-a-file) with purpose [`check_attachment`](/documentation/api/files#create-a-file.purpose.check_attachment) and pass that File's ID when [creating a Check Transfer](/documentation/api/check-transfers#create-a-check-transfer.physical_check.attachment_file_id).

You can see pricing for USPS/FedEx shipping and attachments on your [fees page](https://dashboard.increase.com/fees).

## Printing your own checks

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](/documentation/api/check-transfers#check-transfer-object.stop_payment_request) provided. The Pending Transaction status updates to `complete`, and no additional Transactions are created.

## Pending transaction options

When a Check Transfer is created, a Pending Transaction is immediately created. By default, the Pending Transaction is for the full amount of the transfer, but this behavior can be configured by setting the [`balance_check`](/documentation/api/check-transfers#create-a-check-transfer.balance_check) parameter. Based on the parameter value, the Pending Transaction will be:

1.  **`balance_check: full` (default)**: A Pending Transaction is immediately created for the full amount of the transfer in order to hold funds. This ensures you have sufficient funds available when the check is created and will have enough money when the check deposit comes through.
2.  **`balance_check: none`**: A $0 Pending Transaction is created instead. No balance check is performed when the check transfer is initiated, meaning funds are not reserved upfront. The balance will still be checked when the check is deposited. If there are insufficient funds at that time, the deposit will be declined.

## 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, called [Positive Pay](/documentation/positive-pay):

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

### Handling returned mail

If Increase prints and mails your checks, we automatically handle returned mail on your behalf. We do this by setting the [`return_address`](/documentation/api/check-transfers#check-transfer-object.physical_check.return_address) to an Increase owned lockbox. If a check is returned due to a delivery failure, you'll receive a [tracking update](/documentation/api/check-transfers#check-transfer-object.physical_check.tracking_updates).

## 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](/documentation/api/check-transfers#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](/documentation/api/check-transfers#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


# 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. Each time you onboard a new customer, you’ll create a new Entity in Increase.

Funds in Increase belong to exactly one `Account`. Each account can have two entities associated with it, stored as pointers named `entity_id` and `informational_entity_id`.

| Account Ownership                                                      | Implementation                                                                                                                                                                               |
| ---------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| You own accounts                                                       | Each Account’s `entity_id` will be your corporate entity. Each Account’s `informational_entity_id` will be an entity for your customer who is the beneficiary of the funds.                  |
| Accounts are owned by the bank for the benefit (FBO) of your customers | Each Account’s `entity_id` will be an entity identifying the bank partner. Each Account’s `informational_entity_id` will be an entity for your customer who is the beneficiary of the funds. |
| Individual customers own accounts                                      | Each Account’s `entity_id` will be an entity identifying your customer. There is no `informational_entity_id` in this situation.                                                             |

## 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 `informational_entity_id`, associating the customer with the funds. |
| 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


# Positive pay

## Overview

Positive pay is a feature built into every [Check Transfer](/documentation/originating-checks). When you create a Check Transfer, Increase records information about the payment. We use that information to reconcile incoming checks against pre-registered Check Transfers.

When a check is deposited at another financial institution, the depositing bank sends the following information to Increase via Check 21:

- The account number
- The check number
- The amount
- An image of the check

We automatically reject incoming checks that fail these validation steps:

1. _Do this check number and account number refer to a pre-registered check?_ &nbsp;Fraudsters will steal valid checks and create invalid duplicates by copying some, but not all, of the details.
2. _Does the amount presented match the pre-registered check?_ &nbsp;Your counterparty, or its bank, may have transcribed the check amount incorrectly. In that case, the check will be returned and they should re-deposit for the correct amount.
3. _Has the check already been successfully deposited?_ &nbsp;Fraudsters may find deposited checks (in the trash, on a desk in the office) and attempt to re-deposit it! Or, your counterparty may make a mistake and deposit it twice. In either case, you're protected.

About **1%** of incoming checks at Increase fail this validation, averaging **$3,000** per check.

To help you and your customers monitor their accounts, all of the successful and unsuccessful deposits are available in the Dashboard and API. The [Check Decline `reason`](https://increase.com/documentation/api/declined-transactions#declined-transaction-object.source.check_decline.reason) will indicate why our system returned a check deposit.

## Payee name mismatches

Finally, checks can be altered and the "Pay To" line changed to a fraudster. Increase uses artificial intelligence to automatically identify checks that have been manipulated. We'll flag checks with mismatched names to you in the Dashboard and API. In the API, the field [Inbound Check Deposit `payee_name_analysis`](https://increase.com/documentation/api/inbound-check-deposits#inbound-check-deposit-object.payee_name_analysis) determines whether or not the check matches what was recorded.

Your team should review the very small number of checks Increase identifies as `does_not_match`. We've found that our AI algorithm does not have the context on your customers to identify what is fraud and what is expected user behavior. You should make the ultimate determination. For some customers, more than half of the altered checks are actually deposited by the intended recipient. For example:

- A check written to `Ian Crease Accounting Services` altered to `Ian Crease`.
- A check written to `Crease Investment Fund Series 7` deposited to `Crease Investments`.
- A check written to `Alexander Graham` edited to `Alexander Graham Bell`.

Even when flagging seemingly obvious fraud like a line being changed from `ABC Consulting Services` to `Eve Evilson`, we prefer you to make the decision to return the check. Increase does not have the context on whether Eve is (for example) a sole proprietor doing business as ABC Consulting.

For most customers, a mismatch requiring investigation happens far fewer than 1 in 5000 checks.

### Handling mismatches

When a Check Transfer is flagged as a name mismatch, you'll get a Webhook of type `inbound_check_deposit.created`. You can use this indicator to trigger an alert on your end.

From there, your team can review the deposited check in the dashboard and compare it to the check you issued. You can also research the counterparty. If you want to return the check, you'll need to decide within 7 days. You can return a check in the Dashboard or setup your internal tools to call the [appropriate API endpoint](/documentation/api/inbound-check-deposits#return-an-inbound-check-deposit).

If you want to honor the check, no action is required.

![Increase dashboard showing positive pay](/images/positive-pay.png)

_In the dashboard, you have access to all the relevant data: the original, printed pay-to name, the incoming check scan from the depositing bank, and a button to return the check if you determine it's fraudulent._


Learn more about how Increase protects your checks from theft and fraud.

Positive pay


# 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](/documentation/api/inbound-ach-transfers#sandbox-create-an-inbound-ach-transfer). 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/card-payments#sandbox-create-a-card-authorization):

```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/card-payments#sandbox-settle-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/event-subscriptions#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/real-time-decisions#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 commercial 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, Increase and your bank partner 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:

- Account titling and structure
- Cashback paid on card payments
- Interchange earned on card payments
- Per-user dashboard access
- Required compliance reporting
- Reserve accounts and required thresholds
- Technology fees
- Transfer approval rules
- Visa Bank Identification Number (BIN) type
- Your bank partner's interest or referral bonus rate

Some settings are configured by your bank partner, some by Increase, and some by you.

## 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-subscriptions#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-subscriptions#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/event-subscriptions#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.

If Increase doesn't receive a response to a card authorization webhook (for example, if your server crashes or times out), we'll automatically decline the authorization.

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/card-payments#sandbox-create-a-card-authorization) 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


# Validating an account using Real-Time Payments

Include a random code in a one-cent [Real-Time Payments](/documentation/api/real-time-payments-transfers) transfer to verify reachability and authenticate access to the account.

## Performing validation

The [Routing Number endpoint](/documentation/api/routing-numbers) shows if a routing number has _any_ support for Real-Time Payments, but there can still be mixed enablement per account. Including a random code in the validation transfer also allows you to verify someone has access to the account. The steps:

1.  Generate a code and don't share it with your user. The Clearing House (the network behind Real-Time Payments) requires that the code be at most 8 characters long. We recommend using uppercase letters and numbers and avoiding visually ambiguous characters (like `0`, `O`, `I`, and `1`).

2.  Send the Real-Time Payments transfer for $0.01 using [our guide](/documentation/sending-real-time-payments). Include the code in the [`remittance_information`](/documentation/api/real-time-payments-transfers#create-a-real-time-payments-transfer.remittance_information) parameter. Starting July 1, 2026, all banks will be required to show this field to users. Until then, The Clearing House also suggests putting the code in the [`debtor_name`](/documentation/api/real-time-payments-transfers#create-a-real-time-payments-transfer.debtor_name) parameter (along with the name of the entity performing validation.) The Clearing House specifies that the code should be at the beginning of the field and separated from the rest of it by a pipe (`|`).

3.  If the transfer is accepted by the other bank, then the account can receive Real-Time Payments transfers. If it's rejected, then the account likely cannot. The [`reject_reason_code`](https://increase.com/documentation/api/real-time-payments-transfers#real-time-payments-transfer-object.rejection.reject_reason_code) will provide more information.

4.  Finally, ask your user to access their bank and provide the random code. By doing this, they're demonstrating they're able to access the bank account to which the transfer was sent.


Validate account access and reachability using Real-Time Payments.

Real-Time Payments Account Validation


# 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 February 2025, [the per-transaction limit is $10,000,000](https://www.theclearinghouse.org/payment-systems/Articles/2024/12/Higher_10_Million_RTP_Network_Transaction_Limit_Empowers_New_Uses_12-04-2024).

## 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. You can decline the transfer up to the expected settlement time.

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/inbound-ach-transfers#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/inbound-ach-transfers#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 banking 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 ACH Transfers


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

Receiving Wire Transfers


# 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, Transfers they create will always require approval from a Finance manager, Administrator, or Owner and they cannot approve Transfers. 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         |
| `101050001`    | First Bank of the US |
| `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-numbers#routing-number-object.ach_transfers).


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

Sandbox 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/overview#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. For more information, view our [guided tutorial on setting up ACH debits](/documentation/setting-up-ach-debits).

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

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

- The amount, or logic for how the amount will be determined;

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

- The name or identity of the person being debited;

- The account to be debited;

- The date of the authorization; and

- 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/pending-transactions#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/fedach) 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/ach-transfers#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-transfers#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-transfers#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-transfers#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-transfers#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 ACH Transfers


# 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/routing-numbers) 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/real-time-payments-transfers#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-transfers#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-transfers#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-transfers#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 Real-Time Payments


# 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/wire-transfers#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-transfers#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-transfers#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-transfers#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-transfers#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.

Sending Wire Transfers


# Setting up ACH debits

Setting up ACH debits for consumer accounts requires three steps. First, you need to make sure that you have obtained authorization from your end user. Second, you need to verify that the user has access to the provided account and that it is setup to process ACH debits. Third, you need to initiate the actual ACH debit. In this guide, we’ll walk you through each of these steps to ensure your process aligns with industry standards and regulations.

## Receiving authorization

Before initiating ACH debits, you must obtain explicit authorization from your customer. Most often this looks like a written authorization signed by the customer. While debiting a business is relatively straightforward, debiting a consumer is more nuanced, requiring the authorization to be specified as either a one time, recurring, or standing authorization (each with their own rules). The specific requirements for each authorization type are [well documented](/documentation/sending-ach-debit-transfers#debit-authorizations).

Regardless of type, the authorization must include the following:

- The name or identity of the person being debited
- The account that will be debited
- The transaction amount or a variable amount range
- The transaction frequency (one-time or recurring)
- The date of the first transaction (for recurring payments)
- Language on how to revoke the authorization (including the time and manner in which the communication must occur)

##### Retention and record keeping

You are required to retain a copy of the authorization for at least two years from the termination date. In the event of a dispute, you will be required to provide proof of authorization. Consider implementing an automated system for managing authorizations, with encryption to ensure customer data privacy.

## Verify account access

After obtaining authorization, you may want to verify that the customer has access to the account that will be debited. This can commonly happens in two ways:

- Instant verification through a third party service like Plaid, Yodlee, MX, Finicity, Teller, MoneyKit, etc.
- Manually verify with ACH or Real-Time Payments micro-deposits.

Verifying account details is required by Nacha when debiting a consumer account using the [`WEB`](https://increase.com/documentation/api/ach-transfers#create-an-ach-transfer.standard_entry_class_code.internet_initiated) Standard Entry Class Code. [The relevant rule](https://www.nacha.org/rules/supplementing-fraud-detection-standards-web-debits) came into effect in 2021.

Even if your use case doesn't strictly require account details verification, it can still be worthwhile implementing as a way to limit your exposure to ACH returns.

### Setting up account verification with a third party service

The obvious benefit of using a service like Plaid or Yodlee is that customers will be able to verify access to their account relatively quickly, usually requiring them to simply log in to their bank account and confirm access. However, you’ll need to set up a new integration. At a top level, this integration will look like:

- **Integrate the API:** Start by integrating the API provided by Plaid or Yodlee to generate an authentication token.
- **Implement the hosted flow:** Use the third-party-hosted flow—Plaid Link or Yodlee FastLink—to securely guide users through the authentication process.
- **Customize the interface:** Tailor the appearance of the flow to match your brand, ensuring a seamless user experience.
- **Authenticate users:** Once users authenticate, both services return an access token, confirming their access.
- **Retrieve account information :** Retrieve limited data about the user’s bank accounts (e.g., account type, account number, routing number) to facilitate a transfer.

You can learn more by reading [Plaid’s Documentation](https://plaid.com/docs/) and [Yodlee’s Documentation](https://developer.yodlee.com/).

### Building ACH microdeposit verification

Alternatively, you can verify a customer’s access to an account by using ACH microdeposits. This process usually takes 1-2 days to complete. You can also use Real-Time Payments to send microdeposits in a few seconds, but are limited to a subset of banks that currently support this financial network.

##### 1. Send two microdeposits

Start by initiating two small ACH credits with random amounts (e.g., $0.06 and $0.32) to the user’s account. These microdeposits serve as both a verification mechanism and a way to validate that the account is open and can receive ACH transfers. Make sure to notify users to monitor their bank account for these deposits, which typically appear within 1-2 business days.

As of September 2024, microdeposits must be identified as “Micro-Entries” by setting the `company_entry_description` field to `ACCTVERIFY`, in compliance with [Nacha’s](https://www.nacha.org/micro-entries) [rules](https://www.nacha.org/micro-entries). Additionally, the `company_name` must be easily recognizable and consistent with the name used for future entries.

```javascript
await increase.achTransfers.create({
  account_id: 'account_in71c4amph0vgo2qllky',
  amount: 6,
  currency: 'USD',
  individual_name: 'Ian Crease',
  account_number: '987654321',
  routing_number: '101050001',
  company_name: 'Increase',
  company_entry_description: 'ACCTVERIFY',
});
```

```javascript
await increase.achTransfers.create({
  account_id: 'account_in71c4amph0vgo2qllky',
  amount: 32,
  currency: 'USD',
  individual_name: 'Ian Crease',
  account_number: '987654321',
  routing_number: '101050001',
  company_name: 'Increase',
  company_entry_description: 'ACCTVERIFY',
});
```

##### 2. Initiate an offset debit

To balance your ledger, you can optionally initiate a single ACH debit for the total amount of the microdeposits (e.g., $0.38). Note that this debit transfer may not exceed the value of the credit amounts and must be submitted simultaneously within the same file to the receiving institution.

```javascript
await increase.achTransfers.create({
  account_id: 'account_in71c4amph0vgo2qllky',
  amount: -38,
  currency: 'USD',
  individual_name: 'Ian Crease',
  account_number: '987654321',
  routing_number: '101050001',
  company_name: 'Increase',
  company_entry_description: 'ACCTVERIFY',
});
```

##### 3. Evaluate response from the Receiving depository institution

If the account credentials are valid, the transfers will successfully post. However, if there is a problem with the credentials, the receiving bank will return the transfer. In this instance, the associated ACH Transfer object’s status will be updated to `returned` and a `return_reason_code` will be included with [additional information](/documentation/api/ach-transfers#ach-transfer-object.return.raw_return_reason_code)—for example `R02` (The account is closed).

Because the receiving institution can return _either_ the credit or debit transfers, account validation can vary depending upon a few factors. The following table outlines a few common scenarios.

| **Credit**              | **Debit**                  | **Description**                                                                                                                                                         |
| ----------------------- | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Posted                  | Posted                     | **Full validation:** The account is valid for future authorized ACH credits or debits.                                                                                  |
| Posted                  | `R01`, `R09`               | **Full validation:** The account has been overdrawn by the ACH debit. However, the account is still valid for future authorized credits or debits.                      |
| Posted or `R20`, `R23`  | `R16`, `R29`               | **Partial validation:** The account has blocked all ACH debits. However, the account is valid for authorized credits.                                                   |
| Posted or `R20`, `R23`  | `R20`                      | **Partial validation:** The account type does not accept ACH debits. However, the account is valid for authorized credits.                                              |
| `R23`                   | `R05`, `R07`, `R10`, `R11` | **Failed validation:** The transactions have not been authorized by the account holder. No further attempts should be made until a new authorization has been obtained. |
| `R02`, `R03`, `R04`     | `R02`, `R03`, `R04`        | **Failed validation:** The account is either closed or does not exist                                                                                                   |
| Any except `R20`, `R23` | Any except `R01`, `R09`    | **Failed validation:** There is likely an error in the entries                                                                                                          |

For a full list of ACH return codes and their descriptions, [view our documentation on Returns](https://increase.com/documentation/ach-returns#return-reason-codes).

**4. Collect confirmation from the user**

Once the microdeposits have settled, ask the user to confirm the exact deposit amounts. This can be done via:

- A secure input field in your application.
- A phone or email response, depending on your process.

Ensure that this step is straightforward for users to complete, as delays in their response can further impact onboarding time.

## Initiating ACH debits

Now that you’ve obtained authorization from the customer and proven they have access to an account, you can initiate your ACH debit (per your authorization). For more information you can view the [lifecycle of an ACH Transfer](/documentation/sending-ach-transfers#sending-an-ach-transfer) or view our guide on [sending ACH debits](/documentation/sending-ach-debit-transfers#sending-an-ach-debit-transfer).


Setting up ACH debits

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

```shell
$ pip install increase
```

## JavaScript/TypeScript

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

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

## Ruby

Install our Ruby SDK with `gem`. The source is on [GitHub](https://github.com/Increase/increase-ruby).

```shell
$ gem install increase
```

## Go

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

```shell
$ 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.

```groovy
// 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, Ruby, 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 immutable records of financial interactions with Increase. 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.

[Pending Transactions](/documentation/api/pending-transactions) represent potential future credits or debits of money into your account and are a separate resource from Transactions (despite their similar name). 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](/documentation/balance#current-balance) (which is the balance you earn interest on), but do affect your [available balance](/documentation/balance#available-balance) (which is the amount you’re able to move out of Increase).

### Example: Creating an ACH Transfer

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

##### T0: 9am ET on a Monday morning

- You start with $500 in your Increase account. (Your current balance and available balance are both $500.)
- You make an ACH Transfer (via the API or Dashboard) to pay a vendor $100.
- As a side effect, this immediately creates a -$100 Pending Transaction (you now have $100 less that you can move out of Increase). Your available balance is now $400.
- However, given ACH Transfers are submitted asynchronously and no money has actually moved yet at the Federal Reserve, no Transaction has been created yet. Your current balance is still $500 (you are earning interest on $500).
- The ACH Transfer has a status of `pending_submission`.

##### T1: 9:30am

- A few minutes later, Increase submits the ACH Transfer to the Federal Reserve and changes its status to `submitted`. Nothing else changes.

##### T2: 1:00pm

- At 1pm ET, per the Federal Reserve's [processing schedule](https://www.frbservices.org/resources/resource-centers/same-day-ach/fedach-processing-schedule.html), the transferred funds have settled at the receiving bank. As a result, Increase performs 2 updates simultaneously:
- The Pending Transaction updates to status: `complete`, meaning the held funds are released.
- A Transaction is created to reflect that the funds have left your Account.
- At this point, both your available balance and current balance are $400.

##### T3: 9am ET the following day

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.

- The ACH Transfer transitions to status `returned`.
- We make a second Transaction for +$100 to indicate that you now have 100 additional dollars.
- At this point your available balance and current balance are again both $500.

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

This flow demonstrates the one-to-many relationship between Transfers and Transactions. While one ACH Transfer object exists through this entire flow, At T0 there were zero Transactions created, at T2 there was one Transaction, and at T3 a second Transaction was created, all pointing to the same ACH Transfer.

## Dashboard

In your 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.

To require transfer approvals, visit a [program's details](https://dashboard.increase.com/settings/programs) in the Dashboard settings.


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


# 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/events#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/events#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 being generated and a webhook being sent, see our [API reference](/documentation/api/events#event-object.category).

You can configure your Webhook to receive all of the events, or a single specific category.

## IP addresses

We currently send webhooks from these IP addresses:

- 34.83.67.223
- 35.247.122.129
- 34.168.16.194

## OAuth webhooks

If you operate an OAuth application, you can subscribe to webhooks in your users' account. More details are in the [OAuth guide](/documentation/oauth#webhooks).

## Securing your webhook endpoint (recommended)

Increase uses the [Standard Webhooks](https://www.standardwebhooks.com/) specification for webhook signatures. Each webhook request includes three headers for verification:

- `webhook-id`: A unique identifier for the webhook message (the Event ID)
- `webhook-timestamp`: Unix timestamp (seconds since epoch) when the webhook was sent
- `webhook-signature`: The signature(s) for verifying authenticity

```none
webhook-id: event_123abc
webhook-timestamp: 1674087231
webhook-signature: v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE=
```

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), then Base64-encodes the result. The signature is prefixed with the version `v1,`.

### Using a Standard Webhooks library

The easiest way to verify webhook signatures is to use a [Standard Webhooks library](https://github.com/standard-webhooks/standard-webhooks?tab=readme-ov-file#libraries). Libraries are available for many languages including JavaScript, Python, Ruby, Go, Java, and more.

### Manual verification

If you prefer to verify signatures manually, follow these steps:

#### Step 1: Extract the headers

Extract the `webhook-id`, `webhook-timestamp`, and `webhook-signature` headers from the request.

#### Step 2: Prepare the signed payload

The signed payload is created by concatenating:

- The `webhook-id` value
- The character `.`
- The `webhook-timestamp` value
- The character `.`
- The raw request body (JSON payload)

For example: `event_123abc.1674087231.{"id":"event_123abc",...}`

#### Step 3: Compute the expected signature

Compute an HMAC-SHA256 using your endpoint's signing secret as the key and the signed payload as the message. Then Base64-encode the result and prefix it with `v1,`.

#### Step 4: Compare signatures

Compare the computed signature to each signature in the `webhook-signature` header (signatures are space-separated when multiple secrets are active during rotation). Use a constant-time string comparison to protect against timing attacks.

Also verify that the `webhook-timestamp` is within an acceptable time window (e.g., 5 minutes) to prevent replay attacks. You can use the `webhook-id` as an idempotency key to prevent processing duplicate 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 automatically.

Events and webhooks


# Wire Drawdown Requests

Wire Drawdown Requests, sometimes colloquially known as "reverse wires", are a specialized type of Fedwire message that effectively asks a bank to send you a wire transfer for a specific amount. Think of it as a formal request saying "please send me $X via wire transfer."

Contrary to what you might expect, this feature doesn't usually work for most typical bank accounts. If you send a drawdown request to a consumer bank account in the US, the receiving bank likely won't even surface it in their user interface or notify the account holder.

Instead, Wire Drawdown Requests are most useful when you have a pre-negotiated relationship with your counterparty where they'll periodically send you wires, and the drawdown request serves as a cue for them to do so. This is common in business-to-business scenarios where regular settlements occur such as payroll or automated clearing.

For example, when Increase settles with Visa every night, this happens by Visa sending Increase's bank account a drawdown request, to which we then send a Wire Transfer in response.

## How Wire Drawdown Requests work with Increase

### Sending a drawdown request

To send a Wire Drawdown Request, use the [Create Wire Drawdown Request API](/documentation/api/wire-drawdown-requests#create-a-wire-drawdown-request). This will send a Fedwire message to the specified bank requesting they send you a wire transfer. Because of the nuances described above, we ask that you first reach out to [support@increase.com](mailto:support@increase.com) to enable the API for you.

If the counterparty sends a wire in response to your request, we'll update the `status` field from `pending` to `fulfilled` and populate the `fulfillment_inbound_wire_transfer_id` field with the ID of the resulting inbound wire transfer. We'll also send a `wire_drawdown_request.updated` webhook to notify you of the fulfillment.

### Receiving a drawdown request

If someone sends you a Wire Drawdown Request, we'll create an [Inbound Wire Drawdown Request](/documentation/api/inbound-wire-drawdown-requests#inbound-wire-drawdown-requests) object and send an `inbound_wire_drawdown_request.created` webhook to notify you.

You can then review the request and decide whether to fulfill it by sending a wire transfer to the requesting party using the [Create Wire Transfer API](/documentation/api/wire-transfers#create-a-wire-transfer). Note that there's no automatic fulfillment - you'll need to explicitly initiate the wire transfer if you choose to honor the request.


Learn more about wire drawdown requests and how you can use them.

Wire Drawdown Requests


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

## Reversal reason codes

Reversals sent from other banks in response to a wire you sent usually have a [`return_reason_code`](/documentation/api/wire-transfers#wire-transfer-object.reversal.return_reason_code) associated with them. The reason code, when present, will be a four character sequence, generally from an agreed-upon list of codes defined in the "ISO 20022" specification and called `ExternalReturnReason1Code`. The Fedwire network doesn't strictly validate the return reason codes sent by banks, so some wires will have an undocumented, or missing return code.

The most common codes as `NARR` ("see narrative") and `AC01` ("incorrect account number"). Extra details, like the "narrative", are included in the field [`return_reason_additional_information`](/documentation/api/wire-transfers#wire-transfer-object.reversal.return_reason_additional_information).

| Code   | Description                                          |
| ------ | ---------------------------------------------------- |
| `AC01` | Incorrect Account Number                             |
| `AC02` | Invalid Debtor Account Number                        |
| `AC03` | Invalid Creditor Account Number                      |
| `AC04` | Closed Account Number                                |
| `AC06` | Blocked Account                                      |
| `AC07` | Closed Creditor Account Number                       |
| `AC13` | Invalid Debtor Account Type                          |
| `AC14` | Invalid Agent                                        |
| `AC15` | Account Details Changed                              |
| `AC16` | Account In Sequestration                             |
| `AC17` | Account In Liquidation                               |
| `AG01` | Transaction Forbidden                                |
| `AG02` | Invalid Bank Operation Code                          |
| `AG07` | Unsuccessful Direct Debit                            |
| `AGNT` | Incorrect Agent                                      |
| `AM01` | Zero Amount                                          |
| `AM02` | Not Allowed Amount                                   |
| `AM03` | Not Allowed Currency                                 |
| `AM04` | Insufficient Funds                                   |
| `AM05` | Duplication                                          |
| `AM06` | Too Low Amount                                       |
| `AM07` | Blocked Amount                                       |
| `AM09` | Wrong Amount                                         |
| `AM10` | Invalid Control Sum                                  |
| `ARDT` | Already Returned Transaction                         |
| `BE01` | Inconsistent With End Customer                       |
| `BE04` | Missing Creditor Address                             |
| `BE05` | Unrecognized Initiating Party                        |
| `BE06` | Unknown End Customer                                 |
| `BE07` | Missing Debtor Address                               |
| `BE08` | Bank Error                                           |
| `BE10` | Invalid Debtor Country                               |
| `BE11` | Invalid Creditor Country                             |
| `BE16` | Invalid Debtor Identification Code                   |
| `BE17` | Invalid Creditor Identification Code                 |
| `CN01` | Authorization Canceled                               |
| `CNOR` | Creditor Bank Is Not Registered                      |
| `CNPC` | Cash Not Picked Up                                   |
| `CURR` | Incorrect Currency                                   |
| `CUST` | Requested By Customer                                |
| `DC04` | No Customer Credit Transfer Received                 |
| `DNOR` | Debtor Bank Is Not Registered                        |
| `DS28` | Return For Technical Reason                          |
| `DT01` | Invalid Date                                         |
| `DT02` | Check Expired                                        |
| `DT04` | Future Date Not Supported                            |
| `DUPL` | Duplicate Payment                                    |
| `ED01` | Correspondent Bank Not Possible                      |
| `ED03` | Balance Info Request                                 |
| `ED05` | Settlement Failed                                    |
| `EMVL` | EMV Liability Shift                                  |
| `ERIN` | Extended Remittance Information Option Not Supported |
| `FF03` | Invalid Payment Type Information                     |
| `FF04` | Invalid Service Level Code                           |
| `FF05` | Invalid Local Instrument Code                        |
| `FF06` | Invalid Category Purpose Code                        |
| `FF07` | Invalid Purpose                                      |
| `FOCR` | Following Cancellation Request                       |
| `FR01` | Fraud                                                |
| `FRTR` | Final Response Mandate Canceled                      |
| `G004` | Credit Pending Funds                                 |
| `MD01` | No Mandate                                           |
| `MD02` | Missing Mandatory Information In Mandate             |
| `MD05` | Collection Not Due                                   |
| `MD06` | Refund Request By End Customer                       |
| `MD07` | End Customer Deceased                                |
| `MS02` | Not Specified Reason Customer Generated              |
| `MS03` | Not Specified Reason Agent Generated                 |
| `NARR` | Narrative                                            |
| `NOAS` | No Answer From Customer                              |
| `NOCM` | Not Compliant                                        |
| `NOOR` | No Original Transaction Received                     |
| `PINL` | PIN Liability Shift                                  |
| `RC01` | Bank Identifier Incorrect                            |
| `RC03` | Invalid Debtor Bank Identifier                       |
| `RC04` | Invalid Creditor Bank Identifier                     |
| `RC07` | Invalid Creditor Bank Identification Code Identifier |
| `RC08` | Invalid Clearing System Member Identifier            |
| `RC11` | Invalid Intermediary Agent                           |
| `RF01` | Not Unique Transaction Reference                     |
| `RR01` | Missing Debtor Account Or Identification             |
| `RR02` | Missing Debtor Name Or Address                       |
| `RR03` | Missing Creditor Name Or Address                     |
| `RR04` | Regulatory Reason                                    |
| `RR05` | Regulatory Information Invalid                       |
| `RR06` | Tax Information Invalid                              |
| `RR07` | Remittance Information Invalid                       |
| `RR08` | Remittance Information Truncated                     |
| `RR09` | Invalid Structured Creditor Reference                |
| `RR11` | Invalid Debtor Agent Service Identification          |
| `RR12` | Invalid Party Identification                         |
| `RUTA` | Return Upon Unable To Apply                          |
| `SL01` | Specific Service Offered By Debtor Agent             |
| `SL02` | Specific Service Offered By Creditor Agent           |
| `SL11` | Creditor Not On Whitelist Of Debtor                  |
| `SL12` | Creditor On Blacklist Of Debtor                      |
| `SL13` | Maximum Number Of Direct Debit Transactions Exceeded |
| `SL14` | Maximum Direct Debit Transaction Amount Exceeded     |
| `SP01` | Payment Stopped                                      |
| `SP02` | Previously Stopped                                   |
| `SVNR` | Service Not Rendered                                 |
| `TM01` | Cut Off Time                                         |
| `TRAC` | Removed From Tracking                                |
| `UPAY` | Undue Payment                                        |


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