feat(api): api update

.stats.yml

@@ -1,3 +1,3 @@
 configured_endpoints: 255
-openapi_spec_hash: de4578cd6e5125791bb32e1a25c9c5ac
+openapi_spec_hash: 31dbb51b621eeb3886e4e430fe825146
 config_hash: de151ebd21a0bd391662389b310a8f49

api.md

@@ -892,7 +892,7 @@ Methods:
 
 Methods:
 
-- <code title="post /simulations/wire_drawdown_requests/{wire_drawdown_request_id}/refuse">client.simulations.wireDrawdownRequests.<a href="./src/resources/simulations/wire-drawdown-requests.ts">refuse</a>(wireDrawdownRequestID) -> WireDrawdownRequest</code>
+- <code title="post /simulations/wire_drawdown_requests/{wire_drawdown_request_id}/refuse">client.simulations.wireDrawdownRequests.<a href="./src/resources/simulations/wire-drawdown-requests.ts">refuse</a>(wireDrawdownRequestID, { ...params }) -> WireDrawdownRequest</code>
 - <code title="post /simulations/wire_drawdown_requests/{wire_drawdown_request_id}/submit">client.simulations.wireDrawdownRequests.<a href="./src/resources/simulations/wire-drawdown-requests.ts">submit</a>(wireDrawdownRequestID) -> WireDrawdownRequest</code>
 
 ## InboundWireDrawdownRequests

src/resources/ach-transfers.ts

