## Transaction Statuses

- `APPROVAL_REQUIRED` - Approval required by Payer, based on Payer configuration
- `CANCELLED` - Cancelled/voided
- `FAILED` - Failed due to decline or account error
- `PAID` - Transaction was successfully processed
- `PENDING_KYC` - Transaction under review by compliance team
- `PROCESSING` - Transaction is in process and waiting confirmation on completion or failure
- `RETRY` - Transaction will be re-attempted based on scheduled process or manually through support channels
- `REFUNDED` - Transaction has been refunded based on refunds against the originating transaction
- `REFUNDED_PARTIAL` - Transaction has been partially refunded based on refunds against the originating transaction
- `REVERSED` - Transaction reversed
- `REVERSAL_PENDING` - Transaction reversal requested and under review
- `UNKNOWN` - Transaction processed but final status is unknown, based on Payer configuration for `UNKNOWN` response, otherwise will be considered `PAID` until final status is determined. Only applicable to `INSTANT_DEPOSIT`

## Transaction Types

Transaction Type indicates the direction of funds. `CREDIT` indicates you are sending funds to a Recipient. `DEBIT` indicates you are accepting funds from a Recipient.

## Transaction Methods

Transaction Method indicates how to disperse or accept funds. Transaction Type indicates the direction of funds, either `CREDIT` or `DEBIT` the user (recipient).

Portal and Reporting may show a more detailed description of `PREPAID` based on the account type they are funding.

| Method | Type | Description | Recipient Requirements |
| --- | --- | --- | --- |
| ACH_FUNDING | DEBIT | ACH Transaction processed on the same day if submitted before 2:45PM Eastern during business days. | Bank account |
| ACH_FUNDING_PLUS | DEBIT | ACH Transaction processed on the same day if submitted before 2:45PM Eastern during business days. Failed transactions due to R01 ACH Return Code will be automatically retried at a configured interval. | Bank account |
| ACH_REFUND | CREDIT | ACH Transaction processed on the same day if submitted before 2:45PM Eastern during business days. Must reference an originating transaction ID. | Bank account |
| ACH_SAME_DAY | CREDIT | ACH Transaction processed on the same day if submitted before 2:45PM Eastern during business days. | Bank account |
| ACH_STANDARD | CREDIT | ACH Transaction processed in 3-5 business days. | Bank account |
| CHECK | CREDIT | Paper Check | Address |
| ECHECK | CREDIT | Electronic Check | Email |
| INSTANT_DEPOSIT | CREDIT | Funds transferred to an account via Debit Card | Debit card account |
| INSTANT_FUNDING | DEBIT | Funds transferred from a Debit Card | Debit card account |
| PAYPAL | CREDIT | Funds transferred via PayPal | PayPal Account |
| PREPAID | CREDIT | Funds loaded onto a Prepaid Account | Prepaid account |
| RTP | CREDIT | Funds transferred to a Bank Account | Bank account |
| VENMO | CREDIT | Funds transferred via Venmo | Venmo Account |

## Transaction Request Schemas

The following parameters are applicable for every Transaction method. A subset of Transaction methods have optional request parameters identified in their respective areas below.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| recipient_id | String | Yes | Recipient ID |
| account_id | String | Yes | Payment Account ID |
| type | String | Yes | Direction of funds |
| method | String | Yes | Transaction method |
| amount | Double | Yes | Transaction amount |
| reference_id | String | No | Transaction reference ID |
| memo | String | No | Transaction memo |
| location_id | String | Maybe | Valid State or US Territory\nPossibly required for compliance purposes |
| meta_params | JSON | No | JSON string of values to include for reporting requirements\nPlease consult with technical team on usage |

#### ECheck

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| email | String | No | Email override for ECHECK transactions |

#### ACH Funding / ACH Funding Plus

ACH Funding / ACH Funding Plus allows for a `funding_options` request object with risk-associated parameters.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| funding_option.user_segment | String | No | Segment name to indicate user cohort |
| funding_options.ip_address | String | No | User's IP address, can help mitigate against fraudulent transactions |
| funding_options.user_agent | String | No | User agent of user's device, can help mitigate against fraudulent transactions |

#### ACH Refund

ACH Refund request requires the originating Transaction ID to match against the original transaction.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| originating_transaction_id | String | Yes | Originating Transaction ID to be referenced |

## Transaction Webhooks

Webhooks are essential to knowing the latest status of a transaction. A Transaction webhook will be sent with the initial Transaction request and all subsequent status updates. Review the [Webhooks](https://docs-v2.interchecks.com/docs/webhooks) documentation page for samples and further details.

## Transaction Error Codes

A comprehensive list of error codes and descriptions can be found at [API Error Codes](https://docs-v2.interchecks.com/docs/api-error-codes). `4xx` responses follow a consistent format shown below. Under certain conditions the error response will contain a `transaction_id` and/or additional risk metrics associated with the transaction.

JSON

```json
{
    "http_status": 4xx,
    "error_code": "{error code}",
    "error_message": "{error description}"
}
```

### ACH Funding Error Codes

Specific to ACH Funding, there are additional error codes as a result of pre-transaction checks for velocity, bank balance lookup, and risk score evaluation. Risk-related error codes will include a `funding_options_response` object with configured threshold values and actual values.

| Error Code | Details |
| --- | --- |
| ERR_ACCOUNT_BALANCE_THRESHOLD | Balance does not meet required threshold for transaction |
| ERR_ACCOUNT_BALANCE_UNAVAILABLE | Plaid bank account balance is unavailable, a new transaction request can be issued with `balance_check`: `false` to bypass the balance check |
| ERR_ACCOUNT_RE_AUTH_REQUIRED | Plaid account requires re-authorization and the user will have to go through the Bank Account Widget workflow |
| ERR_ACCOUNT_RISK_BANK_BALANCE_THRESHOLD | Bank risk threshold was exceeded _and_ the bank balance multiplier was not met. The bank balance requirement then starts at 200% and increases an additional 100% for every PROCESSING transaction |
| ERR_ACCOUNT_RISK_LEVEL_NOT_CONFIGURED | Client incorrectly configured for `risk_level` passed into the `funding_options` object or is not setup with default risk threshold levels |
| ERR_ACCOUNT_RISK_METRICS_UNAVAILABLE | Plaid risk data is unavailable, a new transaction request can be issued with `risk_check`: `false` to bypass the risk check |
| ERR_ACCOUNT_RISK_THRESHOLD | Consumer risk threshold was exceeded |
| ERR_PROVIDER_ACCOUNT_MISCONFIGURATION | Client incorrectly configure for Plaid integration |
| ERR_VELOCITY_LIMIT | Velocity limit reached |

### ACH Refund Error Codes

| Error Code | Details |
| --- | --- |
| ERR_INVALID_ORIGINATING_TRANSACTION_ID | The originating Transaction ID is invalid or not found |
| ERR_REFUND_INVALID_ORIGINATING_METHOD | The originating Transaction method is not an ACH_FUNDING or ACH_FUNDING_PLUS transaction |
| ERR_REFUND_INVALID_ORIGINATING_STATUS | The originating Transaction status is not PAID or REFUNDED_PARTIAL |
| ERR_REFUND_AMOUNT_EXCEEDED | The refund request amount plus any previous refunds toward the original transaction exceeds the original transaction amount |