// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.

import { APIResource } from '../../core/resource';
import * as CardPaymentsAPI from '../card-payments';
import { APIPromise } from '../../core/api-promise';
import { RequestOptions } from '../../internal/request-options';

export class CardBalanceInquiries extends APIResource {
  /**
   * Simulates a balance inquiry on a [Card](#cards).
   *
   * @example
   * ```ts
   * const cardPayment =
   *   await client.simulations.cardBalanceInquiries.create();
   * ```
   */
  create(
    body: CardBalanceInquiryCreateParams,
    options?: RequestOptions,
  ): APIPromise<CardPaymentsAPI.CardPayment> {
    return this._client.post('/simulations/card_balance_inquiries', { body, ...options });
  }
}

export interface CardBalanceInquiryCreateParams {
  /**
   * The balance amount in cents. The account balance will be used if not provided.
   */
  balance?: number;

  /**
   * The identifier of the Card to be authorized.
   */
  card_id?: string;

  /**
   * Forces a card decline with a specific reason. No real time decision will be
   * sent.
   *
   * - `account_closed` - The account has been closed.
   * - `card_not_active` - The Card was not active.
   * - `card_canceled` - The Card has been canceled.
   * - `physical_card_not_active` - The Physical Card was not active.
   * - `entity_not_active` - The account's entity was not active.
   * - `group_locked` - The account was inactive.
   * - `insufficient_funds` - The Card's Account did not have a sufficient available
   *   balance.
   * - `cvv2_mismatch` - The given CVV2 did not match the card's value.
   * - `pin_mismatch` - The given PIN did not match the card's value.
   * - `card_expiration_mismatch` - The given expiration date did not match the
   *   card's value. Only applies when a CVV2 is present.
   * - `transaction_not_allowed` - The attempted card transaction is not allowed per
   *   Increase's terms.
   * - `breaches_limit` - The transaction was blocked by a limit or an authorization
   *   control.
   * - `webhook_declined` - Your application declined the transaction via webhook.
   * - `webhook_timed_out` - Your application webhook did not respond without the
   *   required timeout.
   * - `declined_by_stand_in_processing` - Declined by stand-in processing.
   * - `invalid_physical_card` - The card read had an invalid CVV or dCVV.
   * - `missing_original_authorization` - The original card authorization for this
   *   incremental authorization does not exist.
   * - `invalid_cryptogram` - The card's authorization request cryptogram was
   *   invalid. The cryptogram can be from a physical card or a Digital Wallet Token
   *   purchase.
   * - `failed_3ds_authentication` - The transaction was declined because the 3DS
   *   authentication failed.
   * - `suspected_card_testing` - The transaction was suspected to be used by a card
   *   tester to test for valid card numbers.
   * - `suspected_fraud` - The transaction was suspected to be fraudulent. Please
   *   reach out to support@increase.com for more information.
   */
  decline_reason?:
    | 'account_closed'
    | 'card_not_active'
    | 'card_canceled'
    | 'physical_card_not_active'
    | 'entity_not_active'
    | 'group_locked'
    | 'insufficient_funds'
    | 'cvv2_mismatch'
    | 'pin_mismatch'
    | 'card_expiration_mismatch'
    | 'transaction_not_allowed'
    | 'breaches_limit'
    | 'webhook_declined'
    | 'webhook_timed_out'
    | 'declined_by_stand_in_processing'
    | 'invalid_physical_card'
    | 'missing_original_authorization'
    | 'invalid_cryptogram'
    | 'failed_3ds_authentication'
    | 'suspected_card_testing'
    | 'suspected_fraud';

  /**
   * The identifier of the Digital Wallet Token to be authorized.
   */
  digital_wallet_token_id?: string;

  /**
   * The identifier of the Event Subscription to use. If provided, will override the
   * default real time event subscription. Because you can only create one real time
   * decision event subscription, you can use this field to route events to any
   * specified event subscription for testing purposes.
   */
  event_subscription_id?: string;

  /**
   * The merchant identifier (commonly abbreviated as MID) of the merchant the card
   * is transacting with.
   */
  merchant_acceptor_id?: string;

  /**
   * The Merchant Category Code (commonly abbreviated as MCC) of the merchant the
   * card is transacting with.
   */
  merchant_category_code?: string;

  /**
   * The city the merchant resides in.
   */
  merchant_city?: string;

  /**
   * The country the merchant resides in.
   */
  merchant_country?: string;

  /**
   * The merchant descriptor of the merchant the card is transacting with.
   */
  merchant_descriptor?: string;

  /**
   * The state the merchant resides in.
   */
  merchant_state?: string;

  /**
   * Fields specific to a given card network.
   */
  network_details?: CardBalanceInquiryCreateParams.NetworkDetails;

  /**
   * The risk score generated by the card network. For Visa this is the Visa Advanced
   * Authorization risk score, from 0 to 99, where 99 is the riskiest.
   */
  network_risk_score?: number;

  /**
   * The identifier of the Physical Card to be authorized.
   */
  physical_card_id?: string;

  /**
   * The terminal identifier (commonly abbreviated as TID) of the terminal the card
   * is transacting with.
   */
  terminal_id?: string;
}

export namespace CardBalanceInquiryCreateParams {
  /**
   * Fields specific to a given card network.
   */
  export interface NetworkDetails {
    /**
     * Fields specific to the Visa network.
     */
    visa: NetworkDetails.Visa;
  }

  export namespace NetworkDetails {
    /**
     * Fields specific to the Visa network.
     */
    export interface Visa {
      /**
       * The reason code for the stand-in processing.
       *
       * - `issuer_error` - Increase failed to process the authorization in a timely
       *   manner.
       * - `invalid_physical_card` - The physical card read had an invalid CVV or dCVV.
       * - `invalid_cryptogram` - The card's authorization request cryptogram was
       *   invalid. The cryptogram can be from a physical card or a Digital Wallet Token
       *   purchase.
       * - `invalid_cardholder_authentication_verification_value` - The 3DS cardholder
       *   authentication verification value was invalid.
       * - `internal_visa_error` - An internal Visa error occurred. Visa uses this reason
       *   code for certain expected occurrences as well, such as Application Transaction
       *   Counter (ATC) replays.
       * - `merchant_transaction_advisory_service_authentication_required` - The merchant
       *   has enabled Visa's Transaction Advisory Service and requires further
       *   authentication to perform the transaction. In practice this is often utilized
       *   at fuel pumps to tell the cardholder to see the cashier.
       * - `payment_fraud_disruption_acquirer_block` - The transaction was blocked by
       *   Visa's Payment Fraud Disruption service due to fraudulent Acquirer behavior,
       *   such as card testing.
       * - `other` - An unspecific reason for stand-in processing.
       */
      stand_in_processing_reason?:
        | 'issuer_error'
        | 'invalid_physical_card'
        | 'invalid_cryptogram'
        | 'invalid_cardholder_authentication_verification_value'
        | 'internal_visa_error'
        | 'merchant_transaction_advisory_service_authentication_required'
        | 'payment_fraud_disruption_acquirer_block'
        | 'other';
    }
  }
}

export declare namespace CardBalanceInquiries {
  export { type CardBalanceInquiryCreateParams as CardBalanceInquiryCreateParams };
}