@@ -8,14 +8,19 @@ import { path } from '../internal/utils/path';
 
 export class ACHTransfers extends APIResource {
   /**
-   * Create an ACH Transfer
+   * An ACH Transfer has two primary descriptive fields:
+   * [`company_name`](/documentation/api/ach-transfers#create-an-ach-transfer.company_name)
+   * and
+   * [`individual_name`](/documentation/api/ach-transfers#create-an-ach-transfer.individual_name).
+   * You should set both of these, in addition to the required amount and account
+   * fields.
    *
    * @example
    * ```ts
    * const achTransfer = await client.achTransfers.create({
    *   account_id: 'account_in71c4amph0vgo2qllky',
    *   amount: 100,
-   *   statement_descriptor: 'New ACH transfer',
+   *   statement_descriptor: 'INVOICE 2468',
    * });
    * ```
    */
@@ -1080,14 +1085,19 @@ export namespace ACHTransfer {
 
 export interface ACHTransferCreateParams {
   /**
-   * The Increase identifier for the account that will send the transfer.
+   * The Increase identifier for the account that will originate the transfer. For
+   * credit transfers (transfers with a positive `amount`), this is the account that
+   * funds will be sent from. For debit transfers (transfers with a negative
+   * `amount`), this is the account that funds will be pulled into.
    */
   account_id: string;
 
   /**
    * The transfer amount in USD cents. A positive amount originates a credit transfer
-   * pushing funds to the receiving account. A negative amount originates a debit
-   * transfer pulling funds from the receiving account.
+   * pushing funds from Increase to the account at the other bank. A negative amount
+   * originates a debit transfer pulling funds from the account at the other bank
+   * into Increase. Debit transfers
+   * [might result in a hold before funds are available](/documentation/sending-ach-debit-transfers).
    */
   amount: number;
 
@@ -1102,9 +1112,10 @@ export interface ACHTransferCreateParams {
   statement_descriptor: string;
 
   /**
-   * The receiver's account number. For credit transfers (positive `amount`) this is
-   * the account that funds will be sent to. For debit transfers (negative `amount`)
-   * this is the account that funds will be pulled from.
+   * The receiver's account number. For credit transfers (transfers with a positive
+   * `amount`), this is the account that funds will be sent to. For debit transfers
+   * (transfers with a negative `amount`), this is the account that funds will be
+   * pulled from.
    */
   account_number?: string;
 
@@ -1124,25 +1135,30 @@ export interface ACHTransferCreateParams {
   company_descriptive_date?: string;
 
   /**
-   * Custom data sent in the company batch header. This value is informational and
-   * does not affect funds movement, settlement timing, or returns. Most ACH
-   * transfers do not need this. Only set this if your recipient has asked for it.
+   * Custom data sent in the company batch header, meant as metadata for the
+   * originator. This value is informational and does not affect funds movement,
+   * settlement timing, or returns. Most ACH transfers do not need this; we recommend
+   * storing metadata in your own application instead.
    */
   company_discretionary_data?: string;
 
   /**
-   * A short description sent in the company batch header. Most receivers do not
-   * surface this. Only set this if your recipient has asked for a specific value or
-   * if Nacha mandates one for your Standard Entry Class (SEC) code and use case. For
-   * example, Prearranged Payment and Deposit (PPD) payroll credits must use
-   * `PAYROLL`, and reversals must use `REVERSAL`.
+   * A short description sent in the company batch header, meant to provide the
+   * receiver with a reason for the transfer. Many receivers do not surface this data
+   * on the receiver's bank statement. Only set this if your recipient has asked for
+   * a specific value or if Nacha mandates one for your Standard Entry Class (SEC)
+   * code and use case. For example, some use cases require constants like
+   * `ACCTVERIFY`, `PURCHASE`, `PAYROLL`, or `REVERSAL`.
    */
   company_entry_description?: string;
 
   /**
-   * The name by which the recipient knows you, sent in the company batch header. We
-   * recommend setting this on every transfer; if you do not, we fall back to the
-   * `statement_descriptor`.
+   * The name by which the recipient knows the counterparty of this transaction. If
+   * you're processing payments on behalf of another party, use their name, not your
+   * own, so that it's more likely the recipient understands the context of the
+   * payment. This value is usually displayed to the recipient on their bank
+   * statement. We recommend setting this on every transfer; if you do not, we fall
+   * back to the `statement_descriptor`.
    */
   company_name?: string;
 
@@ -1172,14 +1188,18 @@ export interface ACHTransferCreateParams {
   funding?: 'checking' | 'savings' | 'loan' | 'general_ledger';
 
   /**
-   * Your internal identifier for the transfer recipient. This value is informational
-   * and not verified by the recipient's bank. Most callers can leave this unset.
+   * Your internal identifier for the recipient. This value is informational and
+   * generally not verified by the recipient's bank. Most callers can leave this
+   * unset. For the specific case of person-to-person credits with the WEB standard
+   * entry class code, this must include the name of the payer.
    */
   individual_id?: string;
 
   /**
-   * The name of the transfer recipient. This value is informational and not verified
-   * by the recipient's bank.
+   * The name of the transfer recipient. This value is informational and generally
+   * not verified by the recipient's bank. This value is usually displayed to the
+   * recipient on their bank statement. We recommend setting this on every transfer;
+   * if you do not, we fall back to the `statement_descriptor`.
    */
   individual_name?: string;
 

src/resources/simulations/account-revenue-payments.ts

@@ -15,7 +15,7 @@ export class AccountRevenuePayments extends APIResource {
    * const transaction =
    *   await client.simulations.accountRevenuePayments.create({
    *     account_id: 'account_in71c4amph0vgo2qllky',
-   *     amount: 1000,
+   *     amount: 100,
    *   });
    * ```
    */

src/resources/simulations/card-disputes.ts

@@ -59,17 +59,20 @@ export namespace CardDisputeActionParams {
      *
      * - `accept_chargeback` - Simulate the merchant accepting the chargeback. This
      *   will move the dispute to a `won` state.
+     * - `accept_user_prearbitration` - Simulate the merchant accepting the user's
+     *   pre-arbitration. This will move the dispute to a `won` state.
      * - `accept_user_submission` - Accept the user's submission and transmit it to the
      *   network. This will move the dispute to a `pending_response` state.
      * - `decline_user_prearbitration` - Simulate the merchant declining the user's
      *   pre-arbitration. This will move the dispute to a `lost` state.
      * - `receive_merchant_prearbitration` - Simulate the merchant issuing
-     *   pre-arbitration. This will move the dispute to a `user_submission_required`
-     *   state.
+     *   pre-arbitration. Only available for disputes in the fraud or authorization
+     *   category. This will move the dispute to a `user_submission_required` state.
      * - `reject` - Simulate the dispute being rejected before it is submitted to the
      *   network. This will move the dispute to a `rejected` state.
-     * - `represent` - Simulate the merchant re-presenting the dispute. This will move
-     *   the dispute to a `user_submission_required` state.
+     * - `represent` - Simulate the merchant re-presenting the dispute. Only available
+     *   for disputes in a consumer or processing error category. This will move the
+     *   dispute to a `user_submission_required` state.
      * - `request_further_information` - Simulate further information being requested
      *   from the user. This will move the dispute to a `user_submission_required`
      *   state.
@@ -80,10 +83,11 @@ export namespace CardDisputeActionParams {
      * - `time_out_representment` - Simulate the user timing out responding to a
      *   merchant re-presentment. This will move the dispute to a `lost` state.
      * - `time_out_user_prearbitration` - Simulate the merchant timing out responding
-     *   to a user pre-arbitration. This will move the dispute to a `win` state.
+     *   to a user pre-arbitration. This will move the dispute to a `won` state.
      */
     action:
       | 'accept_chargeback'
+      | 'accept_user_prearbitration'
       | 'accept_user_submission'
       | 'decline_user_prearbitration'
       | 'receive_merchant_prearbitration'
@@ -101,6 +105,12 @@ export namespace CardDisputeActionParams {
      */
     accept_chargeback?: Visa.AcceptChargeback;
 
+    /**
+     * The parameters for accepting the user prearbitration. Required if and only if
+     * `action` is `accept_user_prearbitration`.
+     */
+    accept_user_prearbitration?: Visa.AcceptUserPrearbitration;
+
     /**
      * The parameters for accepting the user submission. Required if and only if
      * `action` is `accept_user_submission`.
@@ -169,6 +179,12 @@ export namespace CardDisputeActionParams {
      */
     export interface AcceptChargeback {}
 
+    /**
+     * The parameters for accepting the user prearbitration. Required if and only if
+     * `action` is `accept_user_prearbitration`.
+     */
+    export interface AcceptUserPrearbitration {}
+
     /**
      * The parameters for accepting the user submission. Required if and only if
      * `action` is `accept_user_submission`.

src/resources/simulations/index.ts

@@ -79,5 +79,5 @@ export {
   type RealTimePaymentsTransferCompleteParams,
 } from './real-time-payments-transfers';
 export { Simulations } from './simulations';
-export { WireDrawdownRequests } from './wire-drawdown-requests';
+export { WireDrawdownRequests, type WireDrawdownRequestRefuseParams } from './wire-drawdown-requests';
 export { WireTransfers } from './wire-transfers';

src/resources/simulations/interest-payments.ts

@@ -15,7 +15,7 @@ export class InterestPayments extends APIResource {
    * const transaction =
    *   await client.simulations.interestPayments.create({
    *     account_id: 'account_in71c4amph0vgo2qllky',
-   *     amount: 1000,
+   *     amount: 100,
    *   });
    * ```
    */

src/resources/simulations/simulations.ts

@@ -103,7 +103,7 @@ import {
   RealTimePaymentsTransfers,
 } from './real-time-payments-transfers';
 import * as WireDrawdownRequestsAPI from './wire-drawdown-requests';
-import { WireDrawdownRequests } from './wire-drawdown-requests';
+import { WireDrawdownRequestRefuseParams, WireDrawdownRequests } from './wire-drawdown-requests';
 import * as WireTransfersAPI from './wire-transfers';
 import { WireTransfers } from './wire-transfers';
 
@@ -297,7 +297,10 @@ export declare namespace Simulations {
     type InboundWireTransferCreateParams as InboundWireTransferCreateParams,
   };
 
-  export { WireDrawdownRequests as WireDrawdownRequests };
+  export {
+    WireDrawdownRequests as WireDrawdownRequests,
+    type WireDrawdownRequestRefuseParams as WireDrawdownRequestRefuseParams,
+  };
 
   export {
     InboundWireDrawdownRequests as InboundWireDrawdownRequests,

src/resources/simulations/wire-drawdown-requests.ts

@@ -20,12 +20,13 @@ export class WireDrawdownRequests extends APIResource {
    */
   refuse(
     wireDrawdownRequestID: string,
+    body: WireDrawdownRequestRefuseParams,
     options?: RequestOptions,
   ): APIPromise<WireDrawdownRequestsAPI.WireDrawdownRequest> {
-    return this._client.post(
-      path`/simulations/wire_drawdown_requests/${wireDrawdownRequestID}/refuse`,
-      options,
-    );
+    return this._client.post(path`/simulations/wire_drawdown_requests/${wireDrawdownRequestID}/refuse`, {
+      body,
+      ...options,
+    });
   }
 
   /**
@@ -49,3 +50,37 @@ export class WireDrawdownRequests extends APIResource {
     );
   }
 }
+
+export interface WireDrawdownRequestRefuseParams {
+  /**
+   * Additional information about the refusal that the simulated refusal will have.
+   */
+  refusal_reason_additional_information?: string;
+
+  /**
+   * The reason code that the simulated refusal will have.
+   *
+   * - `invalid_debtor_account_number` - The debtor's account number is invalid or
+   *   missing. Corresponds to the Fedwire reason code `AC02`.
+   * - `transaction_forbidden` - The debtor account does not allow drawdown requests.
+   *   Corresponds to the Fedwire reason code `AG01`.
+   * - `unsuccessful_direct_debit` - The debtor account cannot be debited for a
+   *   generic reason. Corresponds to the Fedwire reason code `AG07`.
+   * - `inconsistent_with_end_customer` - The debtor's identification is inconsistent
+   *   with the debtor account number. Corresponds to the Fedwire reason code `BE01`.
+   * - `narrative` - The reason is provided as narrative information in the
+   *   additional information field. Corresponds to the Fedwire reason code `NARR`.
+   * - `other` - Some other error or issue has occurred.
+   */
+  refusal_reason_code?:
+    | 'invalid_debtor_account_number'
+    | 'transaction_forbidden'
+    | 'unsuccessful_direct_debit'
+    | 'inconsistent_with_end_customer'
+    | 'narrative'
+    | 'other';
+}
+
+export declare namespace WireDrawdownRequests {
+  export { type WireDrawdownRequestRefuseParams as WireDrawdownRequestRefuseParams };
+}

src/resources/wire-drawdown-requests.ts

@@ -173,6 +173,12 @@ export interface WireDrawdownRequest {
    */
   idempotency_key: string | null;
 
+  /**
+   * If the debtor refuses the drawdown request, this will contain supplemental
+   * details.
+   */
+  refusal: WireDrawdownRequest.Refusal | null;
+
   /**
    * The lifecycle status of the drawdown request.
    *
@@ -287,6 +293,47 @@ export namespace WireDrawdownRequest {
     state: string | null;
   }
 
+  /**
+   * If the debtor refuses the drawdown request, this will contain supplemental
+   * details.
+   */
+  export interface Refusal {
+    /**
+     * Additional information about the refusal provided by the debtor bank. This is
+     * typically present when the `refusal_reason_code` is `narrative`.
+     */
+    refusal_reason_additional_information: string | null;
+
+    /**
+     * The reason the wire drawdown request was refused as provided by the debtor bank.
+     *
+     * - `invalid_debtor_account_number` - The debtor's account number is invalid or
+     *   missing. Corresponds to the Fedwire reason code `AC02`.
+     * - `transaction_forbidden` - The debtor account does not allow drawdown requests.
+     *   Corresponds to the Fedwire reason code `AG01`.
+     * - `unsuccessful_direct_debit` - The debtor account cannot be debited for a
+     *   generic reason. Corresponds to the Fedwire reason code `AG07`.
+     * - `inconsistent_with_end_customer` - The debtor's identification is inconsistent
+     *   with the debtor account number. Corresponds to the Fedwire reason code `BE01`.
+     * - `narrative` - The reason is provided as narrative information in the
+     *   additional information field. Corresponds to the Fedwire reason code `NARR`.
+     * - `other` - Some other error or issue has occurred.
+     */
+    refusal_reason_code:
+      | 'invalid_debtor_account_number'
+      | 'transaction_forbidden'
+      | 'unsuccessful_direct_debit'
+      | 'inconsistent_with_end_customer'
+      | 'narrative'
+      | 'other';
+
+    /**
+     * The [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date and time at which
+     * the wire drawdown request was refused.
+     */
+    refused_at: string;
+  }
+
   /**
    * After the drawdown request is submitted to Fedwire, this will contain
    * supplemental details.

tests/api-resources/ach-transfers.test.ts

@@ -12,7 +12,7 @@ describe('resource achTransfers', () => {
     const responsePromise = client.achTransfers.create({
       account_id: 'account_in71c4amph0vgo2qllky',
       amount: 100,
-      statement_descriptor: 'New ACH transfer',
+      statement_descriptor: 'INVOICE 2468',
     });
     const rawResponse = await responsePromise.asResponse();
     expect(rawResponse).toBeInstanceOf(Response);
@@ -27,7 +27,7 @@ describe('resource achTransfers', () => {
     await client.achTransfers.create({
       account_id: 'account_in71c4amph0vgo2qllky',
       amount: 100,
-      statement_descriptor: 'New ACH transfer',
+      statement_descriptor: 'INVOICE 2468',
       account_number: '987654321',
       addenda: {
         category: 'freeform',
@@ -37,12 +37,12 @@ describe('resource achTransfers', () => {
       company_descriptive_date: 'J!',
       company_discretionary_data: 'J!',
       company_entry_description: 'J!',
-      company_name: 'company_name',
+      company_name: 'Phonographs Inc',
       destination_account_holder: 'business',
       external_account_id: 'external_account_id',
       funding: 'checking',
       individual_id: 'individual_id',
-      individual_name: 'individual_name',
+      individual_name: 'Ian Crease',
       preferred_effective_date: { date: '2019-12-27', settlement_schedule: 'same_day' },
       require_approval: true,
       routing_number: '101050001',