# Account Number Reservations Source: https://docs.treasuryprime.com/docs/account-number-reservations Reserve account numbers before creating accounts to support onboarding workflows that require pre-assigned account numbers Account number reservations require the `account_number_reservation` entitlement. Contact [Treasury Prime support](mailto:help@treasuryprime.com) to enable this feature for your organization. ## What are account number reservations? Account number reservations let you obtain and reserve an account number before formally opening an account. The reserved account number is allocated from your organization's configured account number prefix and held exclusively for your use until you create an account with it. This feature supports use cases where an account number must be known ahead of time, such as: * Pre-assigning account numbers during onboarding flows before account approval * Displaying account numbers to customers before account creation completes * Integrating with external systems that require account numbers upfront * Building multi-step onboarding experiences where account details are needed early Account number reservations are specific to an account product. When you create a reservation, Treasury Prime allocates an account number from the pool associated with that account product's configured prefix. ## How account number reservations work Creating an account number reservation involves calling the [`POST /account_number_reservation`](reference/post_account_number_reservation) endpoint with an account product ID. Treasury Prime immediately allocates an account number from the configured prefix for that account product and returns a reservation object containing the reserved account number. The reservation remains valid until you use it to create an account by passing the reservation ID in the `account_number_reservation_id` field when creating an account application. Each reservation can only be used once. ### Creating a reservation When you create an account number reservation: 1. **Treasury Prime validates the account product**: The system checks that the account product exists and that your organization has the `account_number_reservation` entitlement enabled. 2. **Treasury Prime allocates an account number**: The system reserves an account number from the pool associated with the account product's configured prefix. 3. **Treasury Prime creates the reservation object**: The system creates an account number reservation object with the allocated account number and account product ID. 4. **Treasury Prime returns the reservation**: The API response includes the reservation ID and the reserved account number. ##### Example request to create an account number reservation ```bash bash theme={null} curl -X POST \ -u $API_KEY_ID:$API_SECRET_KEY \ https://api.treasuryprime.com/account_number_reservation \ -H 'Content-Type: application/json' \ -d '{ "account_product_id": "apt_11ffk99xyzy" }' ``` ##### Example response ```json json theme={null} { "created_at": "2024-01-15T11:55:14Z", "updated_at": "2024-01-15T11:55:14Z", "id": "anr_123456789", "account_number": "1301550041234", "account_product_id": "apt_11ffk99xyzy" } ``` ### Using an account reservation To use a reserved account number when creating an account, include the `account_number_reservation_id` field in your account application request: ##### Example request to create an account application with a reservation ```bash bash theme={null} curl -X POST \ -u $API_KEY_ID:$API_SECRET_KEY \ https://api.treasuryprime.com/apply/account_application \ -H 'Content-Type: application/json' \ -d '{ "person_applications": [ { "id": "apsn_01d5w6yaa6vt", "roles": ["owner", "signer"] } ], "primary_person_application_id": "apsn_01d5w6yaa6vt", "account_product_id": "apt_11ffk99xyzy", "account_number_reservation_id": "anr_123456789" }' ``` For more details on creating an account application, see [Account Number Reservation API Reference](/reference/post_apply_person_application). When the account application is approved and the account is created, Treasury Prime uses the reserved account number from the reservation instead of allocating a new account number. ### Retrieving reservations You can retrieve existing reservations using the [`GET /account_number_reservation`](/reference/get_account_number_reservation) endpoint to list all reservations, or [`GET /account_number_reservation/:id`](/reference/get_account_number_reservation-id) to fetch a specific reservation by ID. ## Key considerations ### Account product compatibility * **Reservations are account product-specific**: Each reservation is tied to a specific account product. You must use the reservation with an account application for the same account product. * **Prefix validation**: Treasury Prime validates that the reserved account number matches your organization's configured prefix when creating the account. ### Reservation usage * **No expiration**: Reservations do not expire. A reserved account number remains allocated until you use it to create an account. * **Cannot be deleted or released**: Once created, reservations cannot be deleted or released. The account number remains reserved indefinitely. * **Single use only**: Each reservation can only be used once. ### Validation and errors * **Entitlement required**: The `account_number_reservation` entitlement must be enabled for your organization. Attempting to create a reservation without this entitlement returns a `403` error: `"You are not entitled to use this feature at this time: account_number_reservation"`. * **Account product must exist**: The account product ID must reference a valid account product. Attempting to create a reservation with an invalid account product ID returns a `404` not found error. * **Reservation ID must match account product**: When creating an account application, the `account_number_reservation_id` must reference a reservation for the same account product specified in `account_product_id`. Mismatched account products return a `400` error: `"account_number_reservation_id is not valid for the provided account_product_id"`. * **Reservation cannot be reused**: After a reservation is used to create an account, attempting to reuse the same reservation ID on another account application returns a `400` error: `"account_number_reservation_id already used on an application."` ### Bank-specific behavior Account number reservation behavior may vary by partner bank: * **Treasury Prime ledger accounts**: Reservations allocate account numbers from the configured prefix for the account product. * **Partner bank core accounts**: Reservations may interact with the partner bank's account numbering system. Contact support for bank-specific details. *** For detailed API endpoint documentation, parameter specifications, and response schemas, see the [Account Number Reservation API Reference](/reference/post_account_number_reservation). # Account Statements Source: https://docs.treasuryprime.com/docs/account-statements Generate and retrieve branded monthly account statements for your customers. Monthly statements are generated as PDF files and stored securely, accessible via the API whenever your customers need them. This guide covers how to configure statement settings, generate statements for specific accounts and time periods, and retrieve existing statements. ## What are account statements? Account statements are monthly documents that summarize account activity for a specific period. Each statement includes account holder information and mailing address, beginning and ending balances for the statement period, and a detailed transaction history with dates, descriptions, and amounts. Statements also include a summary of deposits, withdrawals, and fees; interest earned and Annual Percentage Yield (APY) information where applicable; customer service contact information; and required regulatory disclosures. You can retrieve statements via the API or display them to customers directly through your application. ### Key benefits * **Regulatory compliance**: Statements include required disclosures for Regulation E and other banking regulations * **Customer transparency**: Provide customers with a clear record of all account activity * **Customizable branding**: Add your logo, business name, and customer support information * **Secure delivery**: Statements are stored securely and accessed via authenticated API calls ## How account statements work Generate account statements in two steps: 1. **Configure statement settings**: Create a [Statement Config](/reference/post_statement_config) that defines your branding, contact information, and formatting preferences 2. **Generate statements**: Use the [Create Statement](/reference/post_account_statement) endpoint to generate statements for specific accounts and time periods Treasury Prime automatically generates statements for all configured accounts on the 2nd of each month, covering the prior full calendar month. No API call is required. ### Statement configuration Before generating statements, create a statement configuration that includes: * **Business information**: Legal name and physical address * **Customer support details**: Phone number, email address, and support website * **Branding**: Logo file (PNG, JPEG, or TIFF format, scaled to fit 360x54 pixels) * **APY display**: Annual Percentage Yield as a percentage or custom text for tiered rates * **Formatting options**: Timezone for transaction dates, transaction ID display, authorized user display * **Regulatory text**: Footnotes and bank disclosure messages Statement configurations can be created per account or shared across multiple accounts within your organization. ### Generating statements To generate a statement, call the [Create Statement](/reference/post_account_statement) endpoint with: * `account_id`: The account for which to generate the statement * `type`: Statement type (currently only `monthly` is supported) * `date`: Statement date in `YYYY-MM` format * `email_address`, `phone_number`, `support_url`, `org_legal_name`: Required branding and contact fields * `footnote`: Required field for regulatory language, including Reg E customer complaint information * `apy` or `apy_custom`: One of these must be provided * `interest_earned`: Optional field to display interest earned on the account during the statement period * `statement_template_id`: Optional. ID of a custom statement template to use for rendering. Contact your Treasury Prime representative to set one up. The API returns a statement object containing a `url` field that points to the generated PDF file. ##### Example request to generate a monthly statement ```bash bash theme={null} curl -X POST \ -u $API_KEY_ID:$API_SECRET_KEY \ https://api.treasuryprime.com/account/acct_1029384756/statement \ -H 'Content-Type: application/json' \ -d '{ "type": "monthly", "date": "2024-03", "email_address": "support@example.com", "phone_number": "+1 555-123-4567", "support_url": "https://support.example.com", "org_legal_name": "Example Financial Inc", "apy": "3.50", "footnote": "In case of errors or questions about your electronic transfers, call +1 555-123-4567 or write to support@example.com within 60 days of the statement date." }' ``` ##### Example response with statement URL ```bash bash theme={null} { "account_id": "acct_1029384756", "type": "monthly", "date": "2024-03", "url": "https://api.treasuryprime.com/account/acct_1029384756/statement/file_11jq1f6w3h58v", "email_address": "support@example.com", "phone_number": "+1 555-123-4567", "support_url": "https://support.example.com", "org_legal_name": "Example Financial Inc", "apy": "3.50", "footnote": "In case of errors or questions about your electronic transfers, call +1 555-123-4567 or write to support@example.com within 60 days of the statement date." } ``` ### Retrieving existing statements To retrieve a previously generated statement, use the [Get Statement](/reference/get_account_statement) endpoint: ```bash bash theme={null} curl -X GET \ -u $API_KEY_ID:$API_SECRET_KEY \ 'https://api.treasuryprime.com/account/acct_1029384756/statement?type=monthly&date=2024-03' ``` The response contains the `url` field pointing to the PDF file. If no statement exists for the specified date, the API returns a 404 error. ## Additional key points about account statements ### Transaction display Statements display transactions in chronological order with the following information: * **Date**: Transaction date in the configured timezone (defaults to UTC) * **Description**: Human-readable transaction description * **Deposits**: Credit amounts (displayed in the deposits column) * **Withdrawals**: Debit amounts (displayed in the withdrawals column) * **Balance**: Running account balance after each transaction When `show_transaction_ids` is enabled, the Treasury Prime transaction ID appears alongside each transaction description. ### Summary section Each statement includes a summary showing: * Beginning balance at the start of the statement period * Total deposits for the period * Total withdrawals for the period * Total fees charged * Interest earned (if applicable) * Annual Percentage Yield (if applicable) * Ending balance at the end of the statement period ### Fee breakdown (optional) When enabled for your organization, statements can include a detailed fee breakdown table showing overdraft fees and returned item fees for both the current period and year-to-date totals. This feature requires the `statement_fee_breakdown` setting to be enabled for your organization. The fee breakdown appears as a separate section on the statement with: * Overdraft fees (monthly and year-to-date) * Returned item fees (monthly and year-to-date) Contact your Treasury Prime representative to enable this feature for your organization. ### Regulatory disclosures Regulation E error resolution procedures and customer complaint information must be provided in the required `footnote` parameter, which appears as plain text at the bottom of the statement. The content of this field is subject to approval by your partner bank. The bank disclosure message appears in the footer of each page and defaults to "Account offered by \[Bank Name] Member FDIC" unless customized via the `bank_disclosure_message` parameter. ### Page breaks in footnotes You can insert page breaks within the `footnote` field to split regulatory disclosures or other footnote content across multiple pages. To create a page break, include a form feed character (`\f`) in the footnote text at the location where you want the page break to occur. When a form feed character is present in the footnote, the statement generator splits the content at each form feed and places each section on a separate page. This is useful for lengthy regulatory disclosures or when you need to separate different types of footnote content. ##### Example footnote with page break ```json theme={null} { "footnote": "First page of regulatory disclosures and important information.\f Second page of additional disclosures and terms." } ``` The content before `\f` appears on one page, and the content after `\f` appears on the next page. You can include multiple form feed characters to create multiple page breaks. ## Important considerations 1. **Automatic generation**: Treasury Prime automatically generates statements for all ledger accounts on the 2nd of each month, covering the prior full calendar month. If you manually generate a statement for a specific month before the automatic generation runs, the system skips automatic generation for that account and month to prevent duplicates. 2. **Statement period**: Monthly statements cover transactions from the first day to the last day of the specified month. The statement date parameter uses `YYYY-MM` format. 3. **Future dates not allowed**: Statements cannot be generated for future months. Requests with future dates return an error. 4. **Configuration requirements**: A statement configuration is required for automatic monthly generation on the 2nd of each month. When manually generating statements via the API, you can either use an existing statement configuration or provide all required fields directly in the request body. 5. **APY requirements**: Either `apy` or `apy_custom` must be provided when generating statements. Use `apy` for simple percentage rates or `apy_custom` for tiered or complex rate structures. 6. **Logo format**: Logo files must be PNG, JPEG, or TIFF format. Images are automatically scaled to fit within a 360x54 pixel region while preserving aspect ratio. 7. **Timezone handling**: Transaction timestamps are formatted according to the `timezone` parameter (defaults to UTC). Use canonical timezone strings from the tz database (e.g., `America/New_York`). 8. **Authorized users**: When `display_authorized_user` is enabled, persons with the `authorized_user` role appear above the owner name on the statement in the format `[Authorized User Name], Representative Payee for [Owner Name]`. 9. **Bank approval required**: Statement content, including footnotes and disclosure messages, is subject to approval by your partner bank. 10. **Sandbox testing**: In the Sandbox environment, statements contain example transactions that do not correspond to actual account activity. See [Statement Testing](/reference/statement-testing) for details. 11. **Statement storage**: Generated statements are stored securely and remain accessible via the API. Statements are not automatically deleted. # Overview Source: https://docs.treasuryprime.com/docs/ach ACH (Automated Clearing House) is an electronic network for financial transactions in the United States. ACH transfers allow you to move money between bank accounts without paper checks, wire transfers, or cash. ACH transfers created via the API are "API originated" transfers processed through the Treasury Prime platform. To create ACH transfers via the Treasury Prime API, see the [ACH Transfer](/docs/ach-transfer) guide. ## Types of ACH Transfers ACH supports two types of transfers: credit and debit. Also referred to as the “direction” of the transfer, the type of transfer selected determines whether the funds are pushed to a recipient's account, or pulled from their account. ### ACH Credit An ACH credit is used when you wish to send or “push” funds to a recipient. An example of an ACH credit transaction is payroll direct deposit, where an employer credits funds to an employee's account. #### Lifecycle of an Originated ACH Credit 1. A balance check is performed on the originating account to ensure sufficient funds are available to cover the transaction. 2. The ACH object is created with an initial `status` of `pending`. 3. A hold is placed on the originating account to secure the funds for the transaction. 4. The ACH `status` transitions to `processing`, the initial hold is released, and a withdrawal is made from the funding account. 5. The `status` of the ACH transitions to `sent` and the NACHA file containing the ACH is sent to the bank for processing. 6. Finally, the funds are deposited into the recipient's bank account. ACH Credit Flow Note that the timing of status changes and funds availability varies by bank and by ACH service. See the the section on [ACH timing](#how-long-does-an-ach-take) below for more detail. ### ACH Debit An ACH debit is used when you wish to “pull” funds from an external account. Bill Payments, where a merchant is given permission to pull funds from their customer's account, is one example of where an ACH debit might be used. **Note:** Originated debit ACHs at or above your bank's [ACH Flag Review Threshold](/docs/flagged-ach#configuring-the-threshold) are flagged for banker review under Treasury Prime's NACHA fraud-monitoring program. Flagging does not delay processing. #### Lifecycle of an originated ACH Debit 1. The ACH object is created with an initial `status` of `pending`. 2. The ACH `status` transitions to `processing`. 3. The `status` of the ACH is updated to `sent` and the `scheduled_settlement` value is set. 4. The NACHA file containing the ACH is sent to the bank for processing. 5. Finally, the funds are deposited into the originating bank account. ACH Debit Flow ## How Long Does an ACH Take? The topic of how long it will take for funds to be received when sending an ACH is a bit complex and often ends in statements like “it depends”. To help clarify this, let’s look at the key factors that determine just how long it will take for the funds from an ACH to be received. ### Service Level ACH supports two levels of service—`standard` and `sameday`—which ultimately determine how fast the ACH will settle. While the type of ACH (`credit` or `debit`), and the processes defined by the Receiving Depository Financial Institution (RDFI) also play a role in settlement time, the general timelines for standard and sameday ACH processing are as follows: | Service | Settlement Time | | - | - | | Standard | 1-3 business days | | Sameday | 0-1 business days | Note that ACH transactions are only processed during business banking days, so you will need to keep this in mind when assessing transfer timelines. ### Submission Time As a matter of practice, ACH transfers are processed in batches by the ODFI (Originating Depository Financial Institution) at set intervals throughout the day. The times at which these batches are processed, known as “processing windows,” are defined by each ODFI, so it is recommended you speak with your Customer Success Manager or Bank Partner(s) to understand the specific timings defined by your partner bank(s). It’s also worth noting that there are separate processing windows for standard and sameday ACH transfers. In order for an ACH to be included in a specific processing window, it needs to be submitted prior to the cut-off time for that window. Treasury Prime defines cut-off times as being 30 minutes prior to the scheduled start of the processing window. To bring this all together, let’s look at the example of a made-up ODFI, Prime Bank. #### Prime Bank ACH Processing Windows | Processing Window | Cut-off Time | Service | | - | - | - | | 11:30 | 11:00 | sameday | | 12:30 | 12:00 | sameday | | 5:30 | 5:00 | standard | Prime Bank offers three ACH processing windows each day: one for standard ACH transfers, and two for sameday ACH transfers. In order for a sameday ACH to be included in the 12:30 processing window, the ACH would need to be created prior to the 12:00 cut-off time. If the cut-off window is missed, then the ACH will be included in the next processing window, which in this case would be 11:30 the following business day (as 12:30 is the final processing window for sameday transfers). ### Direction The direction of the ACH also plays a role in determining how long the transfer will take to complete. Specifically, ACH debits tend to take a bit longer than their credit counterparts. Let’s take a quick look at why this is, and how it affects ACH processing. As it is unknown whether sufficient funds will be available in the account when an ACH debit is initiated, there is an additional level of potential fraud risk introduced in this type of ACH payment. To counteract this, and aid in fraud prevention, ACH debits include a delayed settlement period (imposed by the ODFI) prior to releasing funds to the recipient's account. This delay provides the RDFI an opportunity to fulfill the debit request and, if necessary, respond with an error. While the length of this delay can vary de on the arrangements made with your bank partner, funds for `sameday` ACHs are generally released to the recipient after 48 business hours, and `standard` ACHs after 72 business hours. For ACH debit transfers originating from Treasury Prime ledger accounts, the ACH object will be populated with a `scheduled_settlement` value defining when the funds are expected to become available in the recipient's account. This value is set when the ACH reaches a `status` of `processed` and will take into account the service level selected and any other variables involved in the ACH settlement timing. ## Limits on Total ACH Transaction Amounts A set of velocity limits exists for debit and credit ACH transfers which limit the total dollar amount that can be transacted for each transfer type within a rolling 24-hour period. These limits are defined by your bank partner and can be adjusted with approval from the bank. While separate limits exist for debit and credit ACHs, there is no differentiation among service levels, so both sameday and standard ACHs will count against the daily limit for each type. The timestamp supplied in the `created_at` property of the [ACH object](/reference/ach#the-ach-object) is used to determine which transactions are included within the rolling 24-hour limit. Canceled ACH transactions do not count toward this limit. When these limits are exceeded a 429 status error is returned with a message describing the specific limit exceeded. ## ACH Flag Review Threshold In addition to standard ACH limits (per-transaction or daily), Treasury Prime also supports an **ACH Flag Review Threshold**. Originated debit ACHs at or above this amount are flagged for banker review under our NACHA fraud-monitoring program. Unlike hard limits, the flag threshold does not block transactions — it routes them for post-creation review. Default is **\$10,000**. ## What Data Will Be Shown to ACH Recipients? The short answer to this question is “it depends”. There are a number of parties involved in the processing of ACH transfers, and each plays a role in determining what information is or is not displayed to the end user. For ACH transfers initiated on the Treasury Prime platform, the `description` and `addenda` fields are passed with the transaction; however, whether this information is displayed to the recipient is solely up to the RDFI. As shown in the example below, the recipient of the ACH might see “Test ACH” show up in their banking application, or they might not. It’s up to the RDFI. ```bash bash theme={null} { "description": "Test ACH", "amount": "15.00", "service": "sameday", "counterparty_id": "cp_11gsczk76t1234", "bankdata": { "hold_id": "ttx_11hq81f9ef1234" }, "bank_id": "bank_treasuryprime", "account_id": "acct_11hq4m9aee1234", "addenda": [], "org_id": "org_1evy4cx1234", "batch_key": null, "effective_date": "2022-11-15", "updated_at": "2022-11-15T21:36:38Z", "status": "sent", "id": "ach_11hq81f9ef1234", "error": null, "sec_code": "web", "trace_number": "24015053925610", "scheduled_settlement": null, "direction": "credit", "created_at": "2022-11-15T21:34:33Z", "userdata": { "scheduled_settlement": 15 } } ``` ## Monitoring the status of an ACH The `status` field of the [ACH object](/reference/get_ach-id) represents the current status of the ACH transfer. You can monitor changes to this status (and thus the processing of the ACH) by subscribing to the `ach.update` webhook. It’s important to note that unless an ACH is returned or encounters an error during processing then `sent` will be its terminal status. This is because the ACH network does not support sending updates to confirm the receipt of funds or the successful completion of a transfer after it has been sent for processing. If an error is encountered or an ACH is returned, then the `status` will be updated accordingly. Otherwise, a successful ACH will end in a `status` of `sent`. ## SEC codes The `sec_code` field on the [ACH object](/reference/ach) specifies the type of transfer according to the ACH network. Treasury Prime supports the following SEC codes: | SEC code | Description | | - | - | | `ccd` | Corporate Credit or Debit. Used for business-to-business transactions. | | `ppd` | Prearranged Payment and Deposit. Used for consumer transactions with prior authorization. | | `web` | Internet-Initiated Entry. Used for consumer transactions authorized over the internet. | | `tel` | Telephone-Initiated Entry. Used for consumer transactions authorized over the phone. | | `cie` | Customer Initiated Entry. Used for credit entries initiated by a consumer. | | `arc` | Accounts Receivable Entry. Used to convert a check into an ACH debit. | | `boc` | Back Office Conversion. Used for single-entry check conversions at the point of purchase. | Not all SEC codes are available at every bank. Contact your relationship manager to discuss which SEC codes are supported by your bank partner. ## Tracking originated ACH payments with trace numbers Tracking originated ACH Payment with Trace numbers availability varies by bank partner. Contact your relationship manager to discuss availability and any associated costs. The `trace_number` field on the [ACH object](/reference/ach) provides the 15-digit trace number assigned by the originating bank when an ACH payment is sent. You can use this field to track and reconcile specific originated ACH payments. The trace number is populated after receiving verification of a sent ACH from the originating bank. (Note this is only available at certain bank partners.) To retrieve it, make a `GET` request to the `/ach/:id` endpoint: ```bash bash theme={null} curl -u $API_KEY_ID:$API_SECRET_KEY https://api.treasuryprime.com/ach/ach_5merj00eudnp ``` The response includes the `trace_number` field: ```json json theme={null} { "id": "ach_5merj00eudnp", "amount": "100.00", "direction": "credit", "status": "sent", "trace_number": "24015053925610", "sec_code": "ppd", "service": "standard", "account_id": "acct_1234567890", "counterparty_id": "cp_0987654321" } ``` The `trace_number` field is also available in Prime Data alongside other ACH fields, so you can query it directly from the data warehouse for reporting, reconciliation, and analytics workflows without going through the API. You can also filter by `trace_number` when listing ACH transfers via [`GET /ach`](/reference/get_ach): ```bash theme={null} curl -u $API_KEY_ID:$API_SECRET_KEY \ "https://api.treasuryprime.com/ach?trace_number=123456789012345" ``` ## Filtering ACH transfers by direction You can filter ACH transfers by `direction` when listing transfers via the [`GET /ach`](/reference/get_ach) endpoint. This allows you to retrieve only credit or only debit transfers: ```bash theme={null} curl -u $API_KEY_ID:$API_SECRET_KEY \ "https://api.treasuryprime.com/ach?direction=credit" ``` ## Identifying transactions related to an ACH There are two fields that are used to map an ACH to the related transaction(s) that are generated as part of the payment flow. The first, `trace_id`, can be used to surface all transactions related to a particular ACH (including `hold`, `hold_release`, `withdrawal`, and `deposit` transactions). The second field, `ach_id` is used to identify only transactions that resulted in the movement of funds (a withdrawal or deposit). For transactions that did not result in funds movement (such as a `hold`, or `hold_release`) the `ach_id` field will be null. Note that the values for both of the `trace_id` and `ach_id` fields will be the `id` of the originating ACH object. # ACH Returns Source: https://docs.treasuryprime.com/docs/ach-returns ACH payments can be returned for various reasons including insufficient funds, closed accounts, or incorrect account details. This guide covers identifying returned ACH payments, handling return transactions, and initiating returns for originated and incoming ACH transfers. ## Return timeframes The Receiving Depository Financial Institution (RDFI) has 2 business days to return most ACH payments. For unauthorized transactions on consumer accounts, the RDFI has up to 60 calendar days to initiate a return. When the Originating Depository Financial Institution (ODFI) receives a return, Treasury Prime updates the [ACH object](/reference/ach) status to `returned` and populates the `error` field with the appropriate return code. ## ACH return flow This example shows the flow when an ACH debit is returned due to insufficient funds: 1. You originate an ACH debit using the Treasury Prime API 2. The RDFI receives the ACH but the account has insufficient funds 3. The RDFI issues an ACH return with [return code](#ach-return-codes) `R01` (Insufficient Funds) 4. The ODFI (Treasury Prime partner bank) receives the return and notifies Treasury Prime 5. Treasury Prime updates the ACH object: * Changes `status` to `returned` * Populates `error` field with the [return code](#ach-return-codes) 6. The `ach.update` webhook fires to notify you of the status change ## Identify ACH returns When the RDFI returns an ACH payment, Treasury Prime updates the ACH object with: * `status`: Set to `returned` * `error`: Populated with the [return code](#ach-return-codes) explaining why the payment was returned You can identify returned ACH payments in two ways: ### Monitor webhooks The `ach.update` webhook fires when an ACH object changes status. Use this webhook to notify your customers that their payment was not completed and may require follow-up action. ### Query the API Filter the [/ach endpoint](/reference/ach) by `status=returned` to retrieve all returned ACH payments. This allows you to build internal dashboards or customer-facing views of returned payments. ##### Example Request to List Returned ACH Objects ```bash bash theme={null} curl -u $API_KEY_ID:$API_KEY_VALUE {% api-endpoint /%}/ach?status=returned ``` ## Return an originated ACH To return an ACH transfer you originated, use the [Update an ACH](https://docs.treasuryprime.com/reference/patch_ach-id) endpoint. **Note:** This feature must be enabled for your organization. If not enabled, contact Treasury Prime support at [support@treasuryprime.com](mailto:support@treasuryprime.com) with: * The transaction `id` of the originated ACH * The reason for the return request * Any other relevant information Treasury Prime will submit the return request to the ODFI. If approved, the ODFI submits the return to the RDFI. A successful return posts an additional transaction to the account to reverse the original transaction. Incoming ACH returns availability varies by bank partner and requires bank approval. Contact your relationship manager to discuss availability and any associated costs. ## Example returned ACH object This example shows an ACH debit returned by the RDFI with [return code](#ach-return-codes) `R01` (insufficient funds): ```bash bash theme={null} { "description": "ACH DEBIT RETURN [ach_11hqstvbf3w5es][ppd][standard] Target", "amount": "100.00", "service": "standard", "counterparty_id": "cp_11gsczk76tqj1p", "bank_id": "bank_treasuryprime", "account_id": "acct_11hq4m9aee67ye", "addenda": [], "org_id": "org_1evy4cx2km5", "batch_key": null, "effective_date": "2022-11-22", "updated_at": "2022-11-22T16:00:13Z", "status": "returned", "id": "ach_11hqstvbf3w5es", "error": "R01", "sec_code": "ppd", "scheduled_settlement": "2022-11-25T16:20:13Z", "direction": "debit", "created_at": "2022-11-22T15:31:55Z", "userdata": null } ``` ## Transactions for returned ACH payments An ACH return reverses the funds movement from the original ACH: * **ACH debits** (which create a deposit): A withdrawal reverses the original deposit * **ACH credits** (which create a withdrawal): A deposit reverses the original withdrawal These balance updates trigger the `account.update` webhook. ### Scenario 1: Returned ACH debit When you create a \$20 ACH debit: 1. A \$20 `deposit` is applied to the originating account 2. A \$20 `hold` is placed on those funds When the RDFI returns the ACH: 3\. A $20 `withdrawal` reverses the original deposit 4. A $20 `hold_release` balances the account | Order | Transaction Type | Amount | | - | - | - | | 1 | `deposit` | 20 | | 2 | `hold` | -20 | | 3 | `withdrawal` | -20 | | 4 | `hold_release` | 20 | ### Scenario 2: Returned ACH credit When you create a \$20 ACH credit: 1. A \$20 `withdrawal` is made from the originating account When the RDFI returns the ACH: 2\. A \$20 `deposit` reverses the initial withdrawal | Order | Transaction Type | Amount | | - | - | - | | 1 | `withdrawal` | 20 | | 2 | `deposit` | -20 | ## Return an incoming ACH To return an incoming ACH transfer originated by a third party, use the [Update an Incoming ACH](/reference/patch_incoming_ach-id) endpoint with one of the supported return codes: `R29`, `R10`, or `R20`. For detailed information including timing requirements and example requests, see the [Returning Incoming ACH](/docs/returning-incoming-ach) guide. ## ACH return codes Below is the list of the most commonly encountered ACH return codes. | Code | Reason | Description | | - | - | - | | R01 | Insufficient funds | Available balances is not sufficient to cover the dollar amount of the debit entry. | | R02 | Account closed | A previously open account is now closed. | | R03 | No account or unable to locate account | The account number does not correspond to the individual identified in the entry or a valid account. | | R04 | Invalid account number structure | The account number fails the check digit validation or may contain an incorrect number of digits. | | R05 | Unauthorized debit to consumer account using a corporate SEC code | A `ccd` or `ctx` business debit entry was transmitted to a consumer account, and was not authorized by the recipient. | | R06 | Returned per ODFI's request | The ODFI has requested that the RDFI return the entry. | | R07 | Authorization revoked by customer | A receipient who previously authorized an entry has revoked authorization with the originator. | | R08 | Payment stopped | The recipient has placed a stop payment order on this debit Entry. | | R09 | Uncollected funds | A sufficient balance exists to satisfy the dollar value of the transaction, but the available balance is below the dollar value of the debit Entry. | | R10 | Customer advises Originator is Not Known to Receiver and/or Originator is Not Authorized by Receiver to Debit Receiver’s Account | The RDFI has been notified by the recipient that the recipient does not know the identity of the originator, has no relationship with the originator, or has not authorized the originator to debit their account. | | R11 | Customer Advises Entry Not in Accordance with the Terms of Authorization | The RDFI has been notified by the Receiver that the Originator and Receiver have a relationship and an authorization to debit exists, but there is an error or defect in the payment such that the entry does not conform to the terms of the authorization. | | R12 | Branch sold to another DFI | A financial institution received an Entry to an account that was sold to another financial institution maintained at a branch sold to another financial institution. | | R13 | Invalid ACH routing number | Entry contains an invalid ACH routing number. | | R14 | Representment payee deceased or unable to continue in that capacity | Representative payee is deceased or unable to continue in that capacity. The beneficiary is not deceased. | | R15 | Beneficiary of account holder deceased | Either the beneficiary or account holder is deceased. | | R16 | Account Frozen/Entry Returned Per OFAC Instruction | (1) Access to the account is restricted due to specific action taken by the RDFI or by legal action; or (2) OFAC has instructed the RDFI or Gateway to return the Entry. | | R17 | File record edit criteria/Entry with invalid account number initiated under questionable circumstances | (1) Field(s) cannot be processed by RDFI; or (2) the Entry contains an invalid DFI 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. | | R18 | Improper effective entry date | (1) The Effective Entry Date for a credit Entry is more than two Banking Days after the processing date; or (2) the Effective Entry Date for a debit Entry is more than one Banking Day after the processing date. | | R19 | Amount field error | Improper formatting of the amount field, or the allowed amounts of the SEC code used does not match the dollar value of the entry. | | R20 | Non-transaction account | Policies or regulations (such as Regulation D) prohibit or limit activity to the receiving account based on its type. | | R21 | Invalid company identification | The company ID information is not valid. | | R22 | Invalid individual ID number | The recipient has indicated to the RDFI that the number with which the Originator was identified is not correct. | | R23 | Credit entry refused by receiver | Any credit entry that is refused by the recipient may be returned by the RDFI. | | R24 | Duplicate entry | RDFI has received what appears to be a duplicate entry. | | R25 | Addenda error | Improper formatting of the addenda record information. | | R26 | Mandatory field error | Erroneous data or missing data in a mandatory field. | | R27 | Trace number error | Original entry trace number is not valid for return entry; or addenda trace numbers do not correspond with entry detail record. | | R28 | Routing number check digit error | The check digit for a routing number is not valid. | | R29 | Corporate customer advises not authorized | RDFI has been notified by business account holder that a specific transaction is unauthorized. | | R30 | RDFI not participant in check truncation program | Financial institution not participating in automated check safekeeping application. | | R31 | Permissible return entry | The RDFI may return a `CCD` or `CTX` entry that the ODFI agrees to accept. | | R32 | RDFI nonsettlement | RDFI is not able to settle the entry. | *** [Early ACH Posting](/docs/early-posting-for-incoming-ach-credits) [Testing ACH](/docs/testing-ach) # ACH Transfer Source: https://docs.treasuryprime.com/docs/ach-transfer An Automated Clearing House (ACH) transfer is an electronic funds transfer between two accounts at different banks. It allows for credits (sending money) and debits (receiving money), and is generally cheaper when compared to other available methods, but also most-often slower. This guide will examine the process of sending money to another account using ACH (also known as a credit), though you can also receive money from an account (a debit) using this same method. ### This guide uses the following endpoints * [`/account`](/reference/account) * [`/counterparty`](/reference/get_counterparty) * [`/ach`](/reference/ach) * [`/webhook`](/reference/webhook) ### To create an ACH transfer you will need to 1. [Get the account ID](#1-get-the-account-id) 2. [Get the Counterparty ID](#2-get-the-counterparty-id) 3. [Create the ACH transfer](#3-create-the-ach-transfer) 4. [Get status updates](#4-get-status-updates) ## 1. Get the Account ID The first step in creating an ACH transfer is to obtain the ID of the account the funds will be transferred from. Both a savings and checking account have been pre-created in the Developer Sandbox for testing purposes; however, you can also create and use your own bank accounts if you prefer. To retrieve an account ID, make a `GET` request to the `account` endpoint. ```bash bash theme={null} curl -u $API_KEY_ID:$API_SECRET_KEY https://api.treasuryprime.com/account ``` This will return a list of of Account objects. In order to make an ACH transfer, you will need the account ID which is stored in the `id` property of each account object. ```bash bash theme={null} { "data": [ { "account_type": "savings", "bank_id": "bank_treasuryprime", "updated_at": "2021-02-01T16:32:34Z", "currency": null, "routing_number": "000000000", "account_number": "123000012345", "id": "acct_qda4pJZfpzn4fc", "created_at": "2021-01-13T15:05:14Z", "userdata": null }, { "account_type": "checking", "bank_id": "bank_treasuryprime", "updated_at": "2021-02-01T16:32:34Z", "currency": null, "routing_number": "000000000", "account_number": "123000067890", "id": "acct_wVwR87rxhMRdwD", "created_at": "2021-01-13T15:05:13Z", "userdata": null } ], "total_estimated": 10 } ``` ## 2. Get the Counterparty ID The next piece of data required for an ACH is the ID of the Counterparty (the person or entity on the other side of that transaction) or put more simply: Who the funds are being transferred to. If you have not yet created a Counterparty in your Developer Sandbox, read the next section for instructions on how to accomplish this. Otherwise, feel free to skip ahead to [Retrieve an existing Counterparty](#retrieve-an-existing-counterparty). ### Create a Counterparty Creating a Counterparty requires making a `POST` request to the `counterparty` endpoint, and passing along the name of person or entity who owns the account, as well as three pieces of data required for ACH: 1. The ACH specific bank account number 2. The account type (checking or savings) 3. The routing number ```bash bash theme={null} curl -u $API_KEY_ID:$API_SECRET_KEY https://api.treasuryprime.com/counterparty \ -H 'Content-Type: application/json' \ -d '{ "name_on_account": "Adam Smith", "ach": { "account_number": "12345678", "account_type": "checking", "routing_number": "87654321" } }' ``` Assuming no errors are encountered, the response will contain a Counterparty object containing an `id` property representing the counterparty ID. ```bash bash theme={null} { "created_at": "2021-02-25T01:23:24Z", "updated_at": "2021-02-25T01:23:24Z", "ach": { "account_number": "12345678", "account_type": "checking", "routing_number": "87654321" }, "wire": null, "name": "Adam Smith", "name_on_account": "Adam Smith", "id": "cp_v1p3ay8w4b0x", "userdata": null } ``` ### Retrieve an Existing Counterparty To find the IDs of any existing Counterparty objects, make a `GET` request to the `counterparty` endpoint ```bash bash theme={null} curl -u $API_KEY_ID:$API_SECRET_KEY https://api.treasuryprime.com/counterparty ``` This will return a list of all existing Counterparty objects you have created (or empty if none are found). Each Counterparty object contains an `id` property representing the counterparty ID. ```bash bash theme={null} { "data": [ { "created_at": "2021-02-25T01:23:24Z", "updated_at": "2021-02-25T01:23:24Z", "ach": { "account_number": "12345678", "account_type": "checking", "routing_number": "87654321" }, "wire": null, "name": "Adam Smith", "name_on_account": "Adam Smith", "id": "cp_v1p3ay8w4b0x", "userdata": null }, ... ] } ``` ## 3. Create the ACH Transfer With the Account ID, and Counterparty ID, the ACH transfer can now be made. But first a final note on two additional properties. The `direction` property specifies whether this transfer is a credit or debit (in this case a credit since money is being sent), and the `sec_code` which specifies the type of transfer according to the ACH Network. More details on those topics can be found in the [ACH documentation](/reference/ach). > The protocol that underlies the ACH network is batch-oriented and does not provide success responses (only error responses). As a result, ACH transfers follow a particular workflow as they are processed by the network. You can track a transfer's progress by checking the status attribute on the ACH object. Enough details, let's make the transfer! ```bash bash theme={null} curl -u $API_KEY_ID:$API_SECRET_KEY https://api.treasuryprime.com/ach \ -H 'Content-Type: application/json' \ -d '{ "account_id": "acct_1234567890", "amount": "100.00", "counterparty_id": "cp_0987654321", "direction": "credit", "sec_code": "ppd", "service": "standard" }' ``` If no errors were encountered, a new ACH Object is returned. To find out when the transfer is complete requires watching for status updates which will be covered next. If an error was encountered, an error message should be returned to explain the error. A common error when creating an ACH is exceeding one of the daily limits on total ACH transfer amounts. Exceeding these limits results in a 429 status error, with an error message describing the limit exceeded. More information on how these limits are handled can be found in the [ACH documentation](/reference/ach#limits-on-total-ach-transaction-amounts). ```bash bash theme={null} { "description": null, "amount": "100.00", "service": "standard", "counterparty_id": "cp_0987654321", "bankdata": null, "bank_id": "bank_treasuryprime", "account_id": "acct_1234567890", "addenda": [], "org_id": "org_treasuryprime", "batch_key": null, "effective_date": "2021-02-25", "updated_at": "2021-02-25T01:32:57Z", "status": "pending", "id": "ach_5merj00eudnp", "error": null, "sec_code": "ppd", "direction": "credit", "created_at": "2021-02-25T01:32:57Z", "userdata": null } ``` ## 4. Get Status Updates There are two ways to find out when the status of the ACH transfer has changed: ### Manually Checking for Status Updates By making a `GET` request to the `ach` endpoint and passing in the `id` of the ACH transfer you'd like the status for. This will return an ACH object with the latest status. ```bash bash theme={null} curl -u $API_KEY_ID:$API_SECRET_KEY https://api.treasuryprime.com/ach/:id ``` Note the `status` has been changed to "sent". ```bash bash theme={null} { "description": null, "amount": "100.00", "service": "standard", "counterparty_id": "cp_0987654321", "bankdata": null, "bank_id": "bank_treasuryprime", "account_id": "acct_1234567890", "addenda": [], "org_id": "org_treasuryprime", "batch_key": null, "effective_date": "2021-02-25", "updated_at": "2021-01-04T20:30:27Z", "status": "sent", "id": "ach_5merj00eudnp", "error": null, "sec_code": "ppd", "trace_number": "24015053925610", "direction": "credit", "created_at": "2021-02-25T01:32:57Z", "userdata": null } ``` Once an ACH reaches `sent` status, the `trace_number` field contains an identifier assigned by the originating bank. You can use this to help your customers track payments. See [Tracking originated ACH payments with trace numbers](/docs/ach#tracking-originated-ach-payments-with-trace-numbers) for details. ### Listening for Status Updates with Webhooks By registering a webhook to respond to the `ach.update` event, you can be notified of changes in the status of the ACH transfer when they occur. ```bash bash theme={null} curl https://api.treasuryprime.com/webhook \\ -u "$API_KEY_ID:$API_SECRET_KEY" \\ -H 'Content-Type: application/json' \\ -d '{ "event": "ach.update", "url": "https://example.application.com/notify" }' ``` Once the `ach.update` webhook notification is received, follow the steps outlined above to obtain the latest status of the transfer, or simply make a `GET` request to the URL specified in the `url` property of the data object. ```bash bash theme={null} { "event": "ach.update", "op": "update", "id": "ach_01123456789", "url": "https://api.treasuryprime.com/ach/ach_01123456789" } ``` ## Canceling an ACH Transfer An ACH transfer originated on the Treasury Prime platform may be canceled while it is in a `status` of `pending`. Once the ACH transitions from `pending` to `processing`, it may no longer be canceled. To cancel an ACH, call the [Update an ACH](https://docs.treasuryprime.com/reference/patch_ach-id) endpoint to update its status to `canceled` as shown below. ```bash bash theme={null} $ curl -u $API_KEY_ID:$API_SECRET_KEY https://api.treasuryprime.com/ach/ach_1029384756 \ -X PATCH \ -H 'Content-Type: application/json' \ -d '{ "status": "canceled" }' ``` Canceling a `pending` ACH can also be done directly in the Treasury Prime Dashboard app for users with the required permissions. *** What’s Next Once the ACH Transfer object reaches a status of "sent", then the transfer is complete! Congratulations on making your first ACH transfer. If you'd like to dig deeper, check out the [ACH API documentation](/reference/ach). And since you're already on a hot-streak, why not try out [Issuing Debit Cards](/docs/issuing-a-card)? * [Table of Contents](#) * * * [This guide uses the following endpoints](#this-guide-uses-the-following-endpoints) * [To create an ACH transfer you will need to](#to-create-an-ach-transfer-you-will-need-to) * [1. Get the Account ID](#1-get-the-account-id) * [2. Get the Counterparty ID](#2-get-the-counterparty-id) * * [Create a Counterparty](#create-a-counterparty) * [Retrieve an Existing Counterparty](#retrieve-an-existing-counterparty) * [3. Create the ACH Transfer](#3-create-the-ach-transfer) * [4. Get Status Updates](#4-get-status-updates) * * [Manually Checking for Status Updates](#manually-checking-for-status-updates) * [Listening for Status Updates with Webhooks](#listening-for-status-updates-with-webhooks) # Adding Authorized Users Source: https://docs.treasuryprime.com/docs/adding-authorized-users This guide describes how to add authorized users to existing accounts and issue them debit cards. Authorized users do not require the same amount of KYC as account owners, and as such adding them to accounts requires permission from the bank. ### This guide uses the following endpoints * [`/apply/additional_person_endpoint`](/reference/additional-person) * [`/apply/person_application`](/reference/person-application) * [`/card`](/reference/card) ### To add an authorized user to an account, you must 1. [Create a person application](#1-create-a-person-application) 2. [Use the additional person application flow](#2-create-an-additional-person-application) 3. [Issue the card](#3-issue-the-card) ## 1. Create a Person Application [`person_application`](/reference/person-application) objects represent natural persons who are applying for new bank accounts or to be added to existing bank accounts. Before you can add a person to an account, you must create a `person_application` to represent them. To create a `person_application`, make a `POST` request to the `/apply/person_application` endpoint. ```bash bash theme={null} curl -u $API_KEY_ID:$API_KEY_VALUE https://api.treasuryprime.com/apply/person_application \ -H 'Content-Type: application/json' \ -d '{ "bankdata": { "ip_address": "127.0.0.40" }, "citizenship": "US", "date_of_birth": "1732-02-22", "email_address": "[email protected]", "first_name": "George", "last_name": "Washington", "phone_number": "2025551111", "physical_address": { "street_line_1": "1600 Pennsylvania Ave", "city": "Washington", "state": "DC", "postal_code": "20500" }, "tin": "111222444" }' ``` This will return the `person_application` object with a unique `id`: ```bash bash theme={null} { "bankdata": { "ip_address": "127.0.0.40" }, "citizenship": "US", "created_at": "2019-03-02T11:55:14Z", "date_of_birth": "1732-02-22", "email_address": "[email protected]", "first_name": "George", "id": "apsn_01d5w7mvmwvy", "last_name": "Washington", "middle_name": null, "occupation": null, "phone_number": "2025551111", "physical_address": { "street_line_1": "1600 Pennsylvania Ave", "street_line_2": null, "city": "Washington", "state": "DC", "country": "US", "postal_code": "20500" }, "updated_at": "2019-03-02T11:55:14Z", "userdata": null } ``` The id for `person application` is prefixed with `apsn_`, which aids in distinguishing them from the `person` objects created at the end of the application process. ## 2. Create an Additional Person Application Once the `person_application` representing the authorized user you wish to add to an account has been created, you can add them to the account by making a request to the [`additional_person_application`](/reference/additional-person) endpoint: ```bash bash theme={null} curl -u $API_KEY_ID:$API_KEY_VALUE https://api.treasuryprime.com/apply/additional_person_application \ -H 'Content-Type: application/json' \ -d '{ "bankdata": { "ip_address": "127.0.0.40" }, "account_id": "acct_1029384756", "person_application_id: "apsn_01d5w7mvmwvy", "role": "authorized_user" }' ``` This will start an `additional_person_application` to add the supplied `person_application` to the specified `account`, with the given role. The response will look like this: ```bash bash theme={null} { "account_id": "acct_1029384756", "bankdata": { "ip_address": "127.0.0.40" }, "created_at": "2019-03-02T11:55:14Z", "id": "aapa_01d5w7mvmwvy", "person_application_id": "apsn_01d5w7mvmwvy", "role": "authorized_user", "status": "pending", "updated_at": "2019-03-02T11:55:14Z", "userdata": null } ``` The `status` of the application will begin in `pending` and end in `approved`; once the application is approved, you can issue a card to the new user. ## 3. Issue the Card Once the `additional_person_application` has been approved, you can fetch the `person_application` attached to it and look up the `person` created and linked to the account: ```bash bash theme={null} curl -u $API_KEY_ID:$API_KEY_VALUE https://api.treasuryprime.com/apply/person_application/apsn_01d5w7mvmwvy ``` ```bash bash theme={null} { "first_name": "George", "secondary_email_address": null, "bankdata": { "ip_address": "127.0.0.40" }, "phone_number": "+1 202-555-1111", "mailing_address": null, "occupation": null, "physical_address": { "street_line_1": "1600 Pennsylvania Ave", "street_line_2": null, "city": "Washington", "state": "DC", "postal_code": "20500", "country": "US" }, "person_id": "psn_11gqnx6f69zv0g", "middle_name": null, "updated_at": "2021-10-28T19:06:55Z", "gov_id": null, "document_ids": [], "id": "apsn_11gqkcek69rv55", "citizenship": "US", "date_of_birth": "1991-02-22", "last_name": "Washington", "user_id": null, "email_address": "[email protected]", "created_at": "2021-10-27T20:08:51Z", "userdata": null } ``` The `person_id` attribute of the `person_application` object is what is required to create a card; it is prefixed with `psn`. Once you have the id of the person you wish to issue a card to, you can make a call to issue them a card in the [normal way](/reference/card): ```bash bash theme={null} curl -u $API_KEY_ID:$API_KEY_VALUE https://api.treasuryprime.com/card \ -H 'Content-Type: application/json' \ -d '{ "account_id": "acct_1029384756", "person_id": "psn_11gqnx6f69zv0g5", "card_product_id": "cdpt_w10r2sebv0nl" }' ``` This will return a card object: ```bash bash theme={null} { "account_id": "acct_1029384756", "card_controls": null, "card_product_id": "cdpt_w10r2sebv0nl", "cvv": null, "created_at": "2021-02-19T20:42:40Z", "expiration": "0225", "fulfillment": { "status": "issued" }, "id": "card_zuhqnmz7e085", "last4": "3385", "pan": null, "person_id": "psn_11gqnx6f69zv0g5", "pin_is_set": false, "status": "unactivated", "updated_at": "2021-02-19T20:42:41Z", "userdata": null } ``` # Apple Pay Source: https://docs.treasuryprime.com/docs/apple-pay Digital wallets allow users to store and use their cards without carrying a physical card with them. This guide describes how to provision cards using Apple Pay. At a high level, this is what provisioning a card to Apple Wallet entails: 1. The user taps the Add to Apple Wallet button. 2. Apple Wallet prepares and returns the public certificates, nonce, and nonce signature to your app. 3. Your app passes the public certificates, nonce, and nonce signature to Treasury Prime, which implements the issuer host responsibilities for you. 4. A payment data payload is prepared and encrypted then returned to your app along with the ephemeral public key and activation data. 5. Your app passes the encrypted payment data payload, ephemeral public key, and activation data to Apple Wallet. 6. Apple Wallet processes the request. ### This guide uses the following endpoints * `/card` * `/card/:card_id/digital_wallet/apple_pay` ### To provision a card, you must do these things 1. [Look up cards a user owns](#1-look-up-cards) 2. [Provision digital wallet token](#2-add-card-to-wallet) ## 1. Look up cards The first step in provisioning a card for a digital wallet is looking up which cards a user has. Filter available cards by the person whose device the card is being provisioned for. ```bash bash theme={null} curl -u $API_KEY_ID:$API_SECRET_KEY https://api.treasuryprime.com/card?person_id="psn_qda4pJZfpzn4f" ``` ```bash bash theme={null} { "data": [ { "cvv": null, "account_id": "acct_11ggtz5y2wsj", "pan": null, "expiration": "0925", "person_id": "psn_qda4pJZfpzn4f", "last4": "3496", "card_product_id": "cdpt_11ggtwth2wshde", "updated_at": "2021-09-27T21:12:07Z", "card_controls": null, "status": "active", "fulfillment": { "status": "issued" }, "id": "card_11gn4cvm4c7t6p", "pin_is_set": false, "created_at": "2021-09-27T21:11:16Z", "userdata": null }, { "cvv": null, "account_id": "acct_11ggtz5y2wsj", "pan": null, "expiration": "0925", "person_id": "psn_qda4pJZfpzn4f", "last4": "5732", "card_product_id": "cdpt_11ggtwth2wshde", "updated_at": "2021-09-27T21:12:09Z", "card_controls": null, "status": "terminated", "fulfillment": { "status": "issued" }, "id": "card_11gmwjx63qty7h", "pin_is_set": true, "created_at": "2021-09-24T22:05:26Z", "userdata": null } ], "total_estimated": 10 } ``` You application will display eligible cards to the user, and the user can initiate card tokenization by choosing to add it to their wallet. ## 2. Add card to wallet After the user has clicked the Add to Wallet button, your application will receive a payload you must pass to Treasury Prime, at the `card/:card_id/digital_wallet_token/apple_pay` endpoint. For this example, we will tokenize `card_11gn4cvm4c7t6p`. ```bash bash theme={null} curl https://api.treasuryprime.com/card/card_11gn4cvm4c7t6p/digital_wallet_token/apple_pay \ -u $API_KEY_ID:$API_SECRET_KEY ``` ```bash bash theme={null} { "card_id": "card_11gn4cvm4c7t6p", "encrypted_pass_data": "w9NGKYa3OkPGeQ+FmAKGga", "activation_data": "TUJQQUMtMS1GSy03NDgwNTIuMS0tVERF", "ephemeral_public_key": "BMop3NufgKwy/r0GX1muvomvw" } ``` Your application must pass this data to the [PKAddPaymentPassViewController](https://developer.apple.com/documentation/passkit/pkaddpaymentpassviewcontroller) to complete adding the card to the user's wallet. # ATM Transactions Source: https://docs.treasuryprime.com/docs/atm-transactions By default, debit cards issued using the Treasury Prime platform will have access to withdraw cash from any ATM which operates on the Pulse or Mastercard network (look for the logos). Use of these ATMs will incur a usage fee for the cardholder. ATM cash deposits are not available at this time. ## ATM Transactions An ATM withdrawal will result in the creation of an `auth-clear-request` card event and, if approved, a `debit` transaction on the account. ### Approved ATM Withdrawal If the auth-clear-request is approved (the account has sufficient funds), a debit Transaction will be made on the account. | Object | Type | Amount | | - | - | - | | Card Event | auth-clear-request | 20 | | Transaction | debit | -20 | ### Declined ATM Withdrawal If the auth-clear-request is declined, no subsequent transactions are created. Common reasons for a request to be declined include insufficient funds and surpassing card control withdrawal limits (if defined). | Object | Type | Amount | | - | - | - | | Card Event | auth-clear-request | 20 | ### Card Event Object with ATM Sub-Object The below example shows a Card Event containing an `atm` sub-object. This demonstrates the type of data included in an `auth-clear-request` callback. Note: The `network_fee` field represents the fee that will be charged to the end user for using this ATM. ```bash bash theme={null} { "message_type": "auth-clear-request", "amount": "20.00", "bank_id": "bank_treasuryprime", "org_id": "org_1fdy4di87s78", "decline_reason": null, "updated_at": "2022-06-16T20:57:52Z", "currency": "USD", "status": "pending", "id": "cnm_44jj33abcd1234", "card_id": "card_12345abcde123", "trace_id": "9eda29541ed2asdf1231e61cabcdef123", "network": "mastercard", "network_created_at": null, "merchant": { "name": "Card Transaction Clear Request", "mcc": "4000", "mid": "0045025839033", "address": { "city": "LAS VEGAS", "state": "NV", "postal_code": "88901", "country": "USA" } }, "processor": "marqeta", "networkdata": null, "created_at": "2022-06-16T20:57:52Z", "atm": { "network": "mastercard", "network_fee": "3.00" }, } ``` # Book Transfer Source: https://docs.treasuryprime.com/docs/book-transfer A book transfer is an electronic funds transfer between two accounts at the same bank—for example, moving money from a checking account to a savings account. Book transfers are the fastest and cheapest type of transfer, but they can only be used between accounts held at the same bank. ### This guide uses the following endpoints * [`/account`](/reference/account) * [`/book`](/reference/book-transfer) * [`/webhook`](/reference/webhook) ### To create a book transfer you will need to 1. [Get the account IDs](#1-get-the-account-ids) 2. [Create a new book transfer](#2-create-a-new-book-transfer) 3. [Get status updates](#3-get-status-updates) ### Assumptions 1. You have access to at least two open accounts at the same bank. * If you haven't created any bank accounts yet, refer to the [Opening an Account](/docs/opening-an-account) guide to get started. * If you're testing in the [Developer Sandbox](https://app.sandbox.treasuryprime.com/sign_up), accounts are automatically available when you create your sandbox environment. 2. You have authorization to initiate payments between both the source and destination accounts that will be used in the book transfer. ## How to Create a Book Transfer ### 1. Get the Account IDs First, obtain the account IDs for the accounts you want to transfer funds between. Make a `GET` request to the `account` endpoint to retrieve this information. ```bash bash theme={null} curl -u $API_KEY_ID:$API_SECRET_KEY https://api.treasuryprime.com/account ``` This request returns a list of Account objects. You'll need the Account ID for both the sending and receiving accounts, which you can find in the `id` property of each account object. ```bash bash theme={null} { "data": [ { "account_type": "savings", "bank_id": "bank_treasuryprime", "updated_at": "2021-02-01T16:32:34Z", "currency": null, "routing_number": "000000000", "account_number": "123000012345", "id": "acct_qda4pJZfpzn4fc", "created_at": "2021-01-13T15:05:14Z", "userdata": null }, { "account_type": "checking", "bank_id": "bank_treasuryprime", "updated_at": "2021-02-01T16:32:34Z", "currency": null, "routing_number": "000000000", "account_number": "123000067890", "id": "acct_wVwR87rxhMRdwD", "created_at": "2021-01-13T15:05:13Z", "userdata": null } ], "total_estimated": 10 } ``` ### 2. Create a New Book Transfer Once you have the source and destination Account IDs, make a `POST` request to the `book` endpoint, passing the `amount` of the transfer, as well as the `from_account_id` and the `to_account_id` (representing the funding account and the receiving account respectively). * The `amount` property expects the numeric value representing the amount of money to be transferred in dollars, with two-decimal precision (ex: 100.00). * While only the `amount`, `from_account_id`, and `to_account_id` fields are required, you can also include optional information. Use the `description` field to add a human-readable explanation and the `userdata` field to store additional structured data like related payment references. ```bash bash theme={null} curl -u $API_KEY_ID:$API_SECRET_KEY https://api.treasuryprime.com/book \\ -H 'Content-Type: application/json' \\ -d '{ "amount": "100.00", "from_account_id": "acct_1234567890", "to_account_id": "acct_0987654321" }' ``` Upon successful execution, the system returns a Book Transfer object with a status of "pending". To track when the transfer completes, you'll need to monitor status updates as described in the next section. ```bash bash theme={null} { "to_account_id": "acct_xjwj391iu6rv", "description": null, "amount": "100.00", "bankdata": null, "bank_id": "bank_treasuryprime", "from_account_id": "acct_7mw05q7wthaq", "updated_at": "2021-02-25T01:45:32Z", "status": "pending", "id": "book_5merj00eudnp", "error": null, "created_at": "2021-02-25T01:45:32Z", "userdata": null } ``` ### 3. Get Status Updates There are two ways to monitor book transfer status changes: ### Manually Checking for Status Updates To check a book transfer's current status, send a `GET` request to the `book` endpoint with the transfer's `id`. The response will contain the Book Transfer object with its current status. ```bash bash theme={null} curl -u $API_KEY_ID:$API_SECRET_KEY https://api.treasuryprime.com/book/:id ``` Note that the `status` has changed from "pending" to "sent". ```bash bash theme={null} { "to_account_id": "acct_xjwj391iu6rv", "description": null, "amount": "100.00", "bankdata": null, "bank_id": "bank_treasuryprime", "from_account_id": "acct_7mw05q7wthaq", "updated_at": "2020-05-29T20:57:03Z", "status": "sent", "id": "book_5merj00eudnp", "error": null, "created_at": "2020-05-29T20:57:03Z", "userdata": null } ``` ### Listening For Status Updates with Webhooks Register a [webhook](https://docs.treasuryprime.com/reference/webhook) for the `book.update` event to receive automatic notifications whenever the status of a book transfer changes. ```bash bash theme={null} curl https://api.treasuryprime.com/webhook \\ -u "$API_KEY_ID:$API_SECRET_KEY" \\ -H 'Content-Type: application/json' \\ -d '{ "event": "book.update", "url": "https://example.application.com/notify" }' ``` When you receive a `book.update` webhook notification, you can retrieve the current transfer status in two ways: either follow the steps described above to manually check the status, or make a `GET` request to the URL provided in the notification's `url` property. ```bash bash theme={null} { "event": "book.update", "op": "update", "id": "book_1029384756", "url": "https://api.treasuryprime.com/book/book_1029384756" } ``` # Card Declines Source: https://docs.treasuryprime.com/docs/card-declines Declined card transactions are represented as [Card Events](/reference/card-events) with a `status` of `declined`. Card events in this status will contain a value in the `decline_reason` field which outlines the reason the transaction was declined. The example below shows a card event that was declined due to “Card Not Active.” ### Example Card Decline ```bash bash theme={null} { "message_type": "auth-request", "card_id": "card_09876543421", "amount": "10.00", "currency": "USD", "status": "denied", "decline_reason": "Card Not Active", "network": "mastercard", "network_created_at": "2017-11-02T11:55:09Z", "processor": "marqeta", "id": "cnm_2345678901", "created_at": "2017-11-02T11:55:14Z", "updated_at": "2017-11-02T11:55:14Z", "merchant": { "name": "A VENDOR NAME", "mid": "0123456789", "mcc": "0000", "address": { "city": "EDGEWATER", "state": "NJ", "postal_code": "07020", "country": "USA" } } } ``` ## Common Decline Reasons There are a large number of reasons a card authorization might be declined by the network, the issuer, or by your application logic. Below are some of the more common card decline reasons that you may encounter: | Decline Reason | Description | | - | - | | Denied By Card Controls: Blocked Merchant | This merchant is blocked by the current card control configuration. | | Denied By Card Controls: ATM Withdrawal Limit Reached | The ATM withdrawal limit defined by the card controls for this card have been reached. | | Denied By Card Controls: Usage Limit Reached | The usage limits defined by the card controls for this card have been reached. | | AVS Decline | The address information submitted for the transaction failed AVS verification. | | AVS No Info | The address information submitted for the transaction failed AVS verification. | | Card Auth Loop Endpoint Denied Request | This transaction was denied by a 402 response received from the Card Auth Loop Endpoint (your application logic). If a custom `decline_reason` was included in the 402 response, it is appended, e.g. `Card Auth Loop Endpoint Denied Request - 082`. | | Card Not Active | This card has not yet been activated. | | Card Expired | This card has expired. | | Card Suspended | This card is currently suspended and will need to be reactivated before it can be used. | | Card Expiration Mismatch | The card expiration date provided does not match the expiration data for this card. | | Fraud Decline | This transaction has been decline due to suspected fraudulent activity. | | Incorrect PIN | The PINs provided does not match the PIN for this card. | | Invalid CID | The CID provided does not match the CID assigned to this card. | | Invalid CVV | The CVV provided does not match the CVV assigned to this card. | | Issuer Timeout | The card network did not receive a response from the issuer within the specified timeframe and has declined the transaction. | | Network Decline | The card network has declined this transaction. | | Transaction Not Permitted | The card is not configured to support the transaction being attempted. | | NSF | Non-Sufficient Funds: The user's available balance is insufficient to cover the transaction. | # Card Events Source: https://docs.treasuryprime.com/docs/card-events Card Events and Transactions are the two main elements involved in the lifecycle of a card payment on the Treasury Prime platform. Card Events are dispatched via webhook callback to provide notification that a specific type of message was received from the card network. In response to these messages, Treasury Prime also creates Transactions on the related account, which impacts the current and available balance. The examples outlined for each Card Event type below are meant to be representative of common scenarios seen with card transactions, but do not represent every potential scenario you might encounter. As such, it is recommended that you place greater emphasis on understanding the common patterns encountered between Card Events and Transactions, and less on coding to accommodate these specific examples. ## Example Card Event object ```bash bash theme={null} { "message_type": "auth-request", "card_id": "card_09876543421", "amount": "10.00", "currency": "USD", "status": "pending", "decline_reason": null, "network": "mastercard", "network_created_at": "2017-11-02T11:55:09Z", "processor": "marqeta", "id": "cnm_2345678901", "created_at": "2017-11-02T11:55:14Z", "updated_at": "2017-11-02T11:55:14Z", "merchant": { "name": "A VENDOR NAME", "mid": "0123456789", "mcc": "0000", "address": { "city": "EDGEWATER", "state": "NJ", "postal_code": "07020", "country": "USA" } }, "atm": null, "networkdata": { "type": "authorization.incremental", "state": "PENDING", "token": "9699f5fc-3516-49c1-93a1-f6a9e6635bdf", "user_token": "0146434d-3c22-4906-a538-b61d39cf6f71", "acting_user_token": "0146434d-3c22-4906-a538-b61d39cf6f71", "card_token": "028b20b2-215f-4ab4-a334-f08d99def0e4", "created_time": "2022-09-29T21:35:03Z", "user_transaction_time": "2022-09-29T21:35:03Z", "settlement_date": "2022-09-29T00:00:00Z", "request_amount": 10.00, "amount": 10.00, "issuer_interchange_amount": 0.00, "currency_code": "USD", "network": "MASTERCARD", "acquirer_fee_amount": 0.00, "card_acceptor": { "mid": "123456890", "mcc": "6411", "name": "Marqeta Storefront", "address": "330 Central Ave.", "city": "St. Petersburg", "state": "FL", "postal_code": "33705", "country_code": "USA" }, "acquirer": null, "card_security_code_verification": null, "fraud": { "network": { "transaction_risk_score": 86, "account_risk_score": 2 } }, "pos": { "pan_entry_mode": "MAG_STRIPE", "pin_entry_mode": "TRUE", "terminal_id": "TR100000", "terminal_attendance": "ATTENDED", "card_holder_presence": false, "card_presence": false, "partial_approval_capable": false, "purchase_amount_only": false, "is_recurring": false } } } ``` The above example includes a sample of what might be received in the `networkdata` field. The `networkdata` field is processor specific and contains the information received from the network for the event. For messages processed by Marqeta, more detailed information on fields present in a network message can be found in their [documentation](https://www.marqeta.com/docs/core-api/gateway-jit-funding-messages). ## Card Event Webhooks When Treasury Prime receives a new notification from the card network, a Card Event object is created. This results in the `card_event.create` [webhook](/reference/webhook) firing. Likewise, if a Card Event is updated, the `card_event.update` webhook is triggered. In both cases, a standard webhook response will be provided containing the `id` of the Card Event object, along with a `url` value to retrieve the object. ##### Example card\_event.create Webhook ```bash bash theme={null} { "event": "card_event.create", "op": "create", "url": "https://api.sandbox.treasuryprime.com/card_event/cnm_112233sfbyf0qh", "id": "cnm_11hejtsfbyf0qh" } ``` ## Card Event Status Card events contain a `status` field which represents the current status of the object. The potential statuses are listed below: | Status | Description | | - | - | | pending | Actionable card events such as `auth-request` and `refund-auth-request` are initialized with a status of `pending` , and will eventually change to a status of `approved` or `denied` as the event is decisioned. | | error | An internal or other error has been encountered. | | approved | The card event has been approved. | | denied | The card event has been denied. | | timeout | A `timeout` status can occur when there is a delay in response to a request from the card network. In these instances, the card network will decline the transaction, and the status of the of the card event will be updated to reflect this case. | | received | This is an informational update to acknowledge receipt. There is no action to be taken. As the `status` field can change over time, you may see instances where a card event in status `received` later changes to `denied` or another status type. | ## Card Events by Type These are the types of card events that you will encounter. See below for further descriptions and examples of each type of event. * [`auth-request`](#authrequest) * [`auth-capture`](#authcapture) * [`auth-reversal`](#authreversal) * [`incremental-auth-request`](#incrementalauthrequest) * [`refund-auth-request`](#refundauthrequest) * [`refund`](#refund) * [`refund-auth-reversal`](#refundauthreversal) * [`auth-standin`](#authstandin) * [`force-capture`](#forcecapture) * [`auth-clear-request`](#authclearrequest) * [`auth-clear-adjustment`](#authclearadjustment) * [`auth-clear-reversal`](#authclearreversal) * [`balance-inquiry-request`](#balanceinquiryrequest) * [`chargeback-request`](#chargebackrequest) * [`chargeback-reversal`](#chargebackreversal) * [`original-credit-auth-request`](#originalcreditauthrequest) * [`original-credit-auth-clear-request`](#originalcreditauthclearrequest) * [`account-verification-request`](#accountverificationrequest) ### auth-request `auth-request` events (commonly known as authorizations) are by far the most common type of card event. This request seeks to validate that the account in question has sufficient funds to complete the transaction. Assuming the funds are available, a successful response is sent and a hold is created to ensure those funds remain available to complete the transaction. If using the [Card Auth Loop Endpoint](/reference/card-auth-loop-endpoint) to manage whether an `auth-request` is accepted or rejected, you will receive a webhook callback to the `url` provided in the Card Auth Loop Endpoint when an `auth-request` occurs. #### Partial Authorizations Partial authorizations can occur when a merchant sends an authorization request but the cardholder’s current balance is insufficient to cover the entire amount. In these instances, if the merchant supports partial authorizations, Treasury Prime will respond to the authorization request with the amount that is currently available in the user's account. ##### Example A cardholder wishes to purchase \$25 worth of groceries, but only has \$10 available in their account. The merchant submits an `auth-request` for \$25, and Treasury Prime responds with an approved amount of \$10, and a `hold` is created in that amount. The merchant receives a response informing them that the account only has \$10 available, and an `auth-capture` is dispatched for that amount. The initial \$25 hold is then released, the available \$10 is debited from the users account, and a new hold is created for the remaining authorized amount of \$15. The final \$15 hold will remain in place until the merchant clears it or the authorization expires (typically within 9 days). | Object | Type | Amount | | - | - | - | | Card Event | auth-request | 25 | | Transaction | hold | -10 | | Card Event | auth-capture | 10 | | Transaction | hold\_release | 25 | | Transaction | withdrawal | -10 | | Transaction | hold | -15 | | Transaction | hold\_release | 15 | ### auth-capture An `auth-capture` (commonly called a capture) occurs when a merchant verifies that a transaction is complete and requests that the funds be transferred. In many situations, this happens immediately after the transaction completes; however, depending on the merchant, it may take a number of days for a capture event to occur after the initial authorization. Once the `auth-capture` event is received, a `hold-release` is issued in the amount of the initial authorization (releasing the funds for transfer), and a `withdrawal` is then created to move the funds out of the users account. | Object | Type | Amount | | - | - | - | | Card Event | auth-request | 20 | | Transaction | hold | -20 | | Card Event | auth-capture | 20 | | Transaction | hold\_release | 20 | | Transaction | withdrawal | -20 | #### Partial Captures Partial captures can occur when a merchant sends an authorization request for a higher amount than the final purchase. ##### Example A cardholder swipes their card at an Automated Fuel Dispenser (AFD) to purchase some gas. The AFD sends an initial `auth-request` for \$100, which is approved, and a \$100 `hold` is created. The cardholder proceeds to pump \$50 worth of gas and completes the transaction. At this point, the AFD sends an `auth-capture` for \$50. The initial \$100 hold is released, \$50 is debited from the users account, and a new hold is created for the remaining authorized amount of \$50. The final \$50 hold will remain in place until the merchant clears it or the authorization expires (typically within 9 days). | Object | Type | Amount | | - | - | - | | Card Event | auth-request | 100 | | Transaction | hold | -100 | | Card Event | auth-capture | 50 | | Transaction | hold\_release | 100 | | Transaction | withdrawal | -50 | | Transaction | hold | -50 | | Transaction | hold\_release | 50 | #### Gas Stations and High Value Captures Self-service gas pumps present a somewhat unique scenario where a low-value `auth-request` is sent, and later, a higher-value `auth-capture` is sent for the total cost of the fuel purchased. This can lead to unexpected consequences, including overdrafts. \{% alert severity="warning" %} Note: One way to manage this scenario is to use the [Card Auth Loop Endpoint](/reference/card-auth-loop-endpoint) to review `auth-requests` from gas stations (merchant code: 5542) and apply logic to determine whether to accept or reject the transaction based on the available balance for the account at that time. \{% /alert %} ##### Example A cardholder swipes their card at a gas station and an `auth-request` is sent for \$1, which is approved. They proceed to pump \$50 worth of gas, and complete the transaction. At this point, the gas station, which needs to collect \$50 but has only authorized payment for \$1, will submit an `auth-capture` which instructs the full amount (\$50) to be paid regardless of the initial authorization amount. | Object | Type | Amount | | - | - | - | | Card Event | auth-request | 1 | | Transaction | hold | -1 | | Card Event | auth-capture | 50 | | Transaction | hold\_release | 1 | | Transaction | withdrawal | -50 | ### auth-reversal An `auth-reversal` is used to cancel or reverse an authorization before the funds have been captured. ##### Example A customer swipes their card to initiate a purchase, this results in an `auth-request` being sent. The customer then changes their mind and requests to cancel the transaction. The merchant cancels the transaction and an `auth-reversal` is sent to ensure any funds being held are released. ##### Scenario 1 | Object | Type | Amount | | - | - | - | | Card Event | auth-request | 25 | | Card Event | auth-reversal | 25 | `auth-reversal` submitted before the `auth-request` has been approved and a hold has been created. ##### Scenario 2 `auth-reversal` submitted after the `auth-request` has been approved and a hold has been created. | Object | Type | Amount | | - | - | - | | Card Event | auth-request | 25 | | Transaction | hold | -25 | | Transaction | hold\_release | 25 | | Card Event | auth-reversal | 25 | ### incremental-auth-request On occasion, a merchant may need to increase the amount of an earlier `auth-request`; this is where the `incremental-auth-request` comes in. This request seeks to verify that the user has sufficient funds to cover the additional amount of the transaction, and if they do, results in both a `hold-release` for the original amount and a `hold` being created for the new total amount of the authorization. ##### Example — Tipping in a Restaurant An `auth-request` is submitted for \$10 (the total amount of the bill), later an `incremental-auth-request` is sent to add the value of the tip (\$5) to the total amount of the authorization before finally submitting an `auth-capture` to secure the final amount of the bill (\$15). | Object | Type | Amount | | - | - | - | | Card Event | auth-request | 10 | | Transaction | hold | -10 | | Card Event | incremental-auth-request | 5 | | Transaction | hold\_release | 10 | | Transaction | hold | -15 | | Card Event | auth-capture | 15 | | Transaction | hold\_release | 15 | | Transaction | withdrawal | -15 | ### refund-auth-request A `refund-auth-request` is sent when a merchant wishes to verify that an account is available to receive a refund prior to sending the funds. If using the [Card Auth Loop Endpoint](/reference/card-auth-loop-endpoint), a webhook callback will be triggered in response to this event, allowing you to approve or deny the request. | Object | Type | Amount | | - | - | - | | Card Event | refund-auth-request | 25 | | Card Event | refund | 25 | | Transaction | deposit | 25 | ### refund When a merchant issues a refund to a card, a credit is issued to the users account in the amount of the refund, and will become immediately available. | Object | Type | Amount | | - | - | - | | Card Event | refund | 25 | | Transaction | deposit | 25 | ### refund-auth-reversal Reversal of a prior `refund-auth-request` | Object | Type | Amount | | - | - | - | | Card Event | refund-auth-request | 25 | | Card Event | refund-auth-reversal | 25 | ### auth-standin In circumstances where the issuer processor for the card is unable to respond to an authorization request (such as during an outage), the card network operator may need to step in and make a decision so the transaction can move forward without negatively impacting the cardholder. In these instances, known as “stand-in processing” or "STIP", an `auth-standin` card event dispatched. The initial `auth-standin` event replaces the normal `auth-request` event seen in most circumstances and is generally followed by a `force-capture` event instead of an `auth-capture`. Note that as the authorization has already been approved, `auth-standin` events do not trigger the webhook callback for the [Card Auth Loop Endpoint](/reference/card-auth-loop-endpoint), and you will not be able to decline the authorization. | Object | Type | Amount | | - | - | - | | Card Event | auth-standin | 25 | | Transaction | hold | -25 | | Card Event | force-capture | 25 | | Transaction | hold\_release | 25 | | Transaction | withdrawal | -25 | ### force-capture A `force-capture` is used when a valid authorization for the order is unavailable, but the order has been fulfilled and funds need to be transferred. This type of capture generally relies on a prior authorization for a lower amount than the capture to complete the transaction. In rare occasions, the force capture may not be linked to the initial auth request by trace\_id due to differing details/identifiers provided by the network. ##### Scenario 1 The initial authorization has been reversed due to a network or issuer request (or for some other reason) requiring the merchant to use a `force-capture` to secure the funds. Note the gap between the initial `auth-request` and the `auth-reversal`, as this delay in capturing funds is often the cause of the `auth-reversal` being issued. | Date | Object | Type | Amount | | - | - | - | - | | 2022-04-19 | Card Event | auth-request | 25 | | 2022-04-19 | Transaction | hold | -25 | | 2022-04-28 | Card Event | auth-reversal | 25 | | 2022-04-28 | Transaction | hold\_release | 25 | | 2022-05-10 | Card Event | force-capture | 25 | | 2022-05-10 | Transaction | withdrawal | -25 | ##### Scenario 2 The merchant does not send an initial `auth-request` and instead just issues a `force-capture` for the full amount. This scenario is often seen at gas stations. | Date | Object | Type | Amount | | - | - | - | - | | 2022-04-19 | Card Event | force-capture | 25 | | 2022-05-10 | Transaction | withdrawal | -25 | **Tips for Handling Force Captures** A force capture occurs when a clearing message settles funds without a prior authorization, or when the prior authorization has already been reversed. This bypasses your Card Auth Loop Endpoint entirely—you do not get an opportunity to approve or decline the transaction. One way to manage these risks is to monitor force capture frequency by merchant and MCC, maintain small buffer reserves to absorb unexpected captures, and implement alerting when force captures exceed thresholds. Force captures that exceed the cardholder's balance or appear fraudulent may also be candidates for chargeback. ### auth-clear-request An `auth-clear-request` is essentially a combination of an `auth-request` and an `auth-capture` rolled into a single event. Theses single-message transactions are commonly seen with PIN debits and ATM withdrawals. When an `auth-clear-request` is received, the account is immediately debited for the full amount of the transaction with no prior `hold` being placed on the funds. | Date | Object | Type | Amount | | - | - | - | - | | 2022-04-19 | Card Event | auth-clear-request | 25 | | 2022-04-19 | Transaction | withdrawal | -25 | ### auth-clear-adjustment This reduces the amount of a previous `auth-clear-request` by the specified amount. This scenario, while somewhat rare, can occur in instances where a merchant issues an `auth-clear-request` but the cardholder does not have enough funds in their account to cover the transaction. The most common outcome in this scenario is that a withdrawal will be made for the available balance on the cardholders account. The merchant will then complete the transaction and issue an adjustment for the difference between the final captured amount and the initial `auth-clear-request`. ##### Example A cardholder attempts to make a purchase in the amount of \$50. The merchant sends an `auth-clear-request` in the amount of \$50, but upon receipt, it is determined that the user only has \$25 available in their account. The \$25 is captured and the merchant is notified, at which point the transaction is completed, but only in the amount of \$20. So, the merchant then issues an `auth-clear-adjustment` for the \$5 difference, which is ultimately credited back to the users account. | Object | Type | Amount | | - | - | - | | Card Event | auth-clear-request | 50 | | Transaction | withdrawal | -25 | | Card Event | auth-clear-adjustment | 5 | | Transaction | deposit | 5 | ### auth-clear-reversal This reverses a previous `auth-clear-request` | Object | Type | Amount | | - | - | - | | Card Event | auth-clear-request | 25 | | Transaction | withdrawal | -25 | | Card Event | auth-clear-reversal | 25 | | Transaction | deposit | 25 | ### balance-inquiry-request This is a request for the available balance of an account. This request is often associated with a cardholder request from an ATM. | Object | Type | Amount | | - | - | - | | Card Event | balance-inquiry-request | 0 | ### chargeback-request This is a request to issue a chargeback to the cardholders account. These most often occur as the result of a cardholders claim that a transaction was fraudulent. | Object | Type | Amount | | - | - | - | | Card Event | auth-request | 25 | | Transaction | hold | -25 | | Card Event | auth-capture | 25 | | Transaction | hold\_release | 25 | | Transaction | withdrawal | -25 | | Card Event | chargeback-request | 25 | | Transaction | deposit | 25 | ### chargeback-reversal This reverses a previous `chargeback-request`. | Object | Type | Amount | | - | - | - | | Card Event | chargeback-request | 25 | | Card Event | chargeback-reversal | -25 | ### account-verification-request Also known as a zero-dollar authorization, an `account-verification-request` authorizes an account without placing a hold on funds. | Object | Type | Amount | | - | - | - | | Card Event | account-verification-request | 0 | ### original-credit-auth-request An `original-credit-auth-request` is sent when an Original Credit Transaction (OCT) is initiated to credit funds to a card. Unlike a refund, an OCT is not tied to a previous purchase — it represents a new inbound credit, such as a disbursement from a third-party service. If using the [Card Auth Loop Endpoint](/reference/card-auth-loop-endpoint) to manage authorizations, you will receive a callback with `message_type` set to `original-credit-auth-request`, allowing you to distinguish incoming OCT credits from regular spending authorizations. | Object | Type | Amount | | - | - | - | | Card Event | original-credit-auth-request | 25 | | Transaction | deposit | 25 | ### original-credit-auth-clear-request An `original-credit-auth-clear-request` combines authorization and capture for an Original Credit Transaction (OCT) in a single message. Funds are credited immediately. | Object | Type | Amount | | - | - | - | | Card Event | original-credit-auth-clear-request | 25 | | Transaction | deposit | 25 | # Card Fulfillment Source: https://docs.treasuryprime.com/docs/card-fulfillment ## Physical vs Virtual Cards Both physical and virtual cards are created and managed in the exact same manner; what differentiates the two and ultimately determines whether a physical card is issued is the [Card Product](/reference/card-product) used to issue the card. Card Products are configured for your specific card program by Treasury Prime and if virtual cards will be issued, a separate Card Product is created for this purpose. If you would like to issue a physical card that has a matching virtual representation of the card, you can expose the card details on the digital art you’ve created in your app. For more information see [Exposing Card Details](/docs/card-management#exposing-card-details). ## Issuing a Card Card issuance is covered in-depth in our [Issuing Cards](/docs/issuing-a-card) guide. ## Card Webhooks When a new card is created, a [webhook](/reference/webhook) callback is made if you have subscribed to updates for `card.create`. Likewise, if a card is updated, the `card.update` webhook is called. The body of the webhook callback will contain information regarding the affected card. ##### Example Webhook Notification ```bash bash theme={null} { "event": "card.create", "op": "create", "url": "https://api.sandbox.treasuryprime.com/card/card_11hahfpjb18t7y", "id": "card_11hahfpjb18t7y" } ``` ## Card Status The below are the potential values for the [card status](/reference/card): | Status | Description | | - | - | | unactivated | Default state assigned upon card creation. | | active | Card is now active and ready for use. | | suspended | Card has been frozen and is temporarily non-functional. A card can transition from `active` to `suspended` and back to `active` again. Refunds can still be completed while a card is suspended. Cards may be suspended through the API, often due to a customer request. | | terminated | Card has been permanently deactivated by expiration or direct update of the card status. Cards in this status cannot be reactivated. | ## Printed Character Limits Due to the limited space available for printing on a debit card, some [Person](/reference/get_person-id) object information may be truncated when personalizing a physical debit card. See the table below for the character limits on printed fields. These limits apply to all users who are issued a card. | Field | Character Limit | | - | - | | City | 18 | | Street Line 1 | 35 | | Street Line 2 | 35 | | Postal Code | 10 | | State | 2 | | Name (total of First + Middle + Last) | 21 | ## Issuing a Replacement Card If a card is lost, damaged, or nearing its expiration date, you can issue a replacement card by following the same steps used to issue any new debit card. Note that the new card will always be issued with a different PAN than the original card and it is not possible to re-issue a new card with the same PAN as any prior card. ## Card Issuing Limits By default, a [Person](/reference/get_person-id) can only have 10 cards in an `active` status at any given time (5 in the Developer Sandbox). This number is inclusive of both virtual and physical cards. If a person has reached their maximum allowed number of active cards, you will need to update the status of one or more existing cards prior to issuing or activating any additional cards for that person. Note: It is possible to increase the card issuing limits with prior approval. Please contact your Treasury Prime Account Manager for more information. ## Card Fulfillment and Delivery ### Card Fulfillment Statuses The below are the potential values for the [card fulfillment status](/reference/card): | Status | Description | | - | - | | issued | Request to issue card has been received and will be sent to the card printer for production. | | ordered | The card order has been produced and shipped. This is the terminal status for card fulfillment. | | digitally\_presented | The card details have been digitally presented to the user by use of the `show_pan` value of the `/card` endpoint. | | rejected | Card was rejected by card fulfillment provider. | | shipped | Card was shipped by card fulfillment provider. This field appears only if it is provided by the card fulfillment provider. | ### Shipping Address Cards will always be shipped to the `mailing_address` listed on the [Person](/reference/get_person-id) object attached to the Card. If there is no mailing address present, it will ship to the `physical_address`. ### Fulfillment Timelines Printing a card takes between 1-3 business days from the time it is received by the card printer. The shipping delivery time is estimated from the time a cards' fulfillment status transitions to `ordered`. Once this occurs, add on the number of days for the shipping option selected, and that is when you can expect your card to be delivered. ### Cancelling Production of a Card It is possible to cancel the request to issue a card as long as the card's fulfillment status is `issued`. This is the initial fulfillment status that is set at the time of the card issuing request. Once the card status changes to `ordered`, the card has been sent to the printer for fulfillment and the process can no longer be stopped. To cancel the order for a card with a fulfillment status of `issued`, update the card object's `status` property to `terminated`. Note that you cannot directly update the `status` in the fulfillment sub-object. Once terminated, the fulfillment status should not proceed to `ordered`. ##### Example ```bash bash theme={null} $ curl -u $API_KEY_ID:$API_KEY_VALUE https://api.treasuryprime.com/card/card_zuhqnmz7e085 \ -X PATCH \ -H 'Content-Type: application/json' \ -d '{ "status": "terminated" }' ``` ### Delivery Notifications There is not currently a method of providing notifications for when a card has been delivered to the recipient. # Card Management Source: https://docs.treasuryprime.com/docs/card-management There are a number of scenarios which may require you to take additional actions on a specific card after it has been issued to a cardholder including activation, renewal, suspension, and termination. Each of these scenarios is outlined below with accompanying examples. ## Activating a Card Before a card can be used for the first time, it will need to be activated. This can be accomplished by [updating](/reference/card) the card's status to `active`. Optionally, a PIN number can also be set for the card at this time by passing a `pin` value in the JSON body of the request. ##### Example ```bash bash theme={null} $ curl -u $API_KEY_ID:$API_KEY_VALUE https://api.treasuryprime.com/card/card_zuhqnmz7e085 \ -X PATCH \ -H 'Content-Type: application/json' \ -d '{ "status": "active", "pin": "1234" }' ``` ### Physical Card Activation Best Practices While it is ultimately up to you to determine the best method for verifying card information prior to activation, it is best practice to require the cardholder to enter their physical card details within your application UI before activating the card. This helps to prevent fraudulent transactions in the event that the card is intercepted by another party before reaching the cardholder. ## Suspending a Card To temporarily prevent a card from making any additional transactions, you can [update](/reference/card) its status to `suspended`. Any authorizations received while a card is suspended will be denied; however, refunds will still be processed. Cards that have been suspended can be reactivated by setting their status back to `active`. ##### Example ```bash bash theme={null} $ curl -u $API_KEY_ID:$API_KEY_VALUE https://api.treasuryprime.com/card/card_zuhqnmz7e085 \ -X PATCH \ -H 'Content-Type: application/json' \ -d '{ "status": "suspended" }' ``` ## Terminating a Card To permanently disable a card, [update](/reference/card) its status to `terminated`. Once a card has been terminated, it cannot be reactivated, and all future transactions will be denied. ##### Example ```bash bash theme={null} $ curl -u $API_KEY_ID:$API_KEY_VALUE https://api.treasuryprime.com/card/card_zuhqnmz7e085 \ -X PATCH \ -H 'Content-Type: application/json' \ -d '{ "status": "terminated" }' ``` ## Setting a PIN A four digit PIN can be set for a card by [updating](/reference/card) the `pin` value. Once the PIN has been set, the value of the `pin_is_set` property of the Card object will be changed to `true`. This same method can be used to update an existing PIN. ##### Example ```bash bash theme={null} $ curl -u $API_KEY_ID:$API_KEY_VALUE https://api.treasuryprime.com/card/card_zuhqnmz7e085 \ -X PATCH \ -H 'Content-Type: application/json' \ -d '{ "pin": "1234" }' ``` ## Renewing an Expired Card or Issuing a Replacement Card If a card is nearing its `expiration` date or has been damaged and requires replacement, you will need to submit a request to issue a new card. Cards may not be renewed beyond their original listed expiration. ### Replacement Best Practices When the date is approaching the `expiration` listed on a card, it is best practice to proactively issue a new card to the cardholder. When the cardholder receives a new card, you can allow the user to [activate it through your app UI](/docs/card-management#physical-card-activation-best-practices) before terminating the expiring card. This ensures that the user has continued debit card access to their account. Note that it is not possible to issue a new card with the same PAN as a previously issued card. ## Lost or Stolen Cards If a cardholder reports a card as lost or stolen, it is recommended you set the card's status to `suspended`, temporarily preventing any further transactions from being approved. Alternatively, a card can be terminated to permanently prevent any future transactions from being made on the original card. If desired, a new card can then be issued. ## Exposing Card Details Card details such as PAN and CVV are highly sensitive and should be treated with great care. By default, both the `pan` and `cvv` in the card object fields will return a value of null. If you need to retrieve or display this information, you have two options: [retrieving the PAN and CVV](/docs/card-management#retrieving-the-pan-and-cvv); or [using the Marqeta.js widget](/docs/marqeta_js). ### Retrieving the PAN and CVV In order to maintain security and legal compliance, full PAN and CVV values are not available by default via the API. If you need to retrieve the full PAN and CVV values to present them to users of your application, you will first need to provide proof of PCI compliance. Contact your Treasury Prime Account Manager to learn more about how to have this permission granted for your account. Once enabled, you can then retrieve the `pan` and `cvv` values by making a request to `/card/:id` and passing values of “true” for `show_pan` and `show_cvv` in the query string parameters. ##### Example ```bash bash theme={null} curl -u $API_KEY_ID:$API_KEY_VALUE https://api.treasuryprime.com/card/card_zuhqnmz7e085?show_pan=true&show_cvv=true ``` ### Using the Marqeta UX Toolkit or Marqeta.js Widget To eliminate the burden of proving PCI compliance, you can use Marqeta's tools to present full PAN and CVV details to your users. These tools inject iframes into your webpage or application allowing you to display this information to your end users without requiring you to store sensitive data on your servers. Marqeta is fully PCI-Level 1 compliant. **Recommended: Marqeta UX Toolkit** The [Marqeta UX Toolkit](/docs/marqeta_uxtoolkit) is the current solution for displaying sensitive card information. It provides enhanced security and functionality compared to Marqeta.js. The [Marqeta.js](/docs/marqeta_js) JavaScript library was originally scheduled to sunset on April 1, 2026. While Marqeta is not enforcing that deadline, customers have until the end of 2026 to complete their migration. If you are currently using Marqeta.js, plan to migrate to the UX Toolkit as soon as possible. * More information on Marqeta.js implementation: [https://www.marqeta.com/docs/developer-guides/using-marqeta-js](https://www.marqeta.com/docs/developer-guides/using-marqeta-js) * Token generation for Marqeta.js: [MarqetaJS documentation](/docs/marqeta_js) ## Card Management Methods Card activation, suspension, and termination are performed using the Treasury Prime API. Alternative methods of customer card management, such as Interactive Voice Response, are not supported at this time. # Cardholder Disputes Source: https://docs.treasuryprime.com/docs/cardholder-disputes Submit and manage debit card disputes in line with Regulation E (Reg E) and card network requirements. For specific information on dispute intake, data requirements, or reporting, contact your bank partner. Requirements can vary by bank. ## What are cardholder disputes? Cardholder disputes are claims that a cardholder submits to challenge a debit card transaction. A dispute is submitted when the cardholder believes a charge is unauthorized, incorrect, or otherwise should be reversed (for example, fraud, duplicate posting, or non-receipt of merchandise). Disputes are governed by **Reg E**, which implements the Electronic Funds Transfer Act (EFTA). EFTA allows consumers to challenge electronic transaction errors involving unauthorized or incomplete cardholder transactions as outlined in the issuing bank’s cardholder agreement. Some disputes qualify as errors under Reg E; others do not receive the same protection. Regardless of Reg E eligibility, all cardholder disputes should be submitted to the card processor, which submits them to the respective card network. ### Treasury Prime’s role Treasury Prime facilitates getting dispute information to the card network and relaying the outcome back to the program. Treasury Prime is not involved in any decision making about disputes; the bank and the card network determine eligibility, provisional credit, and resolution. ### Bank responsibilities The bank sets policy, provides training, and retains regulatory accountability. The bank works with the program to ensure disputes are handled according to regulatory requirements and bank policies. * **Process and oversight** — Bank shall establish a process to adjudicate and submit cardholder disputes through the processor and card networks when offering debit card products through program partners. Bank will work with the program to align on an intake process, including how disputes are submitted by the end customer. * **Reg E training** — Conduct Reg E training with the program. Reg E applies only to individual (consumer) cardholders, not commercial customers. Clarify that the program may still be required to submit a dispute to the bank through Treasury Prime (and thus to the card processor) even when it is not Reg E eligible. * **Roles and cost** — Agree with the program on roles, responsibilities, and the cost of submitting disputes. The bank is the issuing bank for the program’s card program. * **Reporting** — Establish dispute reporting with the program and Treasury Prime so the bank can provide dispute data to regulators during exams. * **Templates and approvals** — Approve dispute-related customer communications and templates used by the program. ### Program responsibilities The program is the front door for cardholder disputes and operates the dispute workflow. The bank retains ultimate regulatory responsibility. * **Dispute intake and customer experience** — Receive dispute submissions directly from end customers and collect all required details and documentation. Communicate clearly with customers throughout the dispute lifecycle and send dispute-related notifications using bank-approved templates. * **Provisional credit handling** — When applicable, issue provisional credits for Reg E–eligible disputes. These are typically funded from the program’s loss reserve at the bank; confirm mechanics with the bank. Track dispute aging and outcomes so credits are finalized or reversed correctly; credits become permanent after 45 days if the dispute remains unresolved. Coordinate with Treasury Prime, the bank, and internal teams as needed. * **Customer communications and notifications** — When sending customer communications, as agreed with the bank, send accurate, timely notifications for dispute receipt, provisional credit issuance or ineligibility, final resolution, and credit reversals. Use only bank-approved language and templates and provide customers access to documentation upon request. The program owns the day-to-day customer relationship; the bank owns regulatory accountability. * **Cost awareness** — Understand the cost of submitting disputes to the network. Decide when to submit versus paying out low-dollar (de minimis) disputes—see Scenario 7. Align these decisions with bank policy. * **Reporting and regulatory support** — Participate in dispute reporting with the bank and Treasury Prime. Provide dispute data as needed for regulatory exams, audits, and bank oversight. Maintain internal records that support traceability and compliance. Work with the bank partner to define dispute data requirements for compliance (what to collect, retention periods, and storage). ## How to submit a cardholder dispute Cardholder disputes are submitted through the **Submit a Debit Card Dispute** form. Use the form to submit a claim for any charges on a card that the cardholder wants to dispute. **Only one transaction can be submitted per form;** submit a separate form for each disputed transaction. **Form link:** [Submit a Debit Card Dispute](https://forms.monday.com/forms/09be9d62cc3f5c55c3e01d87e879e362?r=use1) ### Types of dispute When selecting the type of dispute on the form, you can choose from options such as: * **Fraud** — Unauthorized use of the card. * **Double Posting** — Same transaction charged more than once. * **Merchandise was returned** — Cardholder returned the item but was still charged. * **Merchandise not received** — Cardholder did not receive the item. * **Merchandise damaged, defective, or not as described** — Item received but not as expected. * **Cardholder was overcharged for the purchase** — Amount charged exceeds the agreed or correct amount. * **Credit did not post to the cardholder's account** — Expected credit or refund was not applied. * **ATM Withdrawal Incorrect** — Dispute related to an incorrect ATM withdrawal. * **Cancelled Membership or Services** — Cardholder cancelled but was still charged. Provide as much detail as possible in the **Description** field and fill in **Merchant Name**, **Amount**, and **Transaction ID** when available to speed up the investigation. ## Dispute notifications and provisional credit A critical part of offering any card program is having a clear, consistent process for handling disputed transactions and communicating with cardholders. Provisional credit for Reg E–eligible claims is typically issued from the program’s loss reserve at the bank. The exact mechanics (e.g., which account, timing) should be discussed with the bank. After a Reg E–eligible dispute has aged more than 45 days, the provisional credit becomes final. If the dispute is later won with the network after that point, the program’s loss reserve account is credited. Below are example email communications for the most common cardholder dispute scenarios. If the bank has the program send these to end customers who have submitted a dispute, the bank can use and edit these templates as needed. **Scenario 1:** The dispute has been received by the program from the customer, and a provisional credit has been issued. After the program receives a dispute from the customer, it is usually necessary to provide a provisional credit to cover the amount of the disputed transaction. This letter notifies the customer that a provisional credit has been issued and sets expectations for the timeline to a final resolution. > Dear \[Customer], > > Thank you for your recent submission of a cardholder dispute regarding \[Merchant/Amount]. > > We are committed to resolving this dispute as efficiently as possible. However, some investigations may take up to 90 days. We have issued a provisional credit to your account in the amount of \[\$\_\_\_], which represents the total amount of your dispute including any interest you may have lost if your account is an interest-bearing account. You will have full use of these funds during our investigation of your dispute. > > This provisional credit is a temporary credit until your dispute is resolved. To the extent that the dispute is resolved in your favor, the credit will become permanent. If we deny your claim for any reason, this provisional credit will be deducted from your account. You will be notified in this event. > > We may also request additional information from you. Therefore, please retain all documentation or materials related to the disputed item(s). > > If you have any further questions, please feel free to contact us at \[Contact Information]. > > Thank you for being a valued customer.\ > Regards, > \[Fintech] **Scenario 2:** The dispute has been received by the program from the customer and is not eligible for a provisional credit. Not all disputes are eligible for a provisional credit. This letter notifies the customer that the dispute has been received, that no provisional credit applies, and sets expectations for the timeline to a final resolution. > Dear \[Customer], > > Thank you for your recent submission of a cardholder dispute regarding \[Merchant/Amount]. > > We are committed to resolving this dispute as efficiently as possible. However, some investigations may take up to 90 days. To the extent that the dispute is resolved in your favor, a credit will be issued to your account. > > We may also request additional information from you. Therefore, please retain all documentation or materials related to the disputed item(s). > > If you have any further questions, please feel free to contact us at \[Contact Information]. > > Thank you for being a valued customer.\ > Regards, > \[Fintech] **Scenario 3:** Dispute has been resolved in favor of the merchant so the issued provisional credit must be reversed. Not all disputes are resolved in favor of the customer. This letter notifies the customer that the card network has resolved the dispute in favor of the merchant and that the provisional credit will be reversed. > Dear \[Customer], > > Thank you for your recent submission of a cardholder dispute regarding \[Merchant/Amount]. The investigation has been completed. > > We are sorry to inform you that your dispute claim has been denied. Based on our review, we are denying your dispute claim for the following reason:\ > \[Reason for denying dispute] > > As a result, the provisional credit in the amount of \[\$\_\_\_] given to you on \[MM/DD/YYYY], is being reversed five business days from the date of this letter on \[MM/DD/YYYY]. We will honor checks, drafts, or preauthorized transfers payable to third parties up to the amount of the debit from your account without charge to you as a result of an overdraft until that date. > > All documentation relied upon in making this decision are available for your review upon your request. If you have any further questions, please feel free to contact us at \[Contact Information]. > > The provisional credit previously issued on \[MM/DD/YYYY] for \[\$\_\_\_] will be reversed on \[today's date + X business days] as a result of the network ruling in favor of the merchant. If you have any questions, we may be able to request the documents that the network relied upon in making its decision. > > Thank you for being a valued customer.\ > Regards, > \[Fintech] **Scenario 4:** Dispute has been resolved in favor of the merchant and a provisional credit was not issued. Not all disputes are resolved in favor of the customer. This letter notifies the customer that the card network has resolved the dispute in favor of the merchant when no provisional credit was originally issued. > Dear \[Customer], > > Thank you for your recent submission of a cardholder dispute regarding \[Merchant/Amount]. The investigation has been completed. > > We are sorry to inform you that your dispute claim has been denied. Based on our review, we are denying your dispute claim for the following reason:\ > \[Reason for denying dispute] > > All documentation relied upon in making this decision are available for your review upon your request. If you have any further questions, please feel free to contact us at \[Contact Information]. > > Thank you for being a valued customer.\ > Regards, > \[Fintech] **Scenario 5:** Dispute has been resolved in favor of the customer so the provisional credit will be made permanent. This letter notifies the customer that the card network has resolved the dispute in their favor and that the provisional credit will become permanent. > Dear \[Customer], > > Thank you for your recent submission of a cardholder dispute regarding \[Merchant/Amount]. > > The investigation has been completed. We are happy to inform you that the dispute was resolved in your favor. As such, the provisional credit previously issued on \[MM/DD/YYYY] for \[\$\_\_\_] will become permanent. > > If you have any further questions, please feel free to contact us at \[Contact Information]. > > Thank you for being a valued customer.\ > Regards, > \[Fintech] **Scenario 6:** The dispute has been resolved in favor of the customer and a provisional credit was not issued. This letter notifies the customer that the card network has resolved the dispute in their favor when no provisional credit was issued, but a final credit is being issued. > Dear \[Customer], > > Your recent submission of a cardholder dispute regarding \[Merchant/Amount] in the amount of \[\$\_\_\_] has been completed. > > We are happy to inform you that the dispute was resolved in your favor. As such, we have credited your account for \[\$\_\_\_]. > > If you have any further questions, please feel free to contact us at \[Contact Information]. > > Thank you for being a valued customer.\ > Regards, > \[Fintech] **Scenario 7:** The dispute is de minimis so the program has opted to pay out the low-dollar dispute rather than submit it to the network. Submission of disputes to the card network has a fixed cost per dispute. When customers submit disputes for transactions of a lower dollar value than that cost, it can be financially prudent to issue a credit to the cardholder and absorb the cost. These are considered "de minimis" disputes. This letter notifies the customer that a credit has been issued and that the dispute has been resolved in their favor. > Dear \[Customer], > > Your recent submission of a cardholder dispute regarding \[Merchant/Amount] in the amount of \[\$\_\_\_] has been completed. > > We are happy to inform you that the dispute was resolved in your favor. As such, we have credited your account for \[\$\_\_\_]. > > If you have any further questions, please feel free to contact us at \[Contact Information]. > > Thank you for being a valued customer.\ > Regards, > \[Fintech] # Check Issuing Source: https://docs.treasuryprime.com/docs/check-issuing-1 This document provides an overview of the technical aspects of Treasury Prime's Check Issuing Implementation with Lob. It serves as a reference for understanding the bank requirements and feature capabilities of the implementation. ### Required Bank Inputs * **“Per-org” Check Issuing Settlement account:** each fintech customer enabled for check issuing will have their own check issuing specific settlement account. * **Account Closure Check Issuing Settlement account:** every bank will establish a settlement account in its own name for the purpose of closing acounts. To learn more about this account, please refer to our: [Account Closure Guide](https://docs.treasuryprime.com/docs/closing-an-account#closed-account-check-issuance) * **FBO Account:** This account is needed for end-to-end testing purposes. Once the FBO account is opened, Treasury Prime will create a test ledger for testing, and deposit funds into the ledger account. * **Dollar limits issued per-check unit:** If this field is set to null, the value will default to 3,000. However, if we have a "good funds model" provided, it will default to a per-check unit limit of \$100,000. * **[Issued Check Report](https://docs.google.com/spreadsheets/d/1Cf-NGRVI3g4hHTu5u46WfTYPnb5nw_iMrFZt0975KUU/edit#gid=276170393):** The bank will provide Treasury Prime with a daily report of all issued checks in CSV format. *(This is only necessary for banks that don't use the Bank Console to review and manage checks; to see the required format, click on the link)* * **[Cleared Check Report](https://docs.google.com/spreadsheets/d/1CQcn8ziOoU_hhrIW5N_O00siWJqJhlIwuj3nVJtz5Dg/edit?usp=drive_link):** The bank will provide Treasury Prime with a daily report of all cleared checks in CSV format. *(This is only necessary for banks that don't use the Bank Console to review and manage checks; to see the required format, click on the link)* ## Funds flow * [Check Image Example](https://drive.google.com/file/d/1fQ_y1zcJsCfEjuOxeF_G5yJ9M_1v8LRR/view) The check settlement account number is populated on the MICR line of the check Check Issuing Funds Flow 1. A fintech customer can use Treasury Prime's API to create a new issued check object. The customer needs to provide a payload that describes the check, including a memo and message (if desired), as well as metadata on the originating account and the amount transferred to the recipient. Once this data is received, Treasury Prime records a `created_at` timestamp on the check object and the check is immediately put into a `pending` status. At this point, the check data is sent to Lob, and funds are transferred from the ledger account to a per-org check settlement account. Treasury Prime's banking partners can view the checks in the Bank Console once the check object is created. 2. If a check fails to be created (for example, if a fintech customer submits incomplete data), it immediately moves to a status of `error`. This is a terminal status. When this happens, funds are moved back from the settlement account to the FBO and a new corresponding deposit transaction is created on the appropriate ledger account. 3. If a fintech customer wants to cancel a check that is still pending, they can do so by updating the check status to `canceled` in the Developer Dashboard. Banks can also initiate the cancellation of a check by updating the check status to `canceled` via the Bank Console. 4. One hour after the check is created, Lob adds the check to the printing queue. At this point, the status of the check is changed to `sent`. 5. If a fintech customer wants to request a stop payment on a check while it is in the status of `sent`, they can do so by updating the check status to `stop_payment_pending`. All checks in this status are displayed for Treasury Prime's banking partners to review in the Bank Console. Checks with a status of `stop_payment_pending` are organized in a queue for review. Bankers can also search for individual checks to retrieve unique check records. Once the bank approves the stop payment, Treasury Prime updates the check object with a status of `stop_payment`. Treasury Prime's banking partners are able to handle `stop_payment_pending` in two ways: 1. Our banking partners review a queue of checks with a status of `stop_payment_pending` and update them to `stop_payment` within the Bank Console. Any updates made in the Bank Console are immediately reflected in Treasury Prime's database. 2. Alternatively, all checks with a `stop_payment_pending` status are listed on the positive pay report with a **negative amount** and a `stop_payment_pending` status. The bank needs to update the status to `stop_payment` in the issued check report before Treasury Prime can update the status on our end. 6. Once a bank moves a check into either a status of `canceled` or `stop_payment`, funds are moved back from the settlement account to the FBO and a new corresponding deposit transaction is created on the appropriate ledger account. 7. When a check is deposited, the bank's core receives an X9 file from The Fed containing information about checks issued and deposited at the Receiving Depository Financial Institutions. The bank then reviews and downloads the X9 file. Using Treasury Prime's Bank Console or by passing Treasury Prime a file in the specified format predetermined SFTP folder (see the Auto-Clearing Checks section below for more information on this alternative to the Bank Console), the bank updates the status of the checks to either `dishonored` or `cleared`. If the check was previously marked as `stop_payment_pending`, it is updated to `stop_payment`. 8. After updating check status in the Treasury Prime console, the bank also updates the checks in their core. The core then moves funds from the organization's positive pay check issuing settlement account to the bank's Fed settlement account for checks that have cleared. 9. If a check is not actioned by the bank 180 days after it is moved into any non-terminal status (see check statuses below), Treasury Prime automatically moves it into a status of `expired`. This is a terminal status that is reflected in the Bank Console. When a check expires, funds are moved back from the settlement account to the FBO and a new corresponding deposit transaction is created on the appropriate ledger account. *The exceptions to this is if the originating account has been`closed`, or any time a check is `canceled`, `dishonored`, or `stop_payment`. In these cases, funds stay in the per-org settlement account.* 10. Once per day at a time agreed upon with the partner bank, Treasury Prime reconciles each fintech customer's check issuing-sweep accounts, ensuring all deposits, cancellations, or dishonored checks are accounted for (or covered by a fintech customer's loss-reserve account). Any alerting required to inform the fintech customer, bank, or Treasury Prime about reconciliation is done during the same step. ## Loss Reserve Requirements Per-fintech customer check issuing-settlement accounts must be capable of being drawn negative in order to release or return funds. These accounts will be reconciled daily against the fintech customer's loss reserve account. ## Reviewing and Managing Checks in the Bank Console The bank can review and manage all checks in the Treasury Prime Bank Console. This can be done by using the options to filter by organization, status, and date range. Additionally, the Bank Console provides views for **Decision Queue** and **Stop Payment Request** lists. ### Clearing Checks The banker clears a check by updating the status of the check in the Bank Console. This is done by marking it as `cleared`, which is located on the top right corner of the check’s details page. ### Canceling Checks **Checks can be canceled before they are mailed out within one hour from the moment they are issued.** To cancel a check, the banker must update its status in the Bank Console to `canceled`. Only checks with a status of `pending` can be canceled. ### Stopping Payment on Checks Once a check is mailed and reaches a sent status, the only way to stop payment on that check is by updating the status to `stop_payment`, which is located on the top right corner of the check’s details page. ## Checks' Status Overview | Status | Definition | Next status | Money Movement | | - | - | - | - | | `pending` | Check created successfully via API and queued up to be sent to Lob in 1 hour | One of: sent, error, canceled, expired, stop\_payment | Funds moved from FBO to per-org check issuing settlement account. | | `error` | Check not created correctly via API. | Terminal status | This status will be set at time of object creation before any funds have been moved. | | `sent` | Check data has been sent to Lob who will cut and mail check. | One of: pending\_cancelation, cleared, dishonored, expired | N/A | | `canceled` | Checks that have been canceled. This action can be performed by both banks and fintechs. | Terminal status | Funds moved from FBO to per-org check issuing settlement account. | | `stop_payment_pending` | For checks a fintech has requested to stop payment on after they have been cut and sent by Lob. This status requires bank review. | One of: cleared, stop\_payment, dishonored, expired | N/A | | `stop_payment` | Checks that the bank has reviewed and approved for stop payment | Terminal status | Funds moved from per-org check issuing settlement account back to FBO. | | `cleared` | Checks that have been sent and cashed by their recipient. | Terminal status | Funds will move from per-org check issuing settlement account to the bank's Fed settlement account | | `dishonored` | Checks that the recipient bank does not honor (ex. potential fraud, recipient account closed). This status is sometimes referred to as ‘returned’, but will always be reflected in Treasury Prime’s database as dishonored | One of: cleared, canceled, expired | N/A | | `expired` | Checks that have ‘aged out’ after 180 days. | Terminal status | Funds moved from FBO to per-org check issuing settlement account. | | `returned` | This status is exclusive to Piermont Bank for internal operations. | Non-terminal status | The funds will remain in the per-org check issuing settlement account. | ## Auto-Clearing Checks Issued via Treasury Prime's API This is only necessary for banks that don't use the Bank Console to review and manage checks; to see the required format, [click on the link](https://docs.google.com/spreadsheets/d/1CQcn8ziOoU_hhrIW5N_O00siWJqJhlIwuj3nVJtz5Dg/edit?usp=drive_link) 1. The bank will drop a report of cleared checks in the agreed-upon format into the specified SFTP folder. 2. Upon receipt of the report, Treasury Prime will perform the following actions for checks identified in the Cleared Checks Report: 1. Update the status of the check object to cleared. 2. Funds are book transferred from the Check Settlement Account to the Bank-specified Fed Aggregate Clearing Account. 3. Upon completion of step 2, Treasury Prime will generate and send a report to the bank identifying: 1. All successfully cleared checks. 2. Any checks present on the Cleared Checks Report that Treasury Prime was unable to clear. ## Positive Pay Report * [Positive Pay Example Report](https://docs.google.com/spreadsheets/d/1oWigJ-P8sc9s7WmgMfMI6cwpyluvU4qWYPOxOgYq7Sg/edit#gid=1211410438) The positive pay report is a daily CSV format report that we create and send to the bank at approximately 5am EST. This report notifies the bank of which checks we have issued and includes the account\_number, check\_number, check\_date, amount, and payee columns. The report will capture all checks with a status of `sent`, `pending`, `stop_payment_pending`, or scheduled that have not been included in a previous positive pay report. To stop a check that has already been sent, we take the following steps to ensure it is included on the positive pay report: 1. Update the amount field to be the negative of the original amount on the check. 1. Original amount: 50.20 0 → -50.20 2. Set the `positive_pay_sent` field to `null`. 3. Set the status of the check to `stop_payment_pending`. ## Frequently Asked Questions ### What roles does someone need to be set with in bank console in order to be able to decision on checks? The `check_issuing_review` permission (part of the Payments Reviewer role) is required
to clear or dishonor checks within the bank console. ### What event triggers bank operations staff to clear a check? Checks should be paid when presented by the Fed from the fintech customer's
check settlement account (the account number printed on the check image). Marking a check as cleared causes notifications to the fintech and updates the check's status within the Treasury Prime platform. ### Does the bank manually need to decision on every check? Yes; the bank console and the file-based positive pay file exchange are the two
methods for decisioning a check. All checks will be in "sent" status until the bank clears or dishonors each one. After 180 days, checks will expire and the funds are returned to the issuing ledger account. ### What test scenarios should be validated as part of launching check issuing? Two test scenarios should be validated with initial launch customers: * Clearing a check, funding the payment from the correct account. * Acknowleding a fintech's request to stop payment. * Dishonoring a check (e.g. the check amount does not match) and returning. ### How do stop payments work? Fintech customers can request a stop payment on an issued check. Operations
staff at the bank will need to acknowledge the stop payment and mark the stop payment as confirmed either via the bank console or batch file. ### When can a fintech request a stop payment? Fintechs can cancel a check within 1 hour of issuing the request. Once the
check is in the mail, stop payment can be requested at any time until the check is paid or it expires. # Closing an Account Source: https://docs.treasuryprime.com/docs/closing-an-account Closing an account is done primarily when an account owner no longer wishes to use their account. Upon account closure, a paper check will be issued with the remaining balance if the fintech does not zero the account. To the extent you, as the fintech, are seeking to initiate the close because you suspect fraud or nefarious conduct, always use the lock functionality and not the close functionality. See the guide for details. Closing an account must be done via a `PATCH` call to the [/account](/reference/account) endpoint. This must be done in careful consideration of the regulatory and operational impact. Closing an account requires additional permissions in the Treasury Prime API. Please contact support to have those enabled. ## The `closed_date` field When an account is closed, the [Account](/reference/account) object includes a `closed_date` field containing the timestamp of the closure in ISO 8601 format (`YYYY-MM-DDThh:mm:ssZ`). This field is always in UTC and is `null` for accounts that have not been closed. You can filter accounts by `closed_date` when listing accounts via the [`GET /account`](/reference/get_account) endpoint to identify accounts closed within a specific time range. ```json theme={null} { "account_type": "checking", "bank_id": "bank_treasuryprime", "closed_date": "2026-04-10T15:30:00Z", "status": "closed", "id": "acct_1029384756", "created_at": "2024-01-15T11:55:14Z" } ``` The `closed_date` field is available on a limited basis. Contact your relationship manager to discuss availability. ## Regulatory Compliance Impact Closing an account may have regulatory impact and should be done with care and in coordination with your banking partner. Treasury Prime, along with your bank partner, can help you create safe and lightweight compliance program. Contact Treasury Prime support for details. **Before closing any accounts, we recommend that you:** * Build out an account close remediation plan in collaboration with your banking partner and Treasury Prime. * Your plan should address the following questions, though this is not an exhaustive list: 1. How to handle customer account balances with the intent to zero them before initiating a close. 2. How to handle customer communications and inquiries related to closed accounts. 3. What message will display to end users when a transaction is attempted on a closed account. ## Close an Account Bank users can close an open account via the Console. Use this path when your bank operations team needs to close an account. **Prerequisites:** * A Banker Admin role in the Treasury Prime Console. Read-only roles cannot initiate closures. * The account must currently be in `open` status. * Coordinate with your account close remediation plan (see [Regulatory Compliance Impact](#regulatory-compliance-impact)) — zero the balance where required and make sure customer communications are ready before initiating the close. **Steps:** 1. In the Console, navigate to **Accounts** and open the account you want to close. 2. On the account detail page, open the account actions menu and select **Close Account**. 3. Confirm the closure in the modal. The account transitions to `close_pending` immediately, and Treasury Prime begins the same close processing performed by the API — canceling `pending` and `processing` payments, blocking new activity, and issuing a check for any remaining balance where applicable. The action is audited under your Console user. To find accounts you have moved to `close_pending`, use the **Accounts** area's status filter or the [List Accounts](/reference/get_account) endpoint with `status=close_pending`. ### Close an account through the API To close an account through the API, make a `PATCH` request to the `/account` endpoint with the status of `close_pending`. ##### Example Request ```bash bash theme={null} $ curl -u $API_KEY_ID:$API_SECRET_KEY https://api.treasuryprime.com/account/acct_1029384756 \ -X PATCH \ -H 'Content-Type: application/json' \ -d '{"status": "close_pending"}' ``` ## Find Accounts by Status The [List Accounts](/reference/get_account) endpoint accepts a `status` query parameter that filters accounts by their current state. Use this filter to retrieve only accounts in `open`, `close_pending`, or `closed` status — for example, to monitor accounts that are pending closure or to audit which accounts have already been closed. The `status` field is also returned on each account object in the response. ##### Example Request ```bash bash theme={null} $ curl -u $API_KEY_ID:$API_SECRET_KEY \ 'https://api.treasuryprime.com/account?status=close_pending' ``` To close an account, make a `PATCH` request to the `/account` endpoint with the status of `close_pending`. ## Activity On a Closed Account Many activities and API calls are blocked when an account has a status of `closed` or `closed_pending`. If there are unsettled card transactions when the account closure request is received, the account will not be closed until those transactions are settled, which may take 30+ days. To the extent there are transactions or returns that post after the account is closed, they will be visible through current balance and available balance. Any activity that changes the balance of an end user’s account will be the responsibility of the fintech to either disburse funds or collect funds as appropriate. ### Payments | Payment | Behavior When Closed | | - | - | | **ACH** | All `pending` and `processing` ACHs will be canceled when the close is initiated. Closed accounts are blocked from creating any new ACHs. Inbound ACHs will be returned. | | **Wire** | All `pending` wires will be canceled when the close is initiated. Closed accounts are blocked from creating any new wires. Inbound wires will also be blocked on a closed account. | | **Book Transfers** | Closed accounts are blocked from being either the `from_account_id` or `to_account_id` on a book transfer. | | **Check Issuing** | Closed accounts are blocked from issuing new checks. Note: In the case of when a check was issued from an end-user account and the account was closed sometime later, a `stop_payment `will be put on all outstanding checks and the funds will return to the end-user account. As part of the process, the receiving bank will need to send funds back to the customer/end user to bring the account to a \$0 balance prior to closing the account. Please confirm that this flow is enabled at your institution. | | **Check Deposit** | Closed accounts are blocked from depositing checks. | ### Cards When an account is closed cards will update based on their status at the time of the close. | Card Status Prior to Close | Behavior When Closed | | - | - | | `active` | Will be updated to a `terminated` status. | | `unactivated` | Will be updated to a `terminated` status. | | `suspended` | No change. | | `terminated` | No change. | ## Closed Errors When an API call is blocked due to a closed account a `403 - Forbidden` response will be returned with an error message detailing the cause. ```bash bash theme={null} {"error": "The account is closed."} ``` ## Closed Account Check Issuance Please reach out to your Bank partner to discuss enabling this feature. When a ledger account with a positive balance is closed, Treasury Prime issues checks for the remaining balance through the following process: 1. The fintech initiates account closure by updating the account status to `close_pending` through Treasury Prime's API 2. Treasury Prime verifies if there are any pending transactions. If pending transactions exist, the account remains in `close_pending` status for 30 days. 3. After verifying no pending transactions (or after the 30-day period), Treasury Prime checks the account balance. 4. For accounts with positive balances, Treasury Prime issues checks for the remaining amounts. These checks include a memo stating "release of funds" and a message indicating "releasing funds to customer for account closure". 5. After issuing the check, Treasury Prime transfers funds from the FBO account to the bank's Closed Account Check Settlement Account (CACSA). 6. The account balance is updated to zero, and the status changes from `close_pending` to `closed`. If a check is not cashed within 180 days, it's marked as `expired`. The bank is then responsible for escheating these funds to the state as required by unclaimed property laws. # Creating and Filing a 1099-INT Source: https://docs.treasuryprime.com/docs/creating-and-filing-a-1099-int This guide describes how to create and file a 1099-INT for an account. Treasury Prime cannot advise on a customer's tax liability. If you have any questions, it is recommended that you consult a tax professional. All third-party fees incurred in connection with generating and filing 1099-INTs on Treasury Prime's platform will be passed through to the customer. This guide uses the following endpoints * [PATCH /transaction/\{id}](https://docs.treasuryprime.com/reference/patch_transaction-id) * [POST /account/\{account\_id}/tax\_document](https://docs.treasuryprime.com/reference/post_account_tax_document) * [GET /account/\{account\_id}/tax\_document/\{id}](https://docs.treasuryprime.com/reference/get_account_tax_document-id) * [PATCH /account/\{account\_id}/tax\_document/\{id}](https://docs.treasuryprime.com/reference/patch_account_tax_document-id) * [DELETE /account/\{account\_id}/tax\_document/\{id}](https://docs.treasuryprime.com/reference/delete_account_tax_document-id) ### To create and file a 1099-INT for an account 1. Make sure all interest transactions for the account are correctly categorized 2. Generate the 1099-INT 3. Verify the 1099-INT is ready for filing 4. File the 1099-INT ## 1. Make sure all interest transactions for the account are correctly categorized To accurately generate the 1099-INTs, ensure that all relevant transactions are categorized as interest. For this, assign the category field on the transaction object as interest. Transactions can be assigned a category using a `POST` request to the [/transaction/\{id}](https://docs.treasuryprime.com/reference/patch_transaction-id) endpoint. ## 2. Generate the 1099-INT The /account/:account\_id/tax\_document endpoint can be used to generate the 1099-INT. The documents are generated asynchronously. A `POST` request to [/account/\{account\_id}/tax\_document](https://docs.treasuryprime.com/reference/post_account_tax_document) will return a `tax_document` object in pending status. ### Example request ``` curl --request POST \ --url https://api.treasuryprime.com/account/acct_11j8m4cp2pyth/tax_document \ --header 'content-type: application/json' \ --data ' { "year": "2023", "type": "1099" } ' ``` ### Example response ``` { "created_at": "2024-10-24T19:08:08Z", "updated_at": "2024-10-24T19:08:08Z", "account_id": "acct_11j8m4cp2pyth", "is_correction": false, "type": "1099", "year": "2023", "status": "pending", "skip_tin_verification": false, "id": "taxdoc_11khr0ve3vrg8" } ``` Once the document has been generated the status of the `tax_document` object will be updated to `ready_for_filing`. Generating the 1099-INT does not automatically cause it to be filed with the appropriate tax authorities. ## 3. Verify the 1099-INT is ready for filing To be notified of any changes in the status of a `tax_document`, register for the `tax_document.update` webhook. The status of the `tax_document` entry will update to `ready_for_filing` once the document has been generated. A `GET` call to [/account/\{account\_id}/tax\_document/\{id}](https://docs.treasuryprime.com/reference/get_account_tax_document-id) can be used to check the status of the document and obtain a URL where a draft of the document can be downloaded once it is ready. ### Example request ``` curl --request GET \ --url https://api.treasuryprime.com/account/acct_11j8m4cp2pyth/tax_document/taxdoc_11khr0ve3vrg8 ``` ### Example response ``` { "account_id": "acct_11j8m4cp2pyth", "is_correction": false, "type": "1099", "updated_at": "2024-10-25T20:46:04Z", "year": "2023", "status": "filed", "skip_tin_verification": false, "id": "taxdoc_11khr0ve3vrg8", "url": "https://api.treasuryprime.com/account/acct_11j8m4cp2pyth/statement/file_11khr0vt3vrgb", "created_at": "2024-10-25T20:45:34Z" } ``` ## 4. File the 1099-INT Once you've verified the information on the 1099-INT is correct, the 1099-INT can be filed by updating the status of the document to `filing`. This can be done with a `PATCH` request to [/account/\{account\_id}/tax\_document/\{id}](https://docs.treasuryprime.com/reference/patch_account_tax_document-id) ### Example request ``` curl --request PATCH \ --url https://api.treasuryprime.com/account/acct_11j8m4cp2pyth/tax_document/taxdoc_11khr0ve3vrg8 \ --header 'content-type: application/json' \ --data ' { "status": "filing" } ' ``` ### Example response ``` { "created_at": "2024-10-25T21:01:31Z", "updated_at": "2024-10-25T21:01:57Z", "account_id": "acct_11j8m4cp2pyth", "is_correction": false, "type": "1099", "year": "2023", "status": "filing", "skip_tin_verification": false, "id": "taxdoc_11khr0ve3vrg8" "url": null, } ``` The 1099-INT will be filed asynchronously and the status of the document will update to `filed` once filing is complete. By default, TIN verifcation will be performed before filing the 1099-INT with the tax agency. TIN verification checks the TIN/name of the recipient against the IRS database. TIN verification typically takes 24-48 hours to complete and is initiated when you trigger filing of the 1099-INT. If TIN matching fails, the document is moved to `error` status without filing it with the tax agency. After TIN verification is successful the 1099-INT is filed with the tax agency. TIN verification can be skipped by setting `skip_tin_verification` to `true` when creating or filing the tax document. When the document moves to `filed` status the draft `url` on the document will be cleared. The `url` will be populated with a URL where the filed document can be downloaded once it is ready. ## Tracking status of a filed 1099-INT When a 1099-INT is filed it initially moves to `filed` status. Once we receive notification that the tax agency has accepted or rejected the 1099-INT we will update the status of the document. The 1099-INT will move to `accepted` status when accepted without issue, `accepted_with_errors` status if the document is accepted but we are notified of an issue, and `error` status if the document is rejected. If registered, a `tax_document.update` webhook will be sent when the status changes. A `GET` call to [/account/\{account\_id}/tax\_document/\{id}](https://docs.treasuryprime.com/reference/get_account_tax_document-id) can be used to check the status of the document. ## Deleting an un-filed 1099-INT If you find a problem with a 1099-INT that has not been filed yet the document can be deleted and generated again after the incorrect information has been corrected. The 1099-INT can be deleted with a `DELETE` request to [/account/\{account\_id}/tax\_document/\{id}](https://docs.treasuryprime.com/reference/delete_account_tax_document-id). Once a 1099-INT has been marked `deleted` it cannot be filed. After deletion a new 1099-INT can be generated for the account with a POST request to [/account/\{account\_id}/tax\_document](https://docs.treasuryprime.com/reference/post_account_tax_document). ### Example request ``` curl --request DELETE \ --url https://api.treasuryprime.com/account/acct_11j8m4cp2pyth/tax_document/taxdoc_11khr0ve3vrg8 ``` ### Example response ``` { "created_at": "2024-10-24T19:08:08Z", "updated_at": "2024-10-24T19:13:51Z", "account_id": "acct_11j8m4cp2pyth", "is_correction": false, "type": "1099", "year": "2023", "skip_tin_verification": false, "status": "deleted", "id": "taxdoc_11khr0ve3vrg8" } ``` ## 1099-INT corrections If a corrected 1099-INT is needed for an account, first correct the errant information used to generate the 1099. Make sure that the information on businesses and persons associated with the account is accurate and all relevant transactions are categorized as interest. Then the corrected 1099-INT can be created with a `POST` request to [/account/\{account\_id}/tax\_document](https://docs.treasuryprime.com/reference/post_account_tax_document). Set the `is_correction` parameter on that endpoint to `true` to indicate that the document being created is a correction. A new 1099-INT will be generated in `pending` status. Only federal 1099-INT corrections can be handled through this endpoint. If a correction to a state 1099-INT is required please reach out to support for assistance. ### Example request ``` curl --request POST \ --url https://api.treasuryprime.com/account/acct_11j8m4cp2pyth/tax_document \ --header 'content-type: application/json' \ --data ' { "year": "2023", "type": "1099", "is_correction": true } ' ``` ### Example response ``` { "created_at": "2024-10-24T19:08:08Z", "updated_at": "2024-10-24T19:08:08Z", "account_id": "acct_11j8m4cp2pyth", "is_correction": true, "type": "1099", "year": "2023", "skip_tin_verification": false, "status": "pending", "id": "taxdoc_11khr0ve3vaf3" } ``` ## **Frequently Asked Questions** * **What if interest was paid outside the ledger (e.g., statement credit or check)?** * Currently, 1099-INT generation only calculates interest from transactions tagged as `interest` in the Treasury Prime ledger. There is no option to include interest payments made outside the ledger, such as manual checks or statement credits processed through other systems at this time. * **The Update a Transaction endpoint allows setting a category to "interest" or "fees." What happens if a transaction is categorized as "fees" or  "interest"?** -The category field on a transaction determines how that transaction is treated for 1099-INT reporting and statement summaries. Only transactions categorized as interest are included in 1099-INT filings. Transactions categorized as interest are included in the "Interest Paid" value on the statement generated for accounts while transaction categorized as fees are included in the "Fees" value. # Deposit Sweeps Source: https://docs.treasuryprime.com/docs/deposit-sweeps-1 This documentation provides step-by-step instructions for integrating with these services through Treasury Prime's platform, including API endpoints, authentication methods, and example use cases. ## Overview Treasury Prime's Enhanced FDIC Insurance allows end-customer accounts to receive extended FDIC coverage through two network options: * [IntraFi Network](https://www.intrafi.com/) - Provides coverage up to \$100M+ * [Reich & Tang (R\&T) Network](https://rnt.com/) - Provides coverage up to \$50M *\*\*These options are selected and/or vetted by the sponsor banks* ## Getting Started ### Prerequisites Before you begin, ensure you have the following: * **Treasury Prime Account**: Sign up for a Developer Sandbox account to access API keys and testing environments. * **API Credentials**: Obtain your API Key ID and API Secret Key from the Treasury Prime Developer Sandbox. * **Bank Partnership**: Establish a relationship with a partner bank that offers IntraFi or R\&T services through Treasury Prime. | Resources | Description | | :- | :- | | [Pre-Development Steps](/docs/deposit-sweeps-1#bank-enablement-steps) | This document provides information on Treasury Prime's Enhanced FDIC Insurance product offered in collaboration with our partner banks. | | [API Reference](/reference/enhanced-fdic-insurance#/) | ​The Enhanced FDIC Insurance API reference page provides comprehensive information on managing deposit sweeps to offer expanded FDIC insurance coverage. | | [FAQs](/docs/deposit-sweeps-1#frequently-asked-questions) | Frequently Asked Questions | ## Bank Enablement Steps Prior to enrolling in Enhanced FDIC Insurance, a Due Diligence process on the fintech between the bank and sweeps provider is required. The enablement timeline may vary depending on the bank's sweeps provider. 1. Ensure your bank or TP contract has been updated to enable Enhanced FDIC access. Your sponsor bank must have previously completed onboarding with their choice of Depository Network provider. 2. Ensure you've worked with your bank and/or the Depository Network directly (if needed) to execute any necessary agreements. Be aware that you may need to incorporate additional language into your end-user terms of service. 3. Your sponsor bank will complete some setup for your program with the Depository Network and Treasury Prime, like defining the deposit interest rate associated with your program to ensure your end users accrue the appropriate interest. Treasury Prime or your sponsor bank will notify you when those steps are completed 4. Once your program configuration is complete, you're ready to begin [API development ](https://docs.treasuryprime.com/reference/enhanced-fdic-insurance#/) ## Frequently Asked Questions ### If my end user withdraws funds that triggers a withdrawal from the depository network, are those funds subject to availability delays? No, in the case of a depositor withdrawing funds from their account when some of those funds are in the depository network, the bank makes the funds available upon request from the customer. ### Do balance details available via Treasury Prime’s API reflect deposits that sit in the Depository Network? Yes, the ledger balance always shows the sum of funds that exist on the bank's balance sheet directly + funds that may sit outside of the bank in IntraFI. ### How to configure Intrafi enrollment type? (i.e. , "reciprocal" vs "one-way sell")? Enrollment type can be updated by reaching out to Treasury Prime customer support at [help@treasuryprime.com](mailto:help@treasuryprime.com) or through the [Customer Support Platform](http://click.treasuryprime.com/MjUzLVdRQi04MjgAAAGaVKiw01D3t4V5ngYZDbHxzaFRuuA-0gM2Fkb6vmJ_IWl37RJ59BH80w_8pvfrjhegcFPjoQk=). These account types are set at a per-org level; at this time, per account is not available. ### How to set the account-specific interest rates? The default interest rate is 0%; however, to change this, a Fintech/Program can update it via the API. Bank Partners can update this via the console on that specific account page. ### How does interest payout work when a fintech has an interest rate in ICS? This may vary by Bank and IntraFi agreement. It is encouraged for Banks to work directly with IntraFi on this. ### How do thresholds work? When processing sweeps to IntraFi, we calculate the transaction amount (`delta`) based on the current balance of the account at the time the file is generated. The balance used for this calculation is pulled from the `current_balance` field of the account. The formula used to determine the transaction value (`delta`) is: ``` delta = max((current_balance - threshold_balance - sweep_balance), -sweep_balance) ``` #### **Example Calculation -** **Day 1: Initial Deposit**\ Current Balance: 400,000\ Threshold Balance: 250,000\ Sweep Balance: \$0 ***Calculation:*** ```lua lua theme={null} delta = max((400,000 - 250,000 - 0), -0) = max(150,000, 0) = 150,000 ``` 📌 Result: We sent a transaction of \$150,000 to IntraFi. **Day 2: Balance Reduction**\ Current Balance: 150,000\ Threshold Balance: 200,000 \ \ ***Calculation:*** ```lua theme={null} delta = max((200,000 - 250,000 - 150,000), -150,000) = max(-200,000, -150,000) = -150,000 ``` 📌 Result: We sent a transaction of -150,000 to IntraFi to bring the sweep balance to 0. # Digital Wallet Notifications Source: https://docs.treasuryprime.com/docs/digital-wallet-notifications A great way to reduce fraud exposure is to notify your cardholders when someone has attempted to add their card to a Digital Wallet such as Apple Pay™. If you are integrated with Marqeta through Treasury Prime, the allows you to know when a card was attempted to be added to a Digital Wallet so that you can notify the cardholder. ## Crafting a User Notification In the `networkdata` of the `token-activation-request`, there is a `token_service_provider` sub-object that contains information about the token requestor that you can use to inform the notification that you send to the cardholder. Sending this notification allows the cardholder the opportunity to reach out immediately in the case of potential fraud. ### token\_service\_provider sub-object | Parameter | Type | Description | | - | - | - | | token\_type | string | Comma-delimited list of digital wallet token types. | | correlation\_id | string | A unique value representing a tokenization request (Mastercard only). | | token\_reference\_id | string | Unique identifier of the digital wallet token within the card network. | | token\_requestor\_id | string | Unique numerical identifier of the digital wallet token requestor within the card network. These IDs map to a `token_requestor_name`. | | token\_requestor\_name | string | Name of the token requestor within the card network. | ### Example token\_service\_provider sub-object ```bash bash theme={null} "token_service_provider": { "token_type": "DEVICE_SECURE_ELEMENT", "correlation_id": "D0008606521111", "token_reference_id": "DAPLMC0000264791e37c56b00ce24194bda69345f4999000", "token_requestor_id": "50110030273", "token_requestor_name": "APPLE_PAY" } ``` ### Token Requestors You will see the following `token_requestor_name` and `token_requestor_id` in the `token_service_provider` sub-object which you can use to determine what Digital Wallet Provider the card was added to when crafting your messaging. | Network | token\_requestor\_name | token\_requestor\_id | | - | - | - | | Mastercard | APPLE\_PAY | 50110030273 | | Mastercard | ANDROID\_PAY | 50120834693 | | VISA | APPLE\_PAY | 40010030273 | | VISA | ANDROID\_PAY | 40010075001 | ### Example Communication Below is an example communication that can be used as a starting point to build your own messaging. Note: Please work with your partner bank to ensure communications are approved. > Dear \[Cardholder Name], > > Your \[Issuer Name] debit card has been added to \[Token Requestor Name] Pay™. > > We're excited to offer \[Token Requestor Name] Pay™ as an innovative and secure way to use your phone to make purchases with the touch of a finger. > > Your \[Token Requestor Name] Pay™ number is different than your debit card number. > > To help keep your information safe, your device account number in \[Digital Wallet Provider] Pay™ is different than the number on your debit card. > > * You can see the last four digits of your debit card number and device account number in your Wallet at any time. > * The last four digits of your device account number will show on the receipt when you make a purchase. > * You can still use your \[Issuer Name] debit card to make purchases. > > If your phone is ever lost or stolen, you should notify \[Issuer Name] by calling \[Issuer Support Number]. If you or an authorized user didn’t request for your debit card to be added to \[Digital Wallet Provider] Pay™, please call us at \[Issuer Support Number]. > > Sincerely, \[Issuer Name] # Early ACH Posting Source: https://docs.treasuryprime.com/docs/early-posting-for-incoming-ach-credits Early ACH Posting enables banks to allow program partners to give their end customers access to ACH funds before the normal settlement date. Payroll processing is a common use case for this feature. Early ACH Posting requires bank approval for transferring funds from the ACH settlement account to the ledger account. The bank must implement special reconciliation processes to use this feature effectively. When enabled, funds are debited from the Incoming ACH Settlement account before the actual settlement funds arrive. **Please note:** * Early ACH Posting is only available for inbound credits. Debits cannot be originated early through NACHA. * NACHA limits credits to at most two business days in the future. * The bank must fund the early credits Early ACH Posting availability varies by bank partner and requires bank approval. Contact your relationship manager to discuss availability and any associated costs. # FedNow Overview Source: https://docs.treasuryprime.com/docs/fednow FedNow is the Federal Reserve's instant payment service that enables approved financial institutions to provide safe and efficient instant payment services. Treasury Prime provides support for sending and receiving instant payments through the [Federal Reserve's FedNow® Service](https://www.frbservices.org/financial-services/fednow) via select partner banks, enabling real-time gross settlement on a 24/7/365 basis. ## FedNow key features * **Instant Settlement**: Payments settle within seconds, 24/7/365 * **Irrevocable**: Like wire transfers, FedNow payments cannot be reversed once sent * **High Value Limits**: Supports large payments to the extent approved by bank partner * **Rich Data**: Payments include enhanced remittance information ## Managing FedNow payments FedNow processes payments instantly, with funds available to recipients within seconds of initiation. Unlike ACH transfers, which are subject to specific windows during bank business hours, FedNow operates 24/7/365. ## Identifying FedNow transactions on accounts You can identify FedNow transactions on accounts by checking the `fednow_id` field in the [Transaction](/reference/get_transaction-id) object. This field contains the associated FedNow transaction ID. The `type_source` field on transactions is set to `fednow` for FedNow payments. You can use this field to filter account transactions by payment type. ### Example of incoming FedNow payment account transaction ```json theme={null} { "ach_id": null, "amount": "12.02", "balance": "1227.97", "billpay_payment_id": null, "book_id": null, "check_id": null, "check_number": null, "date": "2025-03-24", "desc": "FedNow transfer 202503243211779688172026683739635", "human_readable_description": "FEDNOW IN Wilmer Flores, 123456789 *2077, Fastball lessons 202503243211779688172026683739635" "extended_timestamp": "2025-03-24T17:20:02Z", "extended_timestamp_precise": "2025-03-24T17:20:02.665Z", "fednow_id": "fednow_11ky35224fez5zb", "fingerprint": "ttx_11gyn76cj5678b", "id": "ttx_11gyn76cj5678b", "incoming_wire": null, "issued_check_id": null, "summary": null, "trace_id": null, "type": "deposit", "type_source": "fednow", "wire": null, "wire_id": null } ``` ## Identifying FedNow Send/Receive transactions from `/fednow` endpoint The `payment_type` field indicates the direction of a FedNow payment. Inbound FedNow Receive payments appear as `credit`, while originated FedNow Send payments display as `debit`. ## Account closure and FedNow When a ledger account is closed, it's marked as inactive in the FedNow system. Inactive accounts automatically reject any incoming FedNow payments at the network level and cannot originate any FedNow payments. ## FedNow webhooks ### FedNow send webhooks Creating a FedNow Send payment will trigger the `fednow.create` webhook. As the FedNow payment progresses through different statuses, the system will trigger the `fednow.update` webhook for each status change. ### FedNow receive webhooks Inbound FedNow payments will trigger the `fednow.create` webhook when new incoming payments are received, and `fednow.update` when their status changes. ### Example of `fednow.create` webhook notification ```json theme={null} { "event": "fednow.create", "op": "create", "url": "https://api.treasuryprime.com/fednow/fednow_11ky35224fez5zb", "id": "fednow_11ky35224fez5zb" } ``` ### Example of `fednow.update` webhook notification ```json theme={null} { "event": "fednow.update", "op": "update", "url": "https://api.treasuryprime.com/fednow/fednow_11ky35224fez5zb", "id": "fednow_11ky35224fez5zb" } ``` FedNow availability varies by bank partner and requires bank approval. Contact your relationship manager to discuss availability and any associated costs. # FedNow Receive Source: https://docs.treasuryprime.com/docs/fednow-receive FedNow Receive enables Programs to receive inbound FedNow payments into accounts 24/7/365. Funds settle and are made instantly available in the account. Programs can enable receiving FedNow payments independent of FedNow Send capabilities. ### This guide uses the following endpoints * [`/fednow`](/reference/fednow) * [`/webhook`](/reference/webhook) ### To view incoming FedNow transactions 1. [Retrieve FedNow transactions using ](#1-retrieve-fednow-transactions-using-fednow)`/fednow` 2. [Monitor for incoming FedNow transactions](#2-monitor-for-incoming-FedNow-transactions) ## 1. Retrieve FedNow transactions using `/fednow` Retrieve a list of FedNow transactions by making a `GET /fednow` request. Incoming FedNow transactions are identified by a `payment_type` value of `credit`, while originated transactions show as `debit`. To retrieve a specific transaction, use the FedNow object ID in a `GET /fednow/{id}` request. ```json theme={null} { "description": null, "amount": "8.00", "bank_id": "bank_example", "related_fednow_ids": [], "account_id": "acct_11krnje614s6p3j", "security_context": null, "fed_settlement_date": "2025-07-03", "org_id": "org_example", "payment_type": "credit", "external_status": null, "external_routing_number": "011054252", "updated_at": "2025-07-03T16:59:18Z", "currency": "USD", "status": "done", "id": "fednow_11m6ddq51c3qtzk", "payment_id": "20250703626060097wlCpX6DiWq5PM5XisZ", "external_name": "David Hume", "error": null, "external_account_number": "110000994433", "originator_name": null, "memo": "Payment for coffee and excellent conversation", "created_at": "2025-07-03T16:59:17Z" } ``` ## 2. Monitor for incoming FedNow transactions Configure a `fednow.create` webhook to receive instant notifications whenever a new FedNow transaction arrives. Additionally, set up an `fednow.update` webhook to track any status changes in FedNow transactions. For more details and examples, see the webhooks section in the [FedNow Overview](/docs/fednow). The expected path for an incoming FedNow transaction is to be created in "pending" and then update to "done". # FedNow Send Source: https://docs.treasuryprime.com/docs/fednow-send FedNow payments can be sent 24/7, 365 days a year. Funds sent through the FedNow Service settle instantly. ### This guide uses the following endpoints * [`/account`](/reference/account) * [`/fednow`](/reference/fednow) * [`/fednow/routing_number`](/reference/get_fednow_routing_number) * [`/webhook`](/reference/webhook) ### To create a FedNow Send payment 1. [Check destination FI's FedNow Receiving capability](#1-check-destination-fis-fednow-receiving-capability) 2. [Get the Account ID](#2-get-the-account-id) 3. [Create the FedNow payment](#3-create-the-fednow-payment) 4. [Get status updates](#4-get-status-updates) ## 1. Check destination FI's FedNow Receiving capability Since FedNow is a relatively new payment rail, not all financial institutions (FIs) are set up to receive payments. To verify if a destination FI will accept FedNow payments, make a `GET /fednow/routing_number/` request with the destination FI's routing number. If both the `online` and `receive` fields return `true`, proceed to the next step. If either field returns `false`, you can either inform the end user that the FedNow payment cannot be completed because the destination FI doesn't accept FedNow payments, or reroute the payment through a fallback payment rail, such as ACH. ```bash theme={null} curl -u $API_KEY_ID:$API_SECRET_KEY https://api.treasuryprime.com/fednow/routing_number/110000994 ``` ## 2. Get the Account ID Obtain the account ID for sending a FedNow payment by making a `GET /account` request, which returns a list of all accounts. ```bash theme={null} curl -u $API_KEY_ID:$API_SECRET_KEY https://api.treasuryprime.com/account ``` Identify the `id` of the account you wish to send funds from. Verify that the account is neither [locked](/docs/locking-an-account) nor [closed](/docs/closing-an-account) before proceeding. ```json theme={null} { "tags": null, "account_type": "checking", "bank_id": "bank_example", "org_id": "org_fednow_example", "nickname": null, "updated_at": "2025-09-17T17:16:12Z", "currency": null, "routing_number": "026015024", "account_number": "2279603727", "id": "acct_11m2wpvk1afhmxd", "created_at": "2025-05-21T23:02:11Z", "userdata": null }, { "tags": null, "account_type": "checking", "bank_id": "bank_example", "org_id": "org_fednow_example", "nickname": null, "updated_at": "2025-04-02T22:04:47Z", "currency": null, "routing_number": "026015024", "account_number": "511100003797", "id": "acct_11kyvd2a184kych", "created_at": "2025-04-02T22:03:54Z", "userdata": null } ``` ## 3. Create the FedNow payment Create the FedNow payment by initiating a `POST /fednow` request. The `security_context` object requires two fields: `ip_address` (the originating requestor's IP address) and `user_agent` (the originator's browser or device). An optional [`originator_name`](#modifying-originator-name-on-fednow-payment) field allows you to modify the sender name for third-party sender scenarios. ```bash theme={null} curl --request POST \ --url https://api.treasuryprime.com/fednow \ --user $API_KEY_ID:$API_SECRET_KEY \ --header 'Content-Type: application/json' \ --data '{ "account_id": "acct_11m2wpvk1afhmxd", "amount": "250.00", "external_name": "Adam Smith", "external_routing_number": "110000994", "external_account_number": "110022339940", "memo": "Payment for economic advice", "security_context": { "device_id": "2f4a3f0005614323a61ac09918d29129", "ip_address": "192.168.1.1", "user_agent": "Mozilla/5.0" } }' ``` Upon submission, Treasury Prime creates a new FedNow object with `pending` status. Because FedNow is an instant payment service, you cannot cancel the transaction after creating. ```json theme={null} { "description": null, "amount": "250.00", "bank_id": "bank_example", "related_fednow_ids": [], "account_id": "acct_11krnje614s6p3j", "security_context": { "ip_address": "192.168.1.1", "user_agent": "Mozilla/5.0", "device_id": "2f4a3f0005614323a61ac09918d29129" }, "fed_settlement_date": null, "org_id": "org_example", "payment_type": "debit", "external_status": null, "external_reject_reason": null, "external_routing_number": "110000994", "updated_at": "2025-09-22T19:59:59Z", "currency": "USD", "status": "pending", "id": "fednow_11md3anz1fsags2", "payment_id": null, "external_name": "Adam Smith", "error": null, "external_account_number": "110022339940", "originator_name": null, "memo": "Payment for economic advice", "created_at": "2025-09-22T19:59:59Z" } ``` ### `status` vs `external_status` clarification The `status` field indicates the FedNow object's current state within Treasury Prime's system. In contrast, the `external_status` field shows how the payment is being processed at the external financial institution. For instance, a FedNow payment might have a `status` of `sent` (meaning Treasury Prime successfully transmitted it) while having an `external_status` of `rejected` (indicating the receiving financial institution declined to accept it). See [FedNow Send Scenarios and Corresponding Statuses](#fednow-send-scenarios-and-corresponding-statuses) for a list of the various FedNow scenarios and their associated `external_status` values, and [FedNow Status and External Status Mappings](#fedNow-status-and-external-status-mappings) for a visual representation of how these statuses relate to each other. ### Insufficient funds on account behavior FedNow payments may occasionally fail due to insufficient funds in the sending account. When this happens, the FedNow object's status will change to `error`, and the `error` field will display an insufficient funds message noting that the account balance is lower than the requested amount (ex: `Not enough funds: 186.88 < 200.00`). ## 4. Get status updates There are two ways to find out when the status of the FedNow payment has changed: ### Manually checking for status updates To retrieve the latest status of a FedNow payment, make a `GET /fednow/{id}` request with the FedNow object's ID. ```bash theme={null} curl -u $API_KEY_ID:$API_SECRET_KEY https://api.treasuryprime.com/fednow/fednow_11md3anz1fsags2 ``` Notice that the `status` field has changed to `sent` and the `external_status` field has updated to `done`. ```json theme={null} { "description": null, "amount": "250.00", "bank_id": "bank_example", "related_fednow_ids": [], "account_id": "acct_11krnje614s6p3j", "security_context": { "ip_address": "192.168.1.1", "user_agent": "Mozilla/5.0", "device_id": "2f4a3f0005614323a61ac09918d29129" }, "fed_settlement_date": null, "org_id": "org_example", "payment_type": "debit", "external_status": "done", "external_reject_reason": null, "external_routing_number": "110000994", "updated_at": "2025-09-22T20:00:06Z", "currency": "USD", "status": "sent", "id": "fednow_11md3anz1fsags2", "payment_id": "20250922626060097P0Fpuc4iQR9ByM9cdZ", "external_name": "Adam Smith", "error": null, "external_account_number": "110022339940", "originator_name": null, "memo": "Payment for economic advice", "created_at": "2025-09-22T19:59:59Z" } ``` ### Listening to status updates with webhooks Set up a `fednow.create` webhook to receive notifications about newly created FedNow Send objects and a `fednow.update` webhook for status changes. For implementation examples, see the webhooks section in the [FedNow Overview](/docs/fednow). Since FedNow is an instant payment system, transactions will progress through various statuses rapidly. ## Modifying originator name on FedNow payment When Programs originate a FedNow payment, the system automatically assigns a sender name—the primary person for personal accounts or the business name for business accounts. This name appears as the originator on the FedNow transaction at the receiving financial institution. Programs acting as Third Party Senders may need to modify this sender name. To customize the sender name, simply set the `originator_name` field to your desired value. Modifying originator names may require bank approval. Please discuss with your bank partner(s) to implement. ## FedNow `status` and `external_status` mappings FedNow Send status and external status mappings ## FedNow Send scenarios and corresponding statuses Most FedNow payments are accepted by the receiving financial institution (FI), though some may be rejected or placed in an "Accepted Without Post" status. The table below details the various FedNow Send scenarios with their corresponding `external_status` values. | Scenario | Description | External Status | | - | - | - | | Accepted | FedNow payment successfully sent and accepted by the receiving financial institution (FI). | `done` | | Rejected | The receiving FI rejected the FedNow payment and will send an inbound payment to return the funds. | `rejected` | | ACWP | Accepted Without Post (ACWP) means the receiving FI received the payment but did not post the transaction. The receiving FI's staff will manually review the transaction. During this review, the external status remains `pending` until a final decision is reached. There are three possible final outcomes listed below. | `pending` | | ACWP - Accepted | Receiving FI reviewed and accepted the payment, posting it to the recipient account. | `done` | | ACWP - Blocked | Receiving FI reviewed and decided not to post the payment, and will not return the payment. | `blocked` | | ACWP - Rejected | Receiving FI reviewed and rejected the payment. The receiving FI will initiate an inbound FedNow payment to return funds. | `rejected` | ## Handling FedNow returns While FedNow payments are described as irrevocable, in rare instances, the receiving financial institution may return a payment, typically when payments are rejected. When this happens, you'll see a separate inbound FedNow transaction matching the amount of the original payment, with the `related_fednow_ids` field containing the original payment's ID. You can use this ID to identify the payment as a return and notify the end user. Additionally, the `external_status` on the original payment will update to `rejected`. Note: Not every payment in rejected status will have a return transaction. ### Example of inbound FedNow return transaction with `related_fednow_ids` populated Below is a return example for the FedNow payment originated in the steps above. Note that the `related_fednow_ids` field contains the original FedNow object ID, allowing you to connect this return with the initial payment. ```json theme={null} { "description": null, "amount": "250.00", "bank_id": "bank_example", "related_fednow_ids": [ "fednow_11md3anz1fsags2" ], "account_id": "acct_11krnje614s6p3j", "security_context": null, "fed_settlement_date": "2025-07-03", "org_id": "org_example", "payment_type": "credit", "external_status": null, "external_reject_reason": null, "external_routing_number": "011055555", "updated_at": "2025-09-22T22:42:53Z", "currency": "USD", "status": "done", "id": "fednow_11m6d97w1c3bx8x", "payment_id": "202507036260600971yMpCkrY8ynQVP5so5", "external_name": "Adam Smith", "error": null, "external_account_number": "110000994433", "originator_name": null, "memo": null, "created_at": "2025-09-22T22:42:52Z" } ``` # Reviewing flagged ACHs Source: https://docs.treasuryprime.com/docs/flagged-ach Treasury Prime supports your bank's NACHA fraud-monitoring obligations by flagging higher-value debit ACHs for review. This page covers what flagging is, how to configure your threshold, and how to review flagged ACHs in Console. #### What is a flagged ACH? A flagged ACH is an originated debit ACH that Treasury Prime has identified for banker review based on a configurable dollar threshold. Flagging is part of Treasury Prime's risk-based fraud-monitoring procedures under [NACHA's 2026 Rule amendments](https://www.nacha.org/rules/risk-management-topics-fraud-monitoring-phase-2). Key things to know: * **Flagging is non-blocking.** Flagged ACHs continue to process on their normal schedule. The flag exists so your bank's risk team can review the transaction; it does not delay or stop the payment. * **Only originated debit ACHs are flagged.** Credit ACHs, incoming ACHs (where the bank is the RDFI), and ACH returns are out of scope for this feature. * **Flagging happens at ACH creation time** based on the threshold configured for the originating program or account. #### Configuring the threshold Set the **ACH Flag Review Threshold** under **Programs > Limits > ACH Limits**. The threshold can be set at the **program** level (applies to all accounts on the program by default) or the **account** level (overrides the program-level value for that account). | Setting | Behavior | | :- | :- | | No threshold set (anywhere) | Platform default of **\$10,000** applies | | Program threshold set, no account override | Program threshold applies to all accounts on the program | | Threshold set to `0` | All originated debit ACHs are flagged | > **About the \$10,000 default:** This value is based on Treasury Prime's internal risk assessment of our overall ACH portfolio. NACHA's rule requires each party to perform its own risk assessment; you should tune the threshold based on your bank's risk appetite and the profile of each program. #### Reviewing flagged ACHs 1. In Console, navigate to **Payments > ACH**. 2. Select the **Flagged ACH (Needs Review)** tab. This tab shows originated debit ACHs that have been flagged and have **not yet been reviewed**. 3. The table includes the following columns: * **Originator / Source** — the program or originator that initiated the ACH * **Amount** — the transaction amount * **Counterparty** — the receiving counterparty * **Updated** — when the ACH was last updated 4. Click a row to open the ACH detail page. 5. In the **Flagged ACH Details** section, click the chevron next to the red **Needs Review** badge and select **Mark Flagged ACH as Reviewed**. 6. Confirm in the modal: *"This will mark this flagged ACH as reviewed."* Click **Yes, mark the ACH as reviewed.** 7. The badge flips from red **Needs Review** to green **Reviewed**, a confirmation toast appears, and the **Reviewed By** and **Reviewed At** fields populate with your user and the current timestamp. #### Reviewing multiple flagged ACHs at once When your Flagged ACH queue contains several items that share the same disposition, you can mark them reviewed in bulk instead of opening each ACH one at a time. This shortens the daily review workflow for banks operating under NACHA's 2026 fraud-monitoring rules. 1. On the **Flagged ACH (Needs Review)** tab in **Payments > ACH**, use the checkbox at the start of each row to select the ACHs you want to review. 2. Once you select one or more rows, a Review N Flagged ACHs button appears at the top right of the tab (for example, Review 2 Flagged ACHs; a single selection reads Review Flagged ACH). Click it. 3. Confirm in the modal. Treasury Prime marks each selected ACH as reviewed, stamps your user and the current timestamp on the **Reviewed By** and **Reviewed At** fields, and removes the ACHs from the **Needs Review** tab. #### The ACH detail page The **Flagged ACH Details** section on the ACH detail page shows the ACH's flagged status. The section includes: * A status badge in the section header: * **Needs Review** (red) — the ACH is flagged but has not been reviewed * **Reviewed** (green) — the ACH has been reviewed * **Reviewed** — Yes or No * **Reviewed By** — the user who marked it reviewed, or N/A * **Reviewed At** — the timestamp of review, or N/A When the badge is **Needs Review**, a chevron next to it opens a dropdown with a **Mark Flagged ACH as Reviewed** action (see "Reviewing flagged ACHs" above). To revisit a previously reviewed flagged ACH, navigate to the ACH directly (via ACH ID search or from the Originated ACH tab); the green **Reviewed** badge and review details will be visible on the detail page. #### Best practices * **Assign clear ownership.** Identify the banker(s) responsible for the daily flagged-ACH review queue. * **Establish a review cadence** that meets your bank's overall NACHA fraud-monitoring procedures (e.g., daily within N business days of flagging). * **Document your procedures.** Reviewers should follow a written procedure that describes what they're checking and what triggers escalation. Treasury Prime's flagging is one input into your bank's broader fraud-monitoring program — not a replacement for it. * **Revisit your threshold quarterly** as part of your risk assessment. *** # Getting Started Source: https://docs.treasuryprime.com/docs/getting-started Start building today with Treasury Prime's APIs for banking. This guide uses the following endpoints: * [`/ping`](https://docs.treasuryprime.com/reference/health-check#/) * [`/account`](https://docs.treasuryprime.com/reference/account#/) #### To accomplish this you will need to 1. [Create a Developer Sandbox account](#1-create-a-developer-sandbox-account) 2. [Create API keys](#2-create-api-keys) 3. [Test the API keys](#3-test-the-api-keys) 4. [Get an account balance](#4-get-an-account-balance) ## 1. Create a Developer Sandbox Account In order to start working with the Treasury Prime API, you will need to [create a free Developer Sandbox account](https://app.sandbox.treasuryprime.com/sign_up). This provides access to the Developer Sandbox where you can create and manage API keys, and safely test the API without worrying about interfering with production data. ## 2. Create API keys Before making requests to the Treasury Prime API, you will need to generate a set of API keys. These keys act much like a username and password, and are used to authenticate each request. See our API Docs for more information. To create your keys, login to the [Developer Sandbox](https://app.sandbox.treasuryprime.com/sign_up) and click the "Create API Keys" button, then click "Create API Key". Carefully save the secret key that is generated. It is only shown once, so don't lose it. ## 3. Test the API keys To make sure everything is working as expected, you can use `curl` on the command-line to make a request to the `ping` endpoint which validates your API Key ID and API Secret Key and returns a response as shown below. First store your API Key ID and API Secret Key as environment variables. Run the following in your command-line, replacing \ and \ with your API Key ID and API Secret Key values: ```bash bash theme={null} $ export API_KEY_ID= $ export API_SECRET_KEY= ``` Call the `ping` endpoint using [HTTP Basic Auth](http://en.wikipedia.org/wiki/Basic_access_authentication), providing your API Key ID as the username, and the API Secret Key as the password. ```bash bash theme={null} $ curl -u "$API_KEY_ID:$API_SECRET_KEY" https://api.sandbox.treasuryprime.com/ping ``` The response should look similar to the one below. ```bash bash theme={null} { "api_version": "1", "version": "1.11.207-gb5accf2c", "time": "2021-02-25T01:59:23.091Z" } ``` ## 4. Get an account balance Great work creating and validating your API keys, now comes the fun part! We've already created a few accounts in the Developer Sandbox for you to use. These accounts have been pre-funded with 5k, so you're ready to dive right in and check the available balance on an account. Get a list of all the available accounts using the `account` endpoint. ```bash bash theme={null} curl -u "$API_KEY_ID:$API_SECRET_KEY" https://api.sandbox.treasuryprime.com/account ``` The response should look similar to the one below. ```bash bash theme={null} { "data": [ { "account_type": "savings", "bank_id": "bank_treasuryprime", "updated_at": "2021-02-01T16:32:34Z", "currency": null, "routing_number": "000000000", "account_number": "123000012345", "id": "acct_qda4pJZfpzn4fc", "created_at": "2021-01-13T15:05:14Z", "userdata": null }, { "account_type": "checking", "bank_id": "bank_treasuryprime", "updated_at": "2021-02-01T16:32:34Z", "currency": null, "routing_number": "000000000", "account_number": "123000067890", "id": "acct_wVwR87rxhMRdwD", "created_at": "2021-01-13T15:05:13Z", "userdata": null } ], "total_estimated": 10 } ``` The response should contain several accounts, each containing an `id` property with a unique value such as `acct_2w458dsi392h2m`. Using this value, you can request the details for a specific account (including the current balance) by calling the Account endpoint and passing the `id` value (shown here as :id). ```bash bash theme={null} curl -u "$API_KEY_ID:$API_SECRET_KEY" https://api.sandbox.treasuryprime.com/account/:id ``` In the response data, you should see the `available_balance` which shows the amount of money in the account that is immediately available for transactions. ```bash bash theme={null} { "address": { "street_line_1": "123 Kearny St", "street_line_2": null, "city": "San Francisco", "state": "CA", "postal_code": "94102" }, "account_type": "checking", "bank_id": "bank_treasuryprime", "person_ids": ["psn_26a98dsf184j7a"], "available_balance": "5000.00", "name": "Account Owner", "updated_at": "2021-01-28T14:47:13Z", "currency": "USD", "routing_number": "000000000", "status": "open", "primary_person_id": "psn_26a98dsf184j7a", "account_number": "098234989485", "locked": false, "id": "acct_23f18dja392m60", "funded": false, "business_ids": [], "current_balance": "5000.00", "created_at": "2021-01-28T14:47:11Z", "userdata": null } ``` # Green Dot Cash Deposits Source: https://docs.treasuryprime.com/docs/green-dot-cash-deposits Enable customers to add funds to their accounts using cash at 90,000+ retail locations nationwide Prime Cash (Powered by Green Dot) provides a convenient cash funding option for customers who prefer or need to use physical currency. This guide covers how to integrate Green Dot cash deposits, generate barcodes, find retail locations, and manage deposit limits through the Treasury Prime API. Green Dot availability varies by bank partner and requires bank approval. Contact your Treasury Prime Account Manager to discuss availability and any associated costs. ## What is Green Dot cash deposit? Green Dot cash deposit allows your customers to add funds to their accounts by visiting participating retail locations and providing cash to the cashier. The customer presents a barcode (generated through the Treasury Prime API) at the point of sale, hands over cash, and Treasury Prime loads the funds to their account after authorization. Treasury Prime has partnered with Green Dot® to deliver Prime Cash (Powered by Green Dot), providing access to over 90,000 participating retail locations nationwide including major chains like Walmart, CVS, Walgreens, 7-Eleven, and Dollar General. This makes cash deposits accessible and convenient for customers across the country. The integration handles the entire deposit lifecycle from barcode generation through fund settlement. You generate a barcode for the customer through the API, they present it at a retail location with cash, and Treasury Prime processes the authorization and posts the funds to the account. The system tracks each deposit through multiple status transitions and provides real-time updates via webhooks. Green Dot cash deposits are particularly valuable for customers who are unbanked, underbanked, or prefer cash transactions. The feature expands financial access and provides flexible funding options for both individual and business accounts. ©2026 Green Dot Corporation. Green Dot is a registered trademark of Green Dot Corporation. ### Key benefits 1. **Extensive retail network**: Access to over 90,000 participating retail locations nationwide, making cash deposits convenient for customers regardless of location. 2. **Real-time status tracking**: Monitor deposits from barcode generation through completion with status updates at each stage, including pending, authorized, available, and complete. 3. **Flexible deposit amounts**: Support various cash amounts based on your configured limits, with Green Dot handling the transaction processing and fee collection at the point of sale. 4. **Location finder integration**: Help customers find nearby participating retailers using the location search API with zip code or GPS coordinates. 5. **Configurable limits and controls**: Set transaction minimums, daily limits, monthly limits, and total program limits at both organization and account levels for risk management. ## How Green Dot cash deposits work The Green Dot cash deposit process involves generating a barcode for the customer, the customer presenting it at a retail location with cash, and Treasury Prime processing the authorization and settlement. When you call the [`POST /greendot`](/reference/post_greendot) endpoint, Treasury Prime communicates with Green Dot to generate a unique barcode number. Green Dot determines the barcode expiration time (typically around 1 hour) and returns it in the response. The barcode can only be used once. The customer displays this barcode (as an image or numeric code) to the cashier at a participating retail location. Generating a new barcode for an account automatically invalidates any previous unused barcode for that account. Only one barcode can be valid at a time per account. At the retail location, the cashier scans the barcode and the customer provides cash. The retailer collects a fee (typically $3-$5 depending on location) and processes the transaction through Green Dot's network. Green Dot sends an authorization request to Treasury Prime, which validates the deposit against configured limits and account status. Once authorized, the deposit moves through several status transitions. It starts as `authorized` when Green Dot confirms the transaction, becomes `available` when funds are ready to use, and finally reaches `complete` when fully settled. Treasury Prime sends webhook events at each status change, allowing you to notify customers about their deposit progress. ### Generating a barcode When you generate a barcode for a customer: 1. **Treasury Prime validates the request**: The system checks that the account exists, is open, and that all required parameters (account ID, retailer key, device information, geolocation, email) are provided. 2. **Green Dot creates the barcode**: Treasury Prime calls Green Dot's API to generate a unique barcode number. Green Dot determines the expiration time (typically around 1 hour). The barcode can only be used once. 3. **Treasury Prime returns the barcode**: The API response includes the barcode number, expiration timestamp, and deposit ID. You display this barcode to the customer as an image or numeric code. 4. **Webhook event fires**: Treasury Prime sends a `greendot.create` webhook event with the deposit details and barcode information. ##### Example request to generate a barcode ```bash bash theme={null} curl -X POST \ -u $API_KEY_ID:$API_SECRET_KEY \ https://api.treasuryprime.com/greendot \ -H 'Content-Type: application/json' \ -d '{ "account_id": "acct_1234567890", "retailer_key": "2812", "channel_type": "mobile", "device_type": "mobile", "latitude": "39.724121", "longitude": "-94.793228", "ip_address": "192.168.1.100", "email_address": "customer@example.com" }' ``` ##### Example response ```bash bash theme={null} { "id": "gdep_1029384756", "account_id": "acct_1234567890", "bank_id": "bank_vado", "retailer_key": "2812", "channel_type": "mobile", "device_type": "mobile", "ip_address": "192.168.1.100", "latitude": "39.724121", "longitude": "-94.793228", "email_address": "customer@example.com", "barcode_number": "830324014617630280006355261955", "amount": null, "status": "pending", "expires_at": "2024-01-15T15:30:00Z", "authorized_at": null, "available_at": null, "completed_at": null, "voided_at": null, "expired_at": null, "created_at": "2024-01-15T14:30:00Z", "updated_at": "2024-01-15T14:30:00Z" } ``` ### Customer deposits cash When the customer visits a retail location: 1. **Customer presents barcode**: The customer shows the barcode (on their phone or printed) to the cashier at a participating Green Dot retail location. 2. **Cashier scans barcode**: The cashier scans the barcode at the point of sale terminal and the customer provides the cash amount they want to deposit. 3. **Retailer collects a fee**: The retailer collects a fee from the customer (typically $3-$5, varies by location) in addition to the deposit amount. 4. **Green Dot processes the transaction**: Green Dot processes the transaction and sends an authorization request to Treasury Prime with the deposit amount. ### Authorization and settlement When Treasury Prime receives the authorization request: 1. **Treasury Prime validates limits**: The system checks the deposit amount against configured transaction minimums, daily limits, monthly limits, and total program limits. 2. **Treasury Prime authorizes the deposit**: If all validations pass, the deposit status changes to `authorized` and a `greendot.update` webhook event fires. 3. **Funds become available**: The deposit status changes to `available` when funds are ready for the customer to use. Another `greendot.update` webhook event fires. 4. **Settlement completes**: The deposit status changes to `complete` when fully settled. A final `greendot.update` webhook event fires. ## Finding retail locations Treasury Prime provides a location finder API to help customers find nearby participating Green Dot retail locations. The [`GET /greendot/location`](/reference/get_greendot_location) endpoint returns a list of retailers based on either zip code or GPS coordinates. Each location result includes the retailer name, address, phone number, customer fee, and the retailer key needed for barcode generation. The fee varies by location, typically ranging from $3 to $5 per transaction. You can search by zip code for a broader area search, or use latitude and longitude coordinates for precise location-based results. The API requires the customer's IP address for security and fraud prevention purposes. ##### Example request to find retail locations ```bash bash theme={null} curl -X GET \ -u $API_KEY_ID:$API_SECRET_KEY \ 'https://api.treasuryprime.com/greendot/location?zip_code=55025&ip_address=192.168.1.100' ``` ##### Example response ```bash bash theme={null} { "data": [ { "retailer_name": "Walmart Supercenter", "retailer_key": "2812", "address": "200 12th St SW", "city": "Forest Lake", "state": "MN", "zip_code": "55025", "phone": "6514649740", "customer_fee": "3.74", "latitude": "45.27678600", "longitude": "-93.00201300", "store_id": "Walmart Supercenter2274" } ] } ``` ## Deposit limits and timing Green Dot cash deposits support configurable limits at both the organization level and individual account level. Treasury Prime enforces these limits during the authorization phase to manage risk and prevent fraud. ### Limit types **Transaction minimum**: The smallest amount allowed for a single deposit. Deposits below this amount are rejected during authorization. **Transaction limit**: The maximum amount allowed for a single deposit. This limit is enforced during authorization when the customer completes the transaction at the retail location. **Daily limit**: The maximum total amount that can be deposited to an account since midnight Pacific Time at the start of the current business day. On weekends and holidays, the window rolls back to midnight of the previous business day. Includes authorized, available, and completed deposits. **Monthly limit**: The maximum total amount that can be deposited to an account within a calendar month (calculated in Pacific Time). **Total program limit**: The maximum total amount that can be outstanding across all accounts in your program. This represents the float amount and includes only authorized and available deposits (not completed). This limit can only be set at the organization level and cannot be configured per account. Account-level limits override organization-level limits when configured for transaction minimum, transaction limit, daily limit, and monthly limit. This allows you to set tighter controls for specific accounts while maintaining default limits for the broader program. ### Timing and availability **Barcode expiration**: Green Dot determines the barcode expiration time when generating the barcode, typically around 1 hour after creation. Customers must complete the transaction at the retail location before expiration. **Authorization timing**: Authorization typically occurs within seconds of the customer completing the transaction at the retail location. **Funds availability**: Funds generally become available within minutes of authorization, though timing may vary based on Green Dot processing. **Settlement timing**: Final settlement typically completes within 1-2 business days, though the funds are available to the customer much sooner. **Time zone**: All limit calculations use Pacific Time (America/Los\_Angeles) to align with Green Dot's systems. ## Deposit statuses Green Dot deposits progress through several statuses during their lifecycle: | Status | Description | | - | - | | **pending** | Barcode has been generated but customer has not yet completed the transaction at the retail location | | **authorized** | Customer completed the transaction and Green Dot has authorized the deposit | | **available** | Funds are available in the customer's account for use | | **complete** | Deposit has fully settled | | **voided** | Deposit was cancelled or rejected during authorization | | **expired** | Barcode expired before the customer completed the transaction | ## Additional key points about Green Dot cash deposits * **One barcode per account**: Only one barcode can be valid at a time per account. Generating a new barcode automatically invalidates any previous unused barcode for that account. * **Barcode validity**: Green Dot sets the barcode expiration time (typically around 1 hour from generation) and each barcode can only be used once. Expired barcodes cannot be reused. * **Retailer fees**: The retail location collects a fee from the customer at the point of sale, typically $3-$5 depending on the location. This fee is separate from the deposit amount. * **Required parameters**: Barcode generation requires account ID, retailer key, channel type, device type, latitude, longitude, IP address, and verified email address. * **Geolocation tracking**: Customer device location (latitude/longitude) is required for fraud prevention and security purposes. This helps Green Dot verify the transaction is legitimate. * **Email verification**: The email address provided must be verified and belong to the account holder. Green Dot uses this for transaction receipts and notifications. * **Webhook events**: Green Dot deposits trigger `greendot.create` when the barcode is generated and `greendot.update` when the status changes (authorized, available, complete, voided, expired). * **Error handling**: The API returns specific error codes for various failure scenarios including velocity limits exceeded, load limits exceeded, invalid parameters, and Green Dot system errors. * **Metadata**: Green Dot provides additional metadata when deposits are authorized, including transaction details and retailer information. * **No amount specification**: The deposit amount cannot be specified when generating the barcode. The customer determines the amount when they visit the retail location. * **No chargebacks**: There is no traditional dispute or chargeback process for cash deposits. Once funds are committed to the account, the transaction is final. * **Void transaction mechanics**: When a deposit is voided after authorization, it creates four transactions that net to zero: a credit to the transit account, a debit from the customer account, a hold release, and the original reversal. All transactions share the same `greendot_deposit_id` as their trace ID. * **Account requirements**: The account must be open and in good standing. Closed or locked accounts cannot receive Green Dot deposits. ## Important considerations 1. **Bank partner approval required**: Green Dot availability varies by bank partner. You must work with your partnered bank and Treasury Prime Relationship Manager to enable this feature. 2. **Configuration setup needed**: Your organization must have Green Dot deposit configuration established, including program number, secret credentials, and limit settings before generating barcodes. 3. **Limit enforcement is strict**: Treasury Prime enforces all configured limits during authorization. Deposits exceeding any limit are automatically voided with an error message. 4. **Barcodes expire**: Green Dot sets barcode expiration times (typically around 1 hour). Customers must complete transactions before expiration. Consider this timing in your user experience design. 5. **Fees are customer-paid**: The retail location collects fees directly from customers at the point of sale. These fees are not controlled by Treasury Prime or your program. 6. **Geolocation is mandatory**: You must collect and provide accurate device location coordinates. This is a Green Dot requirement for fraud prevention. 7. **IP address tracking**: The customer's IP address must be provided for both barcode generation and location searches for security purposes. 8. **Velocity limits exist**: Green Dot enforces velocity limits on barcode generation to prevent abuse. Excessive barcode creation attempts may be rejected. 9. **System errors can occur**: Green Dot's systems may occasionally experience issues. The API returns a 503 error when Green Dot is unavailable, and you should implement retry logic. 10. **Status transitions are automatic**: You cannot manually change deposit statuses. All status changes are driven by Green Dot's processing and Treasury Prime's authorization logic. 11. **Total program limit is organization-wide**: Unlike other limits, the total program limit cannot be set per account. It applies across all accounts in your organization and represents the maximum float amount. *** For detailed API endpoint documentation, parameter specifications, and response schemas, see the [Green Dot API Reference](/reference/greendot). # Overview Source: https://docs.treasuryprime.com/docs/incoming-ach ACH transfers originated outside of the Treasury Prime platform are referred to as “incoming” or “externally originated” ACH transfers as they are originated by a third party. We support the acceptance of both ACH credits and debits to accounts on the Treasury Prime platform and can manage both standard and sameday levels of service. ## Managing Incoming ACH Transfers For incoming ACH transfers originated by third parties, an associated [ACH object](/reference/ach) is not created. Instead, an [Incoming ACH object](/reference/incoming-ach) is created for ledger accounts, and the resulting funds movement posts to the recipient's account as a [Transaction](/reference/get_transaction). For information on returning incoming ACH transfers, see the [Returning Incoming ACH](/docs/returning-incoming-ach) guide. ## Example: Incoming ACH Credit In this example, a third party sends an ACH credit for \$100 from their account at Capital One to an account on the Treasury Prime platform. The basic flow is as follows: 1. The ACH originates at Capital One, the Originating Depository Financial Institution (ODFI) 2. The ACH is processed through the ACH network 3. The ACH is then received by the Treasury Prime partner bank, the Receiving Depository Financial Institution (RDFI) 4. Lastly, the ACH posts to the recipient's account as a `deposit` transaction Below you can see the transaction created from that incoming ACH credit. Note that the `type` field of the transaction object has a value of `deposit` as this is a credit to the account. For ACH debits, this would have a value of `withdrawal`. ##### Example Transaction Object Corresponding to the Incoming ACH Credit ```bash bash theme={null} { "ach_id": null, "amount": "100.00", "balance": "150.00", "billpay_payment_id": null, "book_id": null, "check_id": null, "check_number": null, "date": "2021-11-21", "desc": "INCOMING ACH CREDIT CAPITAL ONE [091000011234567][PPD]", "extended_timestamp": "2021-11-21T11:45:16Z", "extended_timestamp_precise": "2021-11-21T11:45:16.321Z", "fingerprint": "ttx_11gyn76cj1234b", "id": "ttx_11gyn76cj1234b", "incoming_wire": null, "issued_check_id": null, "summary": null, "trace_id": null, "type": "deposit", "type_source": null, "wire": null, "wire_id": null } ``` ## Example: Incoming ACH Debit In this example, a third party sends an ACH debit requesting \$100 from an account on the Treasury Prime platform to their account at Capital One. 1. The ACH originates at the ODFI (Capital One) 2. The ACH is then processed through the ACH network 3. The ACH is received by the RDFI 4. Lastly, the ACH posts to the recipient's account as a `withdrawal` [transaction](/reference/get_transaction) (shown below) ##### Example Transaction Object Corresponding to the Incoming ACH Debit ```bash bash theme={null} { "ach_id": null, "amount": "-100.00", "balance": "200.00", "billpay_payment_id": null, "book_id": null, "check_id": null, "check_number": null, "date": "2021-07-20", "desc": "INCOMING ACH DEBIT CAPITAL ONE [09100001122233][POS]", "extended_timestamp": "2021-07-20T11:45:13Z", "extended_timestamp_precise": "2021-07-20T11:45:13.794Z", "fingerprint": "ttx_11gyjjt9j1234a", "id": "ttx_11gyjjt9j1234a", "incoming_wire": null, "issued_check_id": null, "summary": null, "trace_id": null, "type": "withdrawal", "type_source": null, "wire": null, "wire_id": null } ``` ## Webhooks for Incoming ACH Transfers ### Webhooks for Incoming ACHs with Ledger Account Recipient Incoming ACHs landing at ledger accounts will trigger the `incoming_ach.create` [webhook](/reference/webhook) which fires when new incoming ACH objects are created. ##### Example `incoming_ach.create` Webhook Notification ```bash bash theme={null} { "event": "incoming_ach.create", "op": "create", "url": "https://api.treasuryprime.com/incoming_ach/inach_1234567890abcde", "id": "inach_1234567890abcde" } ``` Please note that this webhook will only work with ledger accounts. For webhooks on inbound ACHs against core accounts, see below. ### Webhooks for Incoming ACHs with Core Account Recipient A successful incoming ACH transfer results in a new transaction on the recipient's account. Knowing this, you can monitor incoming ACH transfers by subscribing to the `account.update` [webhook](/reference/webhook), which fires any time a new transaction is created on an account. ##### Example `account.update` Webhook Notification ```bash bash theme={null} { "event": "account.update", "op": "update", "url": "https://api.treasuryprime.com/account/acct_11her5nvc012ab", "id": "acct_11her5nvc012ab" } ``` A second webhook `transaction.create` may also be used to receive updates when new transactions are created; however, this webhook (and the associated [Transaction object](/reference/get_transaction)) do not contain any information to identify the account that the transaction belongs to. So this will likely be most useful in circumstances where you are interested in identifying all new transactions as they are created, but do not need to know the account to which that transaction belongs. ##### Example `transaction.create` Webhook Notification ```bash bash theme={null} { "event": "transaction.create", "op": "create", "url": "https://api.treasuryprime.com/transaction/ttx_11hqfx7xejabcd", "id": "ttx_11hqfx7xejabcd" } ``` ## Identifying Incoming ACH Transfers As outlined above, a successful incoming ACH transfer will result in a transaction being on the recipient's account. However, other funds movements (such as book transfers, and wires) also result in the same outcome. To identify which transactions occurred as a result of an incoming ACH we can look at the `desc` field of the Transaction object. As shown below, this field will usually contain a value starting with “INCOMING ACH” followed by the direction of the ACH (credit or debit) and the original description included with the ACH if available. ##### Example `desc` Value for an Inbound ACH Credit ```bash bash theme={null} "desc": "INCOMING ACH CREDIT PAYPAL [091000015555123][PPD]" ``` ##### Example `desc` Value for an Inbound ACH Debit ```bash bash theme={null} "desc": "INCOMING ACH DEBIT TARGET DEBIT CRD [09100001122233][POS]" ``` # Invoice Account Numbers Source: https://docs.treasuryprime.com/docs/invoice-account-numbers Use multiple account numbers to receive payments into a single ledger account Invoice Account Numbers enable you to allocate additional account numbers to an existing ledger account, allowing you to receive payments through multiple account numbers while maintaining a single destination for funds. This feature is particularly useful for businesses that need to track payments from different sources or associate specific account numbers with different invoices, departments, or partners. These can also be thought of as *virtual account numbers*. Invoice Account Number availability varies by bank partner and requires bank approval. Contact your relationship manager to discuss availability and any associated costs. ## What are Invoice Account Numbers? Invoice Account Numbers are additional routing endpoints for an existing ledger account. They are not separate accounts but rather alternative account numbers that all route payments to the same underlying ledger account. When payments are sent to any of these invoice account numbers, they are automatically posted to the associated bank account and include the invoice account number for easy tracking. For API reference documentation and endpoints, see [Invoice Account Number API Reference](/reference/invoice-account-number). ## Key Benefits 1. **Simplified Payment Tracking**: Use different account numbers to track payments from various sources without managing multiple accounts 2. **Invoice Based Collections**: Assign unique account numbers to specific invoices for easy reconciliation 3. **No Payment Limits**: There are no restrictions on payment size or frequency except those set by the underlying account. 4. **Unified Account Management**: All funds arrive in a single account, simplifying balance management and reporting ## How Invoice Numbers Work Incoming ACHs and wires received for the invoice account number will be posted to the associated ledger account. These payments will be posted to the ledger account just as if they were a payment to the account number on the ledger account. The account number for the ACH/wire will continue to be surfaced on the [`/incoming_ach`](/reference/incoming-ach) and [`/incoming_wire`](/reference/incoming-wire) endpoints which will allow customers to make the connection to the invoice account number. Transaction descriptions behave the same regardless of whether an incoming payment posts to the primary account number or an invoice account number.