# Increase > Increase builds modern banking APIs that enable technology companies to programmatically store, move, and reconcile money. Key features and benefits: - Bare Metal APIs directly from the Federal Reserve. Major financial networks like Visa and FedACH have evolved over decades. Often, technology companies try to hide or abstract away their complexity, which limits what you can build. We take a different approach and strive to expose the full power. We connect you directly to the Federal Reserve, Visa, and other networks so you can get unfiltered access, more stability, and a flexible implementation. - Move money faster and more reliably. Programmatically send and receive ACH, wires, real-time payments, and even physical checks. - Store and reconcile funds with flexibility. All the building blocks you need to support whatever your unique funds flows require. - Create a robust card program. ​​Increase integrates directly with Visa as an issuer processor, offering direct access to underlying network data. - Instantly provision unlimited accounts, account numbers, and cards. ## Resources - [Documentation](https://increase.com/documentation.md): Increase's documentation site. For LLMs, any URL starting with `https://increase.com/documentation` works with a `.md` suffix. - [Updates](https://increase.com/updates.md): Changelog of all product releases, feature improvements, and bug fixes. ## Features - [Accounts](https://increase.com/documentation/accounts-and-account-numbers.md): Instantly provision bank accounts ia our API. - [ACH Transfers](https://increase.com/documentation/sending-ach-transfers.md): Send and receive ACH Transfers via API. Increase hits every same-day ACH window. - [Check Transfers](https://increase.com/documentation/originating-checks.md): Send checks via API. Increase supports positive pay, prints and mails customizeable checks (with USPS and Fedex), and supports tracking and stopping payment on checks. - [Wire Transfers](https://increase.com/documentation/sending-wire-transfers.md): Send and receive Wire Transfers programatically via API. - [Real-Time Payments](https://increase.com/documentation/sending-real-time-payments.md): Send and receive transfers over the Real-Time Payments network via API. - [Card Issuing](https://increase.com/documentation/programmatic-card-processing.md): Issue physical and virtual cards backed by real bank accounts. Control spend on them with our APIs. ## Customers - [Ramp](https://increase.com/customers/ramp): How Ramp scaled a successful bill pay product with Increase - [Ascend](https://increase.com/customers/ascend): How Ascend facilitates payments and automates insurance AR/AP workflows with Increase - [CapitalOS](https://increase.com/customers/capitalos): How CapitalOS built their spend management platform on Increase ## Getting started - [Signup](https://dashboard.increase.com): Sign up for an Increase account and start moving money today. - [Agent authentication](https://increase.com/auth.md): Agents can create a sandbox Group and obtain a sandbox API key with one unauthenticated request, no human signup required. - [Pricing](https://increase.com/pricing): Increase pricing plans flexibility. ## Solutions - [Bill Pay](https://increase.com/solutions/bill-pay): Scalable bill pay infrastructure. Manage payments with unmatched flexibility and control. Programmatically fund, disburse, and reconcile your payment flows effortlessly. - [Wallets](https://increase.com/solutions/wallets): A complete platform for money storage. Instantly open Accounts with a full suite of capabilities—from moving money to issuing cards. - [Fund Administration](https://increase.com/solutions/fund-administration): Simplified fund administration. Dependable, transparent, and secure tools for managing funds, capital calls, and distributions with ease. - [Payroll](https://increase.com/solutions/payroll): Build reliable payroll solutions. Move high volumes of critical payments with confidence. Originate and track payments with unmatched control and flexibility. - [Embedded Lending](https://increase.com/solutions/embedded-lending): Provide capital to your customers with embedded lending. Give your customers instant access to capital through virtual cards, physical cards or disbursements via bank transfers. - [Vertical SaaS](https://increase.com/solutions/vertical-saas): Payments and financial services for vertical SaaS platforms. --- Source: https://increase.com/documentation/3d-secure.md # 3D Secure [3D Secure](https://www.emvco.com/emv-technologies/3-d-secure/) (3DS) is a protocol governed by EMVCo that lets you verify a cardholder’s identity before a card payment is authorized. Unlike card authorizations, 3DS follows a strict state machine with well-defined stages. When a merchant initiates a 3DS authentication attempt, Increase creates a `card_authentication` entry on the [Card Payment](/documentation/api/card-payments). The 3DS API is composed of a few parts: - **Card Payments API:** The `card_authentication` element under a Card Payment covers the lifecycle of a 3DS authentication attempt. - **Real-Time Decisions API:** Two real-time decision categories, `card_authentication_requested` and `card_authentication_challenge_requested`, let you control the authentication flow. - **Simulations API:** Sandbox endpoints for testing the full authentication flow. ## Authentication flow A challenge-based authentication unfolds as three separate requests: 1. The merchant’s request for 3DS authentication, which you decision to create a Card Authentication 2. The cardholder’s device initiating the challenge, which triggers sending a one-time code to the cardholder 3. The cardholder entering the one-time code to complete the Card Authentication The Card Authentication object tracks the state of the authentication flow. ## Card Authentication lifecycle | Status | Description | | --------------------------------- | --------------------------------------------------------------------------------------------- | | `denied` | The authentication attempt was denied. | | `authenticated_without_challenge` | Approved without requiring a challenge. | | `awaiting_challenge` | A challenge has been requested and we are waiting for the cardholder’s client to initiate it. | | `validating_challenge` | The challenge is in progress and the cardholder is entering their one-time code. | | `authenticated_with_challenge` | The cardholder successfully completed the challenge. | | `timed_out_awaiting_challenge` | The cardholder’s client did not initiate the challenge in time. | | `exceeded_attempt_threshold` | The cardholder exceeded the maximum number of challenge attempts. | | `canceled` | The authentication was canceled. | | `errored` | An error occurred during the authentication. | A Card Authentication progresses through a series of statuses as the authentication attempt is processed. Here is a typical challenge-based flow: 1. We receive an authentication request from Visa with metadata about the purchase. You receive a `card_authentication_requested` [real-time decision](/documentation/real-time-decisions). You [action the real-time decision](/documentation/api/real-time-decisions#action-a-real-time-decision) with `card_authentication.decision` set to `challenge`, which causes a Card Authentication to be created in status `awaiting_challenge`. 2. The cardholder’s client (a browser or app) connects to Increase to initiate the challenge. We generate a one-time code and send you a `card_authentication_challenge_requested` real-time decision containing the code. You deliver it to your cardholder via text message or email. The authentication moves to `validating_challenge`. 3. The cardholder enters the one-time code. If correct, the authentication moves to `authenticated_with_challenge`. We generate a cryptographic Cardholder Authentication Verification Value (CAVV) that is sent to the acquirer through Visa. 4. The acquirer kicks off the card authorization, including the CAVV in the authorization message to tie it to the successful authentication. The Card Payment now has both a `card_authentication` and a `card_authorization` element. If at step 1 you are confident in the transaction, you can approve the Card Authentication directly. This results in a status of `authenticated_without_challenge` and skips the challenge steps entirely. Denying it instead resolves the Card Authentication to `denied`. Merchants usually decide on their own whether to start 3D Secure. To ask a merchant to authenticate a purchase you would otherwise decline, see [Requesting 3D Secure](/documentation/real-time-decisions#requesting-3d-secure). ## Real-time decisions We recommend first reading our [Real-Time Decisions guide](/documentation/real-time-decisions) for background on how real-time webhooks work. ### Responding to authentication requests ![card\_authentication\_requested real-time decision](/images/card_authentication_requested.png) When a merchant attempts to authenticate a purchase, Increase creates a Real-Time Decision with `category: card_authentication_requested`. This comes with metadata about the purchase including merchant details and the purchase amount. Your application decides how to proceed: - **`approve`**: Authenticate the transaction without a challenge (frictionless). - **`challenge`**: Request the cardholder to verify their identity with a one-time code. - **`deny`**: Deny the authentication attempt outright. To action the decision, `POST` to the Real-Time Decision action endpoint: ```curl curl -X "POST" \ --url "https://api.increase.com/real_time_decisions/${REAL_TIME_DECISION_ID}/action" \ -H "Authorization: Bearer ${INCREASE_API_KEY}" \ -H "Content-Type: application/json" \ -d '{ "card_authentication": { "decision": "challenge" } }' ``` ### Delivering the challenge ![card\_authentication\_challenge\_requested real-time decision](/images/card_authentication_challenge_requested.png) If you request a challenge, the cardholder’s client (browser or app) will connect to Increase to start the challenge process. Increase creates a second Real-Time Decision with `category: card_authentication_challenge_requested`. This decision includes a `one_time_code` that you must deliver to your cardholder via text message or email. Once you’ve delivered the code, action the decision with the result: ```curl curl -X "POST" \ --url "https://api.increase.com/real_time_decisions/${REAL_TIME_DECISION_ID}/action" \ -H "Authorization: Bearer ${INCREASE_API_KEY}" \ -H "Content-Type: application/json" \ -d '{ "card_authentication_challenge": { "result": "success" } }' ``` If your application is unable to deliver the one-time code, respond with `"result": "failure"`. After the challenge is delivered, Increase renders an interface to the cardholder where they enter the one-time code. We validate their attempts and update the `card_authentication` status accordingly. ## Testing in sandbox You can simulate the end-to-end authentication flow using three sandbox endpoints. ### 1. Simulate an authentication attempt [Create a simulated 3DS authentication request](/documentation/api/card-payments#sandbox-create-a-card-authentication-attempt) for a card: ```curl curl -X "POST" \ --url "${INCREASE_URL}/simulations/card_authentications" \ -H "Authorization: Bearer ${INCREASE_API_KEY}" \ -H "Content-Type: application/json" \ -d '{ "card_id": "card_oubs0hwk5rn6knuecxg2" }' ``` This returns a Card Payment with a `card_authentication` element. If you have a `card_authentication_requested` real-time decision subscription, you’ll receive the webhook and can action the decision. ### 2. Simulate initiating a challenge After requesting a challenge, [simulate the cardholder’s client connecting](/documentation/api/card-payments#sandbox-create-an-initial-card-authentication-challenge) to start the challenge: ```curl curl -X "POST" \ --url "${INCREASE_URL}/simulations/card_authentications/${CARD_PAYMENT_ID}/challenges" \ -H "Authorization: Bearer ${INCREASE_API_KEY}" ``` This triggers the `card_authentication_challenge_requested` real-time decision with the one-time code. ### 3. Simulate a challenge attempt [Simulate the cardholder entering the one-time code](/documentation/api/card-payments#sandbox-create-a-card-authentication-challenge-attempt): ```curl curl -X "POST" \ --url "${INCREASE_URL}/simulations/card_authentications/${CARD_PAYMENT_ID}/challenge_attempts" \ -H "Authorization: Bearer ${INCREASE_API_KEY}" \ -H "Content-Type: application/json" \ -d '{ "one_time_code": "123456" }' ``` Alternatively, you can navigate to `https://dashboard.increase.com/card_authentication_simulation/${CARD_PAYMENT_ID}` and enter the one-time code directly. If the code matches, the `card_authentication` status moves to `authenticated_with_challenge`. --- Source: https://increase.com/documentation/accounts-and-account-numbers.md # 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 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) --- Source: https://increase.com/documentation/ach-returns.md # ACH returns Explicitly, FedACH doesn’t intermediate disputes. This is different from the card networks. However, both the originator and recipient have the means to request a transfer be recalled: - A recipient can Return a transfer back to the originator. - An originator can request a Reversal of the transfer from the recipient. When these mechanisms don’t work, Nacha recommends using non-ACH related dispute resolution mechanisms like contacting the account holder, collections agencies, or courts. When you send an [ACH transfer](/documentation/api/ach-transfers) from Increase, you may receive a return from the receiving bank. When you receive an [Inbound ACH transfer](/documentation/api/inbound-ach-transfers) in your Increase account, you’ll be able to respond with a return. ## How returns work with FedACH ### Types of returns Returns fall into three broad categories: - **Administrative returns** are caused by issues like an unrecognized account number, an invalid routing number, or insufficient funds. The administrative ACH returns are `R02`, `R03`, and `R04`. - **Unauthorized returns** occur when the account holder states the transfer was not authorized. The unauthorized return codes are `R05`, `R07`, `R10`, `R11`, `R29`, and `R51`. - **All other returns** cover any alternative return reason. This includes the most common return reason: `R01` “insufficient funds.” ### Return rate monitoring ACH Originators must keep their return rate below certain thresholds to remain in good standing with Nacha. Return rates are calculated on a 60-day rolling basis as a ratio between the received returns and originated debits in that sixty-day window. | Return type | Threshold | | --------------------- | --------- | | Administrative debits | 3.0% | | Unauthorized debits | 0.5% | | Total returns | 15% | ### Reconciling returns Returns can be correlated with originating transfers using the date, amount, account number, routing number, and trace number. Trace numbers are 15 digits but with only seven digits of entropy (the leading eight identify the originating financial institution). For any reasonably large institution, it’s usually not possible to uniquely rely on trace numbers for reconciling returns. Increase automatically reconciles ACH returns and ACH transfers. ### Return windows ACH debits can be returned within two business days for commercial accounts[0](#user-content-fn-commercial-returns) and sixty calendar days for consumer accounts[1](#user-content-fn-consumer-returns). To reduce unauthorized returns, Nacha recommends (and in some cases requires) validation of account and routing number details before originating a transfer. ### Late returns and proof of authorization Despite the standard return windows, a receiving bank may submit a late return request, asking the originating bank for permission to return a debit to a business account after the deadline has passed. These requests typically follow a claim that the debit was unauthorized. The originating bank can respond by providing [proof of authorization](/documentation/sending-ach-debit-transfers#debit-authorizations), or by accepting the late return, in which case the receiving bank sends the return — commonly as `R31` “Permissible Return Entry” or `R06` “Returned per ODFI’s Request.” If you have a debit returned after the typical window, you’ll see a proof of authorization request appear in your Dashboard. You have 10 banking days to respond from the time the request is received[2](#user-content-fn-proof-of-authorization). Alternatively, you can accept the return, or not respond and let Increase do so on your behalf; in either case, the receiving bank is permitted to conduct the return. To provide proof of authorization, you’ll supply the original authorization details (authorizer name and contact information, time of authorization, and authorization terms) and confirm how you verified the customer’s access to the debited account, as described in [verifying account access](/documentation/setting-up-ach-debits#verify-account-access). You can also attach supporting documents, such as the signed authorization, as additional evidence. ## Reinitiating returned ACH transfers A returned transfer can be reinitiated only under specific circumstances: | Acceptable circumstances | | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | An ACH debit returned for reasons of insufficient or uncollected funds (`R01`, `R09`) can be reinitiated a maximum of two times to attempt to recollect funds. | | An ACH debit returned for a reason of a stopped payment (`R08`) may be reinitiated if the originator obtains a valid authorization from the receiver to do so. In this instance, it’s important to encourage the receiver to notify their receiving financial institution to remove any stopped payment blocks associated with the originator. | | An ACH transfer was returned for a different reason, but the issue has been remedied by the originator. | In all instances, reinitiating must take place within 180 days of the settlement date of the original transfer. Beyond 180 days, all resolution must take place outside of the ACH network. A reinitiated transfer must be submitted with the `company_entry_description` set to `RETRY PYMT`. However, it otherwise must contain identical information to the original transfer, including the `company_name`, `company_identification`, and `amount` fields. Other fields may be modified only to the extent that they correct an error or enable successful processing of a transfer. Any modification to these fields in order to present it as a new transfer will be treated as a violation of the Nacha rules. Beyond the reasons above, reinitiating transfers is prohibited. However, Nacha rules specify four scenarios where a transfer is not considered a “reinitiated entry” and therefore is outside of the requirements above. | Not considered a reinitiated entry | | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | If an originator has preauthorization for sending recurring debits, and a debit transfer is returned, subsequent debits are not considered “reinitiated entries.” For example, if a user’s monthly credit card payment is returned due to insufficient funds, the following monthly payment is still eligible. | | If an originator receives a new authorization from the receiver after receiving a return, the new transfer will not be considered a “reinitiated entry.” | | If an originator receives a return due to incorrect account or routing information (`R03`, `R04`), retrying the transfer with correct account information will not be considered a “reinitiated entry” because it is not technically associated with the same account. | | If an originator receives a return due to not being within the agreed terms of authorization (`R11`), and they are able to resolve the issue to meet the original terms, they can retry the transfer without obtaining a new authorization from the receiver. | ## How returns work at Increase If you receive a return, Increase will automatically reconcile it with the originating transfer and create a new Transaction to reduce your balance. You can view the `return` [details](/documentation/api/ach-transfers#ach-transfer-object.return), including the `return_reason_code` and the associated `transaction_id` on the initial transfer. This will allow you to instantly map each of your returns to their initial Transactions. You can also view these details in the Dashboard. ![Dashboard ACH returns](/images/docs-ach-return-timeline.png) ## Return Reason Codes ACH returns are accompanied by a Return Reason Code which is used to describe the reason for the return. While there are \~80 codes, returns most commonly use `R01`, `R02`, `R03`, `R04`, `R05`, `R06`, `R07`, `R08`, `R09`, and `R10`. | Code | Description | | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [`R01`](#r01) | **Insufficient Funds** - The available balance is not sufficient to cover the amount of the debit entry. | | [`R02`](#r02) | **Account Closed** - The previously active account has been closed by the customer or the bank. | | [`R03`](#r03) | **No Account on file** - The account number does not correspond to the individual identified in the entry, or the account number designated is not an open account. | | [`R04`](#r04) | **Invalid Account Number** - The account number provided is incorrect or improperly formatted. | | [`R05`](#r05) | **Unauthorized Debit to Consumer Account Using Corporate SEC Code** - A CCD or CTX debit entry was posted to a consumer account, and the consumer has notified the receiving institution (RDFI) that the entry was not authorized. | | [`R06`](#r06) | **Returned per ODFI’s Request** - The originating institution (ODFI) requested that the receiving institution (RDFI) return the transaction. | | [`R07`](#r07) | **Authorization Revoked by Customer** - The Receiver revoked the authorization previously provided. | | [`R08`](#r08) | **Payment Stopped** - The Receiver placed a stop payment order on the debit Entry. | | [`R09`](#r09) | **Uncollected Funds** - The Receiver has a sufficient cash balance but an insufficient available balance. | | [`R10`](#r10) | **Customer Advises Not Authorized** - The Receiver has claimed that the provided authorization is not valid. | | [`R11`](#r11) | **Customer advises not within Authorization Terms** - An authorization to debit exists, but the Receiver has claimed that the entry doesn’t conform to the terms of the authorization. For example, the amount is different or the settlement was earlier than authorized. | | [`R12`](#r12) | **Account Sold to Another DFI** - The account has been sold to another financial institution. | | [`R13`](#r13) | **Invalid ACH Routing Number** - The Receiving Depository Financial Institution (RDFI) is not qualified to participate in ACH or the routing number is invalid. | | [`R14`](#r14) | **Representative Payee Deceased** - The representative payee is deceased or unable to continue in that capacity. The beneficiary is not deceased. | | [`R15`](#r15) | **Beneficiary or Account Holder Deceased** - The beneficiary or account holder is deceased. | | [`R16`](#r16) | **Account Frozen** - (1) Access to the account is restricted due to specific action by the Receiving Depository Financial Institution (RDFI) or by legal action. (2) OFAC has instructed the RDFI to return the entry. | | [`R17`](#r17) | **File Record Edit Criteria** - (1) Field(s) cannot be processed by RDFI; (2) the Entry contains an invalid Account Number (account closed/no account/unable to locate account/invalid account number) and is believed by the RDFI to have been initiated under questionable circumstances. (3) Either the RDFI or Receiver has identified a Reversing Entry as one that was improperly initiated by the Originator or ODFI. | | [`R18`](#r18) | **Improper Effective Entry Date** - Entries have been returned because the effective entry date is not a valid banking day or is more than two banking days in the future. | | [`R19`](#r19) | **Amount Field Error** - (1) Amount field is non-numeric. (2) The amount field is not zero in a Prenotification, Notification of Change, refused Notification of Change, DNE, ENR, or zero dollar CCD, CTX, or IAT Entry. (3) The amount field is zero in an Entry other than a Prenotification, Notification of Change, refused Notification of Change, DNE, ENR, or zero dollar CCD, CTX, or IAT. (4) The amount field is greater than $25,000 for ARC, BOC, and POP Entries. | | [`R20`](#r20) | **Non-Transaction Account** - The ACH entry was attempted for a non-transaction account—an account against which transactions are prohibited or limited. | | [`R21`](#r21) | **Invalid Company Identification** - The company ID information is not valid (usually applies to CCD and CTX entries). | | [`R22`](#r22) | **Invalid Individual ID Number** - The Receiver has indicated that the individual ID number used in the entry is not valid. | | [`R23`](#r23) | **Credit Entry Refused by Receiver** - The Receiver has refused the credit entry. | | [`R24`](#r24) | **Duplicate Entry** - The Receiving Depository Financial Institution (RDFI) has identified the entry as a duplicate. The trace number, date, dollar amount and/or other data matches another transaction. | | [`R25`](#r25) | **Addenda Error** - There is an error with the Addenda. (1) The Addenda Record Indicator value is incorrect. (2) The Addenda Type Code is invalid, out of sequence, or missing. (3) Number of Addenda Records exceeds allowable maximum. (4) Addenda Sequence Number is invalid. | | [`R26`](#r26) | **Mandatory Field Error** - There is erroneous or missing data in a mandatory field. | | [`R27`](#r27) | **Trace Number Error** - (1) The original Trace Number is not present in the Addenda of a Notification of Change or Return. (2) The Trace Number of an Addenda record doesn’t match the Trace number in a preceding Entry Detail Record. | | [`R28`](#r28) | **Routing Number Check Digit Error** - The check digit for a routing number is not valid. | | [`R29`](#r29) | **Corporate Customer Advises Not Authorized** - The Receiver advises that the entry is not authorized. | | [`R30`](#r30) | **RDFI Not Participant in Check Truncation Program** - The Receiving Depository Financial Institution (RDFI) doesn’t participate in a Check Truncation Program. | | [`R31`](#r31) | **Permissible Return Entry (CCD and CTX only)** - The Receiving Depository Financial Institution (RDFI) has been notified by the Originating Depository Financial Institution (ODFI) that it agrees to accept a CCD or CTX return entry beyond normal return time frames. | | [`R32`](#r32) | **RDFI Non-Settlement** - The Receiving Depository Financial Institution (RDFI) is not able to settle the entry. | | [`R33`](#r33) | **Return of XCK Entry** - This Return Reason Code may only be used to return an XCK (Destroyed Check) entry. | | [`R34`](#r34) | **Limited Participation DFI** - The Receiving Depository Financial Institution’s (RDFI) participation in a specific ACH program has been limited by a federal or state supervisor. | | [`R35`](#r35) | **Return of Improper Debit Entry** - Debit Entries are not permitted to loan accounts or for CIE Entries. | | [`R36`](#r36) | **Return of Improper Credit Entry** - Credit Entries are not permitted for ARC, BOC, POP, RCK, TEL, and XCK entries. | | [`R37`](#r37) | **Source Document Presented for Payment** - The source document to which an ARC, BOC, or POP Entry relates has been presented for payment. | | [`R38`](#r38) | **A stop payment was placed on the source document of the transaction.** - The Receiving Depository Financial Institution (RDFI) has determined that a stop order has been placed on the source document related to the ARC or BOC Entries. | | [`R39`](#r39) | **Improper Source Document** | | [`R40`](#r40) | **Return of ENR Entry** | | [`R41`](#r41) | **Invalid Transaction Code** | | [`R42`](#r42) | **Routing Number / Account Number Mismatch** | | [`R43`](#r43) | **Invalid DFI Account Number** | | [`R44`](#r44) | **Invalid Individual Identifier** | | [`R45`](#r45) | **Invalid Individual Name** | | [`R46`](#r46) | **Invalid Representative Payee Indicator** | | [`R47`](#r47) | **Duplicate Enrollment** | | [`R50`](#r50) | **State Law Affecting RCK Acceptance** | | [`R51`](#r51) | **Item is Ineligible, Notice Not Provided** | | [`R52`](#r52) | **Stop Payment on Item** | | [`R53`](#r53) | **Item and ACH Entry Presented for Payment** | | [`R61`](#r61) | **Misrouted Return** | | [`R62`](#r62) | **Incorrect Trace Number** | | [`R63`](#r63) | **Incorrect Dollar Amount** | | [`R64`](#r64) | **Incorrect Individual Identification** | | [`R65`](#r65) | **Incorrect Transaction Code** | | [`R66`](#r66) | **Incorrect Company Identification** | | [`R67`](#r67) | **Duplicate Return** | | [`R68`](#r68) | **Untimely Return** | | [`R69`](#r69) | **Multiple Errors** | | [`R70`](#r70) | **Permissible Return Entry Not Accepted / Notice Not Provided** | | [`R71`](#r71) | **Misrouted Dishonored Return** | | [`R72`](#r72) | **Untimely Dishonored Return** | | [`R73`](#r73) | **Timely Original Return** | | [`R74`](#r74) | **Corrected Return** | | [`R75`](#r75) | **Return Not a Duplicate** | | [`R76`](#r76) | **No Errors Found** | | [`R77`](#r77) | **Non-Acceptance of R62 Dishonored Return** | | [`R78`](#r78) | **Non-Acceptance of R68 Dishonored Return** | | [`R79`](#r79) | **Incorrect Data in Return Entry** | | [`R80`](#r80) | **IAT Entry** | | [`R81`](#r81) | **Non-Participant in IAT Program** | | [`R82`](#r82) | **Invalid Foreign Receiving DFI Identification** | | [`R83`](#r83) | **Foreign Receiving DFI Unable to Settle** | | [`R84`](#r84) | **Entry Not Processed by Gateway** | | [`R85`](#r85) | **Incorrectly Coded Outbound International Payment** | ## Notes 1. Nacha Operating Guidelines, Section II, Chapter 26 Returns of Unauthorized/Improper Corporate Debits [↩](#user-content-fnref-commercial-returns) 2. Nacha Operating Guidelines, Section II, Chapter 26 Returns of Unauthorized/Improper/Incomplete Consumer Debit Entries [↩](#user-content-fnref-consumer-returns) 3. Nacha Operating Rules Subsection 2.3.2.7 Retention and Provision of the Record of Authorization [↩](#user-content-fnref-proof-of-authorization) --- Source: https://increase.com/documentation/ach-reversals.md # 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 that all fields be 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 an 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. --- Source: https://increase.com/documentation/ach-standard-entry-class-codes.md # 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 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 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. Payroll credit transfers must use a Company Entry Description that starts with `PAYROLL`. | | `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. Debits for e-commerce purchases must use a Company Entry Description that starts with `PURCHASE`. | | `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 a rare message used by an ACH Operator to provide a participating financial institution with a machine-readable accounting record of the entries that settled to its account. | | `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 a 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. | --- Source: https://increase.com/documentation/address-verification-system-codes-and-overrides.md # 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 was 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 is 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 into 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 provide any overrides, both overrides must be set. 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`). --- Source: https://increase.com/documentation/atm-withdrawals.md # ATM withdrawals Increase cards support cash withdrawals at Automated Teller Machines (ATMs). Increase routes ATM transactions over three networks: [Visa](/documentation/visa), [Plus](https://en.wikipedia.org/wiki/Plus_\(interbank_network\)) (Visa’s ATM network), and [Pulse](https://en.wikipedia.org/wiki/Pulse_\(interbank_network\)) (Discover’s debit and ATM network). An ATM withdrawal arrives in the [Card Payment](/documentation/card-payment-lifecycle) in one of two shapes: either a `card_authorization` entry followed by a `card_settlement` entry, or a single `card_financial` entry. Which shape arrives depends on the card. Integrations should handle both. ## Identifying an ATM withdrawal To distinguish ATM withdrawals from other Card Payments, check `processing_category` on a `card_authorization` or `card_financial` entry. ATM withdrawals (and, less commonly, cash advances at a point of sale) use `cash_disbursement`. ```json { "type": "card_financial", "processing_category": "cash_disbursement", "amount": 10000, "currency": "USD", ... } ``` You can subscribe to `card_authorization.created`, `card_settlement.created`, and `card_financial.created` Events to be notified as these entries are added to the Card Payment. ## Single-message and dual-message processing Card networks support two processing models. In dual-message processing, an authorization message ([ISO 8583](https://en.wikipedia.org/wiki/ISO_8583) `0100`) reserves funds, and a separate clearing file later posts the transaction. In single-message processing, one `0200` message both authorizes and clears the transaction at once. Visa supports both, and translates between them when the acquirer and issuer use different models. Which one Increase receives depends on the card’s bank identification number (BIN), the prefix on the card number that identifies the issuer. See [Launch a Card Program](/documentation/launch-a-card-program) for background on Increase’s BIN types. - Cards on Increase’s credit BINs use dual-message processing for all transactions, including ATM withdrawals. The withdrawal arrives as a `card_authorization` entry, and Increase records a matching `card_settlement` entry once Visa’s clearing file arrives. - Cards on Increase’s debit BINs use single-message processing for ATM withdrawals. The withdrawal arrives as a `card_financial` entry that authorizes and clears in one step. You don’t need to check the BIN to know which shape arrived. The entry types in the Card Payment make it clear. The two models behave differently when an ATM fails to dispense cash. Under dual-message, the unsettled authorization can be reversed and no Transaction is created. Under single-message, the Transaction has already posted, so the reversal arrives as a separate offsetting entry, and the Account ends up with two opposing Transactions. ## Finalization A `card_authorization` entry triggers a hold on funds, not a posted Transaction. Increase represents the hold as a Pending Transaction on the Account. When the matching `card_settlement` entry arrives, the Pending Transaction completes and Increase posts a Transaction. Visa delivers its daily clearing file around 10:00 UTC each business day, so most ATM withdrawals settle within one business day. A `card_financial` entry both authorizes and clears in one step. Increase posts the Transaction immediately. A `card_authorization` entry can still be reversed before it settles. When that happens, Increase records a `card_reversal` entry and releases the Pending Transaction. No Transaction is ever created. To confirm that a withdrawal completed, wait for a `card_settlement` or `card_financial` entry. A `card_authorization` entry on its own is a useful early signal, but be prepared to handle a subsequent `card_reversal` entry. ## Interchange ATM withdrawals invert the typical [interchange](/documentation/visa) flow on Visa. For ordinary card purchases, the merchant’s acquirer pays interchange to Increase. For ATM withdrawals, Increase pays interchange to the ATM operator’s acquirer. ## Examples ### A typical single-message withdrawal 1. A user withdraws $100 from an ATM. 2. A `card_payment` is created. It includes a `card_financial` entry for $100 with `processing_category` of `cash_disbursement`. 3. A `transaction` is created for -$100 on the Account. ### A typical dual-message withdrawal 1. A user withdraws $100 from an ATM. 2. A `card_payment` is created. It includes a `card_authorization` entry for $100 with `processing_category` of `cash_disbursement`. 3. A `pending_transaction` for -$100 is created on the Account to hold the funds. 4. The following morning, a `card_settlement` entry is created for $100. 5. The `pending_transaction` for -$100 completes. 6. A `transaction` is created for -$100 on the Account. ### A failed dual-message withdrawal 1. A user attempts to withdraw $100 from an ATM. 2. A `card_payment` is created. It includes a `card_authorization` entry for $100 with `processing_category` of `cash_disbursement`. 3. A `pending_transaction` for -$100 is created on the Account to hold the funds. 4. The ATM fails to dispense cash. 5. A `card_reversal` entry is received for $100. 6. The `pending_transaction` is released, and no `transaction` is created. --- Source: https://increase.com/documentation/card-art.md # Digital wallets Increase’s [Cards](/documentation/api/cards) can be added to [Digital Wallet](/documentation/api/digital-wallet-tokens) 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, which is configured with a [Digital Card Profile](/documentation/api/digital-card-profiles). ## Card art image The main card artwork ([`background_image_file_id`](/documentation/api/digital-card-profiles#create-a-digital-card-profile.background_image_file_id)) 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 its design standards. The image needs to include a Visa logo of a specific size and in one of three spots. You can either use our [Figma template](/digital_card_template_20260520.fig) or Visa’s [Illustrator template](/digital_card_master_opt1_2022_US.ai) for the specific card type you’re issuing (e.g., `VISA CORPORATE`). The full rules can be accessed [here](/Digital-Card-Art_rules_20260223.pdf). ## Icon image The icon image ([`app_icon_file_id`](/documentation/api/digital-card-profiles#create-a-digital-card-profile.app_icon_file_id)) 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`](/documentation/api/digital-card-profiles#create-a-digital-card-profile.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](/documentation/api/real-time-decisions). See the [real-time decisions guide](/documentation/real-time-decisions) for how to set up a handler. Once tokenization completes, a [Digital Wallet Token](/documentation/api/digital-wallet-tokens) is created for the Card. ### 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 [`digital_wallet.phone`](/documentation/api/cards#card-object.digital_wallet.phone) and/or [`digital_wallet.email`](/documentation/api/cards#card-object.digital_wallet.email) populated. To action the [`real_time_decision.digital_wallet_token_requested`](/documentation/api/events#event-object.category.real_time_decision.digital_wallet_token_requested) event, you call the [`/real_time_decisions/:id/action`](/documentation/api/real-time-decisions#action-a-real-time-decision) endpoint like usual, populating the [`digital_wallet_token`](/documentation/api/real-time-decisions#action-a-real-time-decision.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`](/documentation/api/events#event-object.category.real_time_decision.digital_wallet_authentication_requested) real-time decision handler is present. Once you receive the [real-time decision](/documentation/api/real-time-decisions#real-time-decision-object.digital_wallet_authentication), you would be responsible for sending the two-factor code to the requested email or phone number, followed by [actioning the real-time decision](/documentation/api/real-time-decisions#action-a-real-time-decision.digital_wallet_authentication) once that’s done. ![Apple Pay enter two-factor code](/images/apple_pay_verify.png) --- Source: https://increase.com/documentation/card-art-physical-cards.md # 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 text and images. Cards support EMV and NFC contactless payments. You can use this [Figma template](/physical_card_and_carrier_template_20260320.fig) to design your card art and carrier images. ## Card layout The front of the card displays the card art image, Visa logo, EMV chip, and optionally one or two lines of custom text. The back of the card displays the cardholder name, card number, expiration date, CVV, and magstripe. ### Front text You can optionally print up to two lines of text on the front of the card using the `front_text` field when creating a [Physical Card Profile](https://increase.com/documentation/api/physical-card-profiles). The first line of text is printed on the front of the card. Providing a second line moves the first line slightly higher and prints the second line in the spot where the first line would have otherwise been printed. ## 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) ## Fulfillment speed By default, cards ship out the day after the order is received by the card printer. The cut-off for physical card orders is 1am Pacific Time. If you create a physical card Monday evening, the card printer will receive the order Tuesday morning Pacific Time and ship it out on Wednesday. To ship sooner, pass [`shipment.schedule: same_day`](https://increase.com/documentation/api/physical-cards#physical-card-object.shipment.schedule.same_day) when creating the card. With `same_day`, the example above would ship out on Tuesday instead. ## Shipping speed Increase supports the following shipping methods: - USPS - FedEx 2-day - FedEx Priority Overnight - DHL Worldwide Express (international only) USPS does not provide a tracking number, but we surface tracking updates from USPS’s Informed Visibility system through [`shipment.tracking.updates`](https://increase.com/documentation/api/physical-cards#physical-card-object.shipment.tracking.updates) on the Physical Card. For the other carriers we provide a tracking number, and we deliver tracking updates directly through the API as well so you don’t have to fetch them from the carrier. --- Source: https://increase.com/documentation/card-authorization-controls.md # Card authorization controls An authorization requests approval for an amount before the merchant submits it for settlement. You can restrict which requests Increase approves by declaring controls on the card, deciding each request through a real-time webhook, or using both. These rules govern authorization; they do not prevent a merchant from submitting a different amount for settlement. ## Where a rule lives Declare controls on the card when the rule depends on an amount, the card’s spending history, or the merchant information in the request. Increase evaluates these controls without a round trip to your server. A vendor card restricted to one merchant and $250 can use card controls alone, and those controls keep working when your server is unavailable. Use [Real-time decisions](/documentation/real-time-decisions) for rules that depend on state only your application holds: an invoice’s approval status, an employee’s remaining budget across several cards, or whether a trip is still active. Your handler must retrieve and action the decision before its deadline. If you subscribe to authorization decisions, passing the card’s controls still requires a response from your handler. By default, a timeout declines the request. You can combine the two. Declare a monthly limit on an employee’s card and use your handler to check whether the employee is still permitted to spend. The handler can decline a request that passed the card’s controls, but cannot approve one that failed them. ## Creating a card with controls Include `authorization_controls` in the body of `POST /cards`. This sandbox request creates a single-use card for exactly $250, restricted to one merchant acceptor ID. Replace `ACCOUNT_ID` with your sandbox Account ID and use your sandbox API key. Amounts are in cents. ```curl curl -X "POST" \ --url "https://sandbox.increase.com/cards" \ -H "Authorization: Bearer ${INCREASE_API_KEY}" \ -H "Content-Type: application/json" \ -d '{ "account_id": "ACCOUNT_ID", "description": "Vendor invoice", "authorization_controls": { "usage": { "category": "single_use", "single_use": { "settlement_amount": { "value": 25000, "comparison": "equals" } } }, "merchant_acceptor_identifier": { "allowed": [{"identifier": "5665270011000168"}] } } }' ``` For an existing card, send `authorization_controls` to `PATCH /cards/{card_id}`. See the [create](/documentation/api/cards#create-a-card.authorization_controls) and [update](/documentation/api/cards#update-a-card.authorization_controls) references for the full request shapes. You can also configure usage, spending limits, and merchant category or acceptor restrictions in the Dashboard. Open the card and select **Authorization controls**. Card authorization controls work the same way in sandbox. Use the [card authorization simulation](/documentation/api/card-payments#sandbox-create-a-card-authorization) to test requests against your controls. ## Restricting usage and amount ### One payment Use a single-use card for one payment of a known or bounded amount. For a $250 invoice, require exactly $250. If the final invoice is not yet known, permit an authorization of at most $250. A $200 approval consumes the single use; it does not leave $50 for another payment. For a positive authorization amount, Increase counts the card’s prior authorizations and single-message financial transactions, then subtracts full authorization reversals. If that count is greater than zero, the request is declined. Otherwise, Increase compares the requested amount in the settlement currency with the configured amount. This comparison happens during authorization, despite the API’s use of the name `settlement_amount`. A full reversal restores the use. A partial reversal, expiration, or refund does not. A zero-dollar validation bypasses the single-use count and amount comparison, but still has to pass the merchant restrictions. Refund authorizations bypass card controls; recorded refund authorizations and financial transactions are nevertheless included in the single-use count. ### Repeated spending Use a multi-use card with spending limits for repeated payments. A $2,000 monthly limit permits requests until the amount already counted plus the new request would exceed $2,000. A request that brings the total to exactly $2,000 passes this control. Limits can apply to each request, a calendar day, week, month, or the card’s lifetime. A limit can cover all merchants or only specified merchant category codes (MCCs), the four-digit codes that classify a merchant’s business. A category-specific limit counts only spending in those categories and does not restrict requests in other categories. All matching limits apply. With a $2,000 monthly limit across all merchants and a $500 monthly restaurant limit, a restaurant authorization needs capacity under both. A narrower limit does not override a broader one. ## Restricting merchants Merchant restrictions compare the information in the authorization request with an allow list or a block list: - **Merchant categories** restrict types of business. An office supplies category restriction applies to merchants classified in that category, not to individual items in a purchase. - **Merchant acceptor IDs** restrict particular acceptors. The merchant acceptor ID identifies the merchant accepting the payment; it is distinct from the merchant descriptor displayed with the transaction. Use the ID submitted in authorizations for the vendor you intend to pay. - **Merchant countries** restrict the merchant country reported in the request, using two-letter country codes such as `US` and `CA`. This does not establish the cardholder’s location. An allow list declines values outside the list. A block list declines values in the list. Choose one list type for each dimension; the API does not accept both for the same dimension. Omit a dimension to impose no additional restriction on it. Category, acceptor, and country restrictions all apply together, along with the usage and amount controls. These lists cannot override Increase’s built-in restrictions. See [Card issuing fraud controls](/documentation/card-issuing-fraud-controls) for the built-in restrictions and recommended categories and countries to consider for your program. ## Evaluation and declines For a purchase authorization, Increase first checks card and account eligibility and built-in controls, including restricted categories and countries, verification failures, and merchant blocking. We then evaluate the card’s usage and spending limits, followed by its category, acceptor, and country restrictions. Any breach declines the request before your authorization webhook is sent. If those checks pass and you have an authorization decision subscription, we send the real-time webhook. Available balance is checked after your approval, using the approved amount. Without that subscription, available balance is checked before the card controls. An approval from your handler therefore does not override insufficient available funds. Card controls evaluate the requested amount before your handler can offer a partial approval. A card-control decline creates a [Declined Transaction](/documentation/api/declined-transactions) with `source.card_decline.reason` of `breaches_limit`. This reason covers merchant restrictions as well as amount limits; it does not identify the individual rule. For Visa, Increase returns response code `61`, activity amount limit exceeded. The merchant controls the message shown to the cardholder and does not receive your control configuration. A declined initial authorization creates no hold. A declined increment leaves the existing hold in place. ## Limits through the payment lifecycle ### Increments and settlements An increment requests an additional amount against an existing authorization. Increase evaluates that additional amount against the controls currently on the card. With $800 counted against a $1,000 monthly limit, a $200 increment passes and a $201 increment fails. Once approved, the increment increases the pending hold used by subsequent limit checks. A per-transaction limit compares only the amount of the current request. A $500 authorization followed by a $100 increment can pass a $500 per-transaction limit even though the hold reaches $600. Use an interval limit if the accumulated amount matters. A single-use card declines a positive increment once its initial authorization has consumed the use. Settlement does not run authorization controls or send an authorization decision webhook. A merchant can settle $1,050 against a $1,000 hold even when the card has a $1,000 limit. The $1,050 settlement counts toward subsequent interval checks, which can then decline further spending. An exact-amount single-use control likewise checks the authorization, not the eventual settlement. ### Reversals and refunds A reversal reduces or releases an authorization’s pending hold. A partial reversal from $800 to $300 reduces the amount counted to $300; a full reversal removes the pending amount. Expiration also removes the hold from the running total. These changes restore interval capacity only if that hold was counted in the interval. A refund posts a separate credit. Refunds and pending refund authorizations do not subtract from the spending total, so a $100 refund after a $500 settlement leaves $500 counted. Refund authorizations still undergo Increase’s initial eligibility and built-in restriction checks, but bypass the card’s controls and the authorization decision webhook. ### Interval boundaries Daily limits reset at midnight UTC, weekly limits on Monday at midnight UTC, and monthly limits on the first of the month at midnight UTC. These are calendar intervals, not rolling windows. Lifetime limits do not reset. Increase selects records by when each was created. A pending authorization is assigned to the interval containing its original creation time, even if it is incremented later. A settlement is assigned to the interval in which the settlement record is created. An authorization on September 30 that settles on October 1 therefore counts against September while pending, then against October when settled. An older hold still pending on October 1 is excluded from October’s monthly total; incrementing it does not change its original creation time. ### Changing controls Updating `authorization_controls` replaces the previous control set rather than merging individual rules. Include the controls you intend to retain. An update that omits `authorization_controls` leaves the existing set in place. The new set applies when Increase next evaluates a request, including an increment on an existing authorization. It does not cancel existing holds, re-evaluate an authorization already sent to your handler, or prevent settlement. Changing controls also does not clear spending history: new limits use the card’s existing records within the selected interval. Lowering a monthly limit below the amount already counted causes subsequent positive requests to decline. --- Source: https://increase.com/documentation/card-disputes.md # 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 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](/documentation/api/card-disputes) fully models these rules for each dispute category the card networks expose. ## Starting a Card Dispute To start a [Card Dispute](/documentation/api/card-disputes) with Increase, you call [`POST /card_disputes`](/documentation/api/card-disputes#create-a-card-dispute) with the disputed [Transaction](/documentation/api/transactions), the amount you want to dispute, and other required details including any [Files](/documentation/api/files) 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](/documentation/api/card-disputes#card-dispute-object.visa.user_submissions). 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](/documentation/api/card-disputes#card-dispute-object.visa.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](/documentation/api/card-disputes#card-dispute-object.visa.user_submissions) 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](/documentation/api/card-disputes). | | `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. | | `rejected` | The Card Dispute was rejected before reaching the network, either by Increase or by a withdrawal. | ## User Submissions To ensure the greatest chance of winning a Dispute, Increase reviews each [User Submission](/documentation/api/card-disputes#card-dispute-object.visa.user_submissions) 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 are contained in the [`further_information_requested_reason`](/documentation/api/card-disputes#card-dispute-object.visa.user_submissions.further_information_requested_reason) property on the User Submission. As outlined below, the status of the [Card Dispute](/documentation/api/card-disputes) 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`](/documentation/api/card-disputes#create-a-card-dispute) and when subsequent User Submissions are submitted with [`POST /card_disputes/:card_dispute_id/submit_user_submission`](/documentation/api/card-disputes#submit-a-user-submission-for-a-card-dispute). 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](/documentation/api/card-disputes#card-dispute-object.visa.user_submissions) are required. When a [Card Dispute](/documentation/api/card-disputes) is in the `user_submission_required` status, the category of User Submission required can be determined from the [`required_user_submission_category`](/documentation/api/card-disputes#card-dispute-object.visa.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`](/documentation/api/card-disputes#card-dispute-object.visa.user_submissions.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`](/documentation/api/card-disputes#card-dispute-object.user_submission_required_by) property of the [Card Dispute](/documentation/api/card-disputes). Warning If you do not submit an approved [User Submission](/documentation/api/card-disputes#card-dispute-object.visa.user_submissions) by the deadline, the cardholder automatically loses the dispute. The merchant may also miss a deadline, in which case the cardholder automatically wins the dispute. The card network measures deadlines in calendar days. Increase needs time to review each User Submission before sending it to the card network, so submit as early as you can rather than close to the deadline. A Card Dispute must be submitted to the card network within a window that depends on its `category`. Windows are counted from when the transaction was processed unless noted, and never extend past 540 days after it. | **Category** | **Deadline** | | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `fraud` | 120 days. | | `authorization` | 75 days. | | `processing_error` | 120 days. | | `consumer_merchandise_not_received` `consumer_services_not_received` | 120 days, or 120 days after the last expected delivery date. Wait 15 days after a cancellation or return before submitting (30 days for travel and ticket merchants). | | `consumer_canceled_merchandise` `consumer_canceled_services` | 120 days, or 120 days after the expected delivery date. Wait 15 days after the cancellation or return before submitting. | | `consumer_canceled_recurring_transaction` | 120 days. | | `consumer_merchandise_not_as_described` `consumer_services_not_as_described` `consumer_damaged_or_defective_merchandise` `consumer_quality_merchandise` `consumer_quality_services` | 120 days, or 120 days after delivery. Wait 15 days after a return or cancellation before submitting. | | `consumer_merchandise_misrepresentation` `consumer_services_misrepresentation` | 120 days, or 120 days after delivery. | | `consumer_counterfeit_merchandise` | 120 days, or 120 days after delivery or after the cardholder learned it was counterfeit. | | `consumer_credit_not_processed` | 120 days after the date on the credit receipt. Wait 15 days after that date before submitting. | | `consumer_non_receipt_of_cash` | 120 days. | | `consumer_original_credit_transaction_not_accepted` | 120 days. | After that, each response is due within 30 days of the step before it: | **Step** | **Deadline** | | ---------------------------------------------------------------- | -------------------------------------------------- | | Merchant decides to re-present or start pre-arbitration | 30 days after the Card Dispute is submitted. | | Cardholder decides to submit a `user_prearbitration` | 30 days after the merchant re-presents. | | Merchant decides to accept or decline the `user_prearbitration` | 30 days after it is submitted. | | Cardholder decides to submit a `merchant_prearbitration_decline` | 30 days after the merchant starts pre-arbitration. | `user_submission_required_by` is set slightly ahead of these deadlines so Increase has time to review and submit your User Submission. You can also always withdraw an active Card Dispute for a cardholder by calling [`POST /card_disputes/:card_dispute_id/withdraw`](/documentation/api/card-disputes#withdraw-a-card-dispute). If Increase has not yet accepted the dispute for submission to the card network, it is rejected outright; otherwise the withdrawal is submitted to the network and the dispute is lost. ## Network Events [Network Events](/documentation/api/card-disputes#card-dispute-object.visa.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](/documentation/api/card-disputes#card-dispute-object.visa.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](/documentation/api/card-disputes) with the initial [User Submission](/documentation/api/card-disputes#card-dispute-object.visa.user_submissions) by calling [`POST /card_disputes`](/documentation/api/card-disputes#create-a-card-dispute), 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`](/documentation/api/card-disputes#submit-a-user-submission-for-a-card-dispute), 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 `user_submission_required` status and the process continues from step 2 onward 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. ## Card Dispute Financial Transactions As a [Card Dispute](/documentation/api/card-disputes) progresses, money will move as a 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 [User Submission](/documentation/api/card-disputes#card-dispute-object.visa.user_submissions) is made. These money movements are represented by [Card Dispute Financial Transactions](/documentation/api/transactions#transaction-object.source.card_dispute_financial). If a given [Network Event](/documentation/api/card-disputes#card-dispute-object.visa.network_events) has caused money movement, a Card Dispute Financial Transaction will be present by reference in the [`dispute_financial_transaction_id`](/documentation/api/card-disputes#card-dispute-object.visa.network_events.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](/documentation/api/card-disputes) with chargeback information using [`POST /card_disputes`](/documentation/api/card-disputes#create-a-card-dispute), but the [Network Events](/documentation/api/card-disputes#card-dispute-object.visa.network_events) and subsequent [User Submission](/documentation/api/card-disputes#card-dispute-object.visa.user_submissions) categories depend on the process. ### The Allocation dispute process In this process, the cardholder is effectively assumed right from the outset. 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](/documentation/api/card-disputes#card-dispute-object.visa.user_submissions) and [Network Events](/documentation/api/card-disputes#card-dispute-object.visa.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](/documentation/api/card-disputes#card-dispute-object.visa.user_submissions) and [Network Events](/documentation/api/card-disputes#card-dispute-object.visa.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). --- Source: https://increase.com/documentation/card-elements.md # Card elements Card Elements is a React library that displays the sensitive details of a [Card](/documentation/api/cards) — its number, expiration date, verification code, and PIN — inside your own interface. Each value renders in its own `