Marqeta simulate API

openapi: 3.0.3
info:
  contact:
    email: support@marqeta.com
    name: Marqeta
  description: Marqeta's Core API endpoints, conveniently annotated to enable code generation (including SDKs), test cases, and documentation. Currently in beta.
  termsOfService: https://www.marqeta.com/api-terms
  title: Core accepted countries simulate API
  version: 3.0.39
servers:
- url: /v3
security:
- mqAppAndAccessToken: []
tags:
- name: simulate
paths:
  /simulate/authorization:
    post:
      operationId: postSimulateAuthorization
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/auth_request_model'
        required: false
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/simulation_response_model'
          description: Success
        '400':
          content: {}
          description: User input error/Bad request
        '500':
          content: {}
          description: Server error
      summary: Simulates an authorization
      tags:
      - simulate
  /simulate/authorization/advice:
    post:
      operationId: postSimulateAuthorizationAdvice
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/authorization_advice_model'
        required: false
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/simulation_response_model'
          description: Success
        '400':
          content: {}
          description: User input error/Bad request
        '404':
          content: {}
          description: Original transaction not found
        '500':
          content: {}
          description: Server error
      summary: Simulates an authorization advice transaction
      tags:
      - simulate
  /simulate/clearing:
    post:
      operationId: postSimulateClearing
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ClearingModel'
        required: false
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/simulation_response_model'
          description: Success
        '400':
          content: {}
          description: User input error/Bad request
        '404':
          content: {}
          description: Original transaction not found
        '500':
          content: {}
          description: Server error
      summary: Simulates a clearing/settlement transaction
      tags:
      - simulate
  /simulate/directdeposits:
    post:
      operationId: postSimulateDirectdeposits
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DirectDepositRequest'
        description: Direct deposit simulate request model
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DepositDepositResponse'
          description: Success
        '400':
          content: {}
          description: Bad request
        '500':
          content: {}
          description: Server error
      summary: Simulates the creation of direct deposit
      tags:
      - simulate
  /simulate/financial:
    post:
      operationId: postSimulateFinancial
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/financial_request_model'
        description: Financial request model
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/simulation_response_model'
          description: Success
        '400':
          content: {}
          description: User input error/Bad request
        '500':
          content: {}
          description: Server error
      summary: Simulates a financial request (PIN debit) transaction with optional cash back
      tags:
      - simulate
  /simulate/financial/advice:
    post:
      operationId: postSimulateFinancialAdvice
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/authorization_advice_model'
        description: Financial advice request model
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/simulation_response_model'
          description: Success
        '400':
          content: {}
          description: User input error/Bad request
        '404':
          content: {}
          description: Original transaction not found
        '500':
          content: {}
          description: Server error
      summary: Simulates a financial advice transaction
      tags:
      - simulate
  /simulate/financial/balanceinquiry:
    post:
      operationId: postSimulateFinancialBalanceinquiry
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/balance_inquiry_request_model'
        description: Balance inquiry request model
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/simulation_response_model'
          description: Success
        '400':
          content: {}
          description: User input error/Bad request
        '500':
          content: {}
          description: Server error
      summary: Simulates a balance inquiry
      tags:
      - simulate
  /simulate/financial/originalcredit:
    post:
      operationId: postSimulateFinancialOriginalcredit
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/orignalcredit_request_model'
        description: Orignal Credit request model
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/simulation_response_model'
          description: Success
        '400':
          content: {}
          description: User input error/Bad request
        '500':
          content: {}
          description: Server error
      summary: Simulates an orignal credit transaction
      tags:
      - simulate
  /simulate/financial/withdrawal:
    post:
      operationId: postSimulateFinancialWithdrawal
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/withdrawal_request_model'
        description: ATM withdrawal request model
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/simulation_response_model'
          description: Success
        '400':
          content: {}
          description: User input error/Bad request
        '500':
          content: {}
          description: Server error
      summary: Simulates an ATM withdrawal transaction
      tags:
      - simulate
  /simulate/reversal:
    post:
      operationId: postSimulateReversal
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReversalModel'
        required: false
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/simulation_response_model'
          description: Success
        '400':
          content: {}
          description: User input error/Bad request
        '404':
          content: {}
          description: Original transaction not found
        '500':
          content: {}
          description: Server error
      summary: Simulates a reversal transaction
      tags:
      - simulate
components:
  schemas:
    transaction_metadata:
      description: 'Contains merchant-provided metadata related to the transaction, including details about lodging- and transit-related purchases.


        May be returned if the request uses Transaction Model v2 of the Marqeta Core API.

        Not returned for Transaction Model v1 requests.'
      properties:
        airline:
          $ref: '#/components/schemas/airline'
        authorization_life_cycle:
          description: Number of days the pre-authorization is in effect.
          format: int32
          type: integer
        cross_border_transaction:
          default: false
          description: Whether the transaction is cross-border, i.e., when the merchant and the cardholder are located in two different countries.
          type: boolean
        is_deferred_authorization:
          description: Indicates an offline authorization made during an interruption of card network connectivity, such as a purchase on a flight.
          type: boolean
        is_lodging_auto_rental:
          default: false
          description: Whether the transaction is a lodging or vehicle rental.
          type: boolean
        lodging_auto_rental_start_date:
          description: Date and time when the lodging check-in or vehicle rental began.
          format: date-time
          type: string
        memo:
          description: Indicates a credit or debit adjustment in a clearing transaction.
          enum:
          - CREDIT_ADJUSTMENT
          - DEBIT_ADJUSTMENT
          maxLength: 99
          minLength: 1
          type: string
        moto_indicator:
          description: Indicates the type of mail or telephone order transaction.
          enum:
          - UNKNOWN
          - MANUAL
          - RECURRING
          - INSTALLMENT
          - OTHERS
          type: string
        one_leg_out:
          type: boolean
        payment_channel:
          description: Channel from which the transaction was originated.
          enum:
          - OTHER
          - ATM
          - ECOMMERCE
          - MAIL
          - PHONE
          - MOTO
          type: string
        special_purchase_id:
          type: string
        transaction_category:
          description: Type of product or service being purchased, if provided by the merchant.
          enum:
          - RETAIL_SALE
          - BILL_PAY
          - HOTEL
          - HEALTH_CARE
          - RESTAURANT
          - AUTO_RENTAL
          - AIRLINE
          - PAYMENT
          - HOSPITALIZATION_COLLEGE
          - PHONE_MAIL_ECOMMERCE
          - ATM
          - TRANSIT
          - EXTENDED_AUTHORIZATION
          type: string
        transit:
          $ref: '#/components/schemas/transit'
      type: object
    cardholder_verification:
      properties:
        result:
          description: Biometric verification result
          enum:
          - Pass
          - Fail
          - not present
          type: string
        verification_method:
          description: Cardholder verification method
          enum:
          - Biometric
          type: string
      type: object
    transaction_card_acceptor:
      description: Contains information about the merchant.
      properties:
        address:
          description: 'Card acceptor''s address.

            May be returned if the request uses Transaction Model v1 of the Marqeta Core API.

            Not returned for Transaction Model v2 requests.'
          type: string
        business_registration_id:
          description: Business registration identifier, as provided by the Visa card network.
          type: string
        business_registration_id_type:
          description: Business registration identifier type, as provided by the Visa card network.
          enum:
          - unspecified
          - tax_registration_identification
          - national_identification
          - company_registration_identification
          - passport
          - default_value
          type: string
        city:
          description: Card acceptor's city.
          type: string
        country_code:
          description: 'Card acceptor''s country code.

            May be returned if the request uses Transaction Model v2 of the Marqeta Core API.

            Not returned for Transaction Model v1 requests.'
          type: string
        country_of_origin:
          description: 'The merchant''s country of origin.


            A merchant''s country of origin can be different from the country in which the merchant is located.

            For example, embassies are physically located in countries that are not their country of origin: a Mexican embassy might be physically located in Singapore, but the country of origin is Mexico.


            This field is included when the cardholder conducts a transaction with a government-controlled merchant using a Marqeta-issued card.'
          type: string
        customer_service_phone:
          type: string
        geographic_coordinates:
          description: 'For Mastercard only.

            Geographic coordinates of the card acceptor in `latitudeE7,longitudeE7` format.'
          type: string
        independent_sales_organization_id:
          type: string
        legal_business_name:
          description: Legal business name, as provided by the Visa card network.
          type: string
        mcc:
          description: Merchant category code (MCC).
          type: string
        mcc_groups:
          description: An array of `mcc_groups`.
          items:
            type: string
          type: array
        merchant_tax_id:
          type: string
        merchant_vat_registration_id:
          description: The VAT registration identifier of the merchant.
          type: string
        mid:
          description: The merchant identifier.
          type: string
        name:
          description: Card acceptor's name.
          type: string
        network_assigned_id:
          description: Identifier assigned by the card network.
          type: string
        network_mid:
          description: The merchant identifier on the card network.
          type: string
        payment_facilitator_id:
          type: string
        payment_facilitator_name:
          description: 'The name of the payment facilitator, including the sub-merchant identifier, of an original credit transaction.

            This field is returned when a payment facilitator participates in the transaction.'
          type: string
        phone:
          type: string
        poi:
          $ref: '#/components/schemas/terminal_model'
        postal_code:
          description: Card acceptor's postal code.
          type: string
        service_geographic_coordinates:
          description: 'For Mastercard only.

            Geographic coordinates of the service provider in `latitudeE7,longitudeE7` format.'
          type: string
        special_merchant_id:
          type: string
        state:
          description: 'State, provincial, territorial, or federal abbreviation (`CA` for California or `CAN` for Canada, for example).


            For the complete list, see <</core-api/kyc-verification#_valid_state_provincial_territorial_and_federal_abbreviations, Valid state, provincial, territorial, and federal abbreviations>>.


            *Note*: Non-US merchants may return more than 2 char for this field.'
          type: string
        sub_merchant_id:
          type: string
        transfer_service_provider_name:
          description: 'The name of the transfer service provider of a money transfer original credit transaction.

            This field is included when a transfer service provider participates in the transaction.'
          type: string
        url:
          type: string
      type: object
    CardFulfillmentResponse:
      description: Determines physical characteristics of a card and shipment information.
      properties:
        card_fulfillment_reason:
          description: Descriptive reason for the card fulfillment.
          enum:
          - NEW
          - LOST_STOLEN
          - EXPIRED
          type: string
        card_personalization:
          $ref: '#/components/schemas/card_personalization'
        shipping:
          $ref: '#/components/schemas/ShippingInformationResponse'
      required:
      - card_personalization
      type: object
    account_owner_model:
      description: Information about the owner of an account participating in an account funding or original credit transaction.
      properties:
        country_of_birth:
          description: Account owner's country of birth.
          type: string
        dob:
          description: Account owner's date of birth.
          type: string
        email_address:
          description: Account owner's email address.
          type: string
        nationality:
          description: Account owner's nationality.
          type: string
        occupation:
          description: Account owner's occupation.
          type: string
      type: object
    fleet_data:
      description: Contains details about fleet program transactions.
      properties:
        prompt_data:
          description: If card product is configured for prompting, contains prompt data entered at the point of sale.
          properties:
            driver_number:
              description: Driver number entered at the point of sale.
              type: string
            odometer:
              description: Fleet vehicle odometer reading entered at the point of sale.
              type: string
            vehicle_number:
              description: Vehicle number entered at the point of sale.
              type: string
          type: object
        purchase_type:
          description: If provided by the network, indicates whether the purchase contains items for fuel, non-fuel, or both.
          enum:
          - fuel
          - non-fuel
          - fuel_and_non_fuel
          type: string
      type: object
    gpa_response:
      description: 'Contains information about a GPA order, including fees, funding sources, and addresses.

        See <</core-api/gpa-orders, GPA Orders>> for more information.'
      properties:
        amount:
          description: Amount funded.
          type: number
        business_token:
          description: 'Unique identifier of the business.


            This field is returned if it exists in the resource.'
          type: string
        created_time:
          description: Date and time when the GPA order was created, in UTC.
          format: date-time
          type: string
        currency_code:
          description: Three-digit ISO 4217 currency code.
          type: string
        fees:
          description: 'List of fees associated with the funding transaction.


            This array is returned if it exists in the resource.'
          items:
            $ref: '#/components/schemas/fee_detail'
          type: array
        funding:
          $ref: '#/components/schemas/funding'
        funding_source_address_token:
          description: Unique identifier of the funding source address to use for this order.
          type: string
        funding_source_token:
          description: Unique identifier of the funding source to use for this order.
          type: string
        gateway_message:
          description: 'Message about the status of the funding request.

            Useful for determining whether it was approved and completed successfully, declined by the gateway, or timed out.


            This field is returned if it exists in the resource.'
          type: string
        gateway_token:
          description: 'Unique identifier of the JIT Funding request and response.


            This field is returned if it exists in the resource.'
          format: int64
          type: integer
        jit_funding:
          $ref: '#/components/schemas/jit_funding_api'
        last_modified_time:
          description: Date and time when the GPA order was last modified, in UTC.
          format: date-time
          type: string
        memo:
          description: 'Additional descriptive text.


            This field is returned if it exists in the resource.'
          type: string
        response:
          $ref: '#/components/schemas/response'
        state:
          description: Current status of the funding transaction.
          type: string
        tags:
          description: 'Comma-delimited list of tags describing the GPA order.


            This field is returned if it exists in the resource.'
          type: string
        token:
          description: Unique identifier of the GPA order.
          type: string
        transaction_token:
          description: Unique identifier of the transaction being funded.
          type: string
        user_token:
          description: 'Unique identifier of the user resource.


            This field is returned if it exists in the resource.'
          type: string
      required:
      - amount
      - created_time
      - currency_code
      - funding
      - funding_source_token
      - last_modified_time
      - response
      - state
      - token
      - transaction_token
      type: object
    transaction_device:
      description: 'Contains information about the device used in the transaction to enhance the risk decisioning process.

        Use this data to improve fraud prevention and dispute resolution.'
      properties:
        binding_id:
          description: Unique identifier of the data component bound to the credential.
          type: string
        ip_address:
          description: 'IP address of the device.

            The presence of the IP address helps determine if the transaction was initiated from an unusual network, helping establish a pattern of safe device usage that further confirms the authenticity of the consumer who initiated the transaction.'
          type: string
        location:
          description: 'Geographic coordinates of the device.

            Contains the latitude and longitude of the device used when the cardholder was authenticated during checkout.

            This field helps to determine if the transaction was initiated from an unexpected location.'
          type: string
        phone_number:
          description: 'Telephone number of the device.

            Contains the phone number that was used to authenticate the consumer during checkout, or the consumer''s preferred phone number.

            The presence of the phone number helps establish the consumer''s authenticity when matching the phone number provided during checkout to a list of known phone numbers for the consumer.'
          type: string
      type: object
    card_response:
      description: Contains information about the card used in the transaction.
      properties:
        3csc:
          type: string
        account_tokens:
          description: List of account tokens associated with the card
          items:
            type: string
          type: array
        activation_actions:
          $ref: '#/components/schemas/activation_actions'
        barcode:
          description: Barcode printed on the card, expressed as numerals.
          type: string
        bulk_issuance_token:
          description: Unique identifier of the bulk card order.
          type: string
        card_product_token:
          description: Unique identifier of the card product.
          type: string
        chip_cvv_contactless_number:
          type: string
        chip_cvv_number:
          description: Three-digit card verification value (ICVV) stored on the chip of the card.
          type: string
        contactless_exemption_counter:
          description: 'Running count of the contactless transactions successfully completed since the last strong customer authentication (SCA) challenge was issued.

            You can limit the number of contactless transactions that can be performed without issuing an SCA challenge at the card product level.


            For more information about strong customer authentication, see <</core-api/card-products, Card Products>>.'
          format: int32
          type: integer
        contactless_exemption_total_amount:
          description: 'Running total of the money spent in contactless transactions successfully completed since the last strong customer authentication (SCA) challenge was issued.

            You can limit the total amount that can be spent in contactless transactions without issuing an SCA challenge at the card product level.


            For more information about strong customer authentication, see <</core-api/card-products, Card Products>>.'
          type: number
        contactless_exemption_transaction_currency:
          description: Indicates the currency type of the transaction.
          type: string
        created_time:
          description: Date and time when the resource was created, in UTC.
          format: date-time
          type: string
        cvv_number:
          description: Three-digit card verification value (CVV2 or CVC2) printed on the card.
          type: string
        expedite:
          default: false
          description: A value of `true` indicates that you requested expedited processing of the card from your card fulfillment provider.
          type: boolean
        expiration:
          description: Expiration date in `MMyy` format.
          type: string
        expiration_time:
          description: Expiration date and time, in UTC.
          format: date-time
          type: string
        fulfillment:
          $ref: '#/components/schemas/CardFulfillmentResponse'
        fulfillment_status:
          description: 'Card fulfillment status:


            * *ISSUED:* Initial state of all newly created/issued cards.

            * *ORDERED:* Card ordered through the card fulfillment provider.

            * *REORDERED:* Card reordered through the card fulfillment provider.

            * *REJECTED:* Card rejected by the card fulfillment provider.

            * *SHIPPED:* Card shipped by the card fulfillment provider.

            * *DELIVERED:* Card delivered by the card fulfillment provider.

            * *DIGITALLY_PRESENTED:* Card digitally presented using the `/cards/{token}/showpan` endpoint; does not affect the delivery of physical cards.'
          enum:
          - ISSUED
          - ORDERED
          - REORDERED
          - REJECTED
          - SHIPPED
          - DELIVERED
          - DIGITALLY_PRESENTED
          type: string
        instrument_type:
          description: 'Instrument type of the card:


            * *PHYSICAL_MSR:* A physical card with a magnetic stripe. This is the default physical card type.

            * *PHYSICAL_ICC:* A physical card with an integrated circuit, or "chip."

            * *PHYSICAL_CONTACTLESS:* A physical card that uses radio frequency identification (RFID) or near-field communication (NFC) to enable payment over a secure radio interface.

            * *PHYSICAL_COMBO:* A physical card with a chip that also supports contactless payments.

            * *VIRTUAL_PAN:* A virtual card with a primary account number (PAN).'
          enum:
          - PHYSICAL_MSR
          - PHYSICAL_ICC
          - PHYSICAL_CONTACTLESS
          - PHYSICAL_COMBO
          - VIRTUAL_PAN
          type: string
        last_four:
          description: Last four digits of the card primary account number (PAN).
          type: string
        last_modified_time:
          description: Date and time when the resource was last modified, in UTC.
          format: date-time
          type: string
        metadata:
          additionalProperties:
            type: string
          description: Associates customer-provided metadata with the card.
          type: object
        new_pan_from_card_token:
          description: Reissues the specified card (known as the "source" card) with a new primary account number (PAN).
          type: string
        pan:
          description: Primary account number (PAN) of the card.
          type: string
        pin_is_set:
          default: false
          description: Specifies if the personal identification number (PIN) has been set for the card.
          type: boolean
        reissue_pan_from_card_token:
          description: Reissues the specified card (known as the "source" card).
          type: string
        state:
          description: Indicates the state of the card.
          enum:
          - ACTIVE
          - SUSPENDED
          - TERMINATED
          - UNSUPPORTED
          - UNACTIVATED
          - LIMITED
          type: string
        state_reason:
          description: 'Descriptive reason for why the card is in its current state.

            For example, "Card activated by cardholder".'
          type: string
        token:
          description: Unique identifier of the card.
          type: string
        translate_pin_from_card_token:
          description: Copies the personal identification number (PIN) from the specified source card to the newly created card.
          type: string
        user:
          $ref: '#/components/schemas/user_card_holder_response'
        user_token:
          description: Unique identifier of the cardholder.
          type: string
      required:
      - barcode
      - card_product_token
      - created_time
      - expiration
      - expiration_time
      - fulfillment_status
      - last_four
      - last_modified_time
      - pan
      - pin_is_set
      - state
      - state_reason
      - token
      - user_token
      type: object
    airline:
      description: Contains information about airline-related transactions.
      properties:
        depart_date:
          description: The date and time of departure.
          format: date-time
          type: string
        origination_city:
          description: The city where the flight originates.
          type: string
        passenger_name:
          description: The name of the passenger.
          type: string
      type: object
    BillingAddress:
      properties:
        address:
          type: string
        compressed_zip:
          type: string
        first_name:
          type: string
        last_name:
          type: string
        zip:
          type: string
      type: object
    funding_source_model:
      description: Contains funding source information for the transaction, including the funding type and time.
      discriminator:
        mapping:
          bankaccount: '#/components/schemas/bank_account_funding_source_model'
          chargeback: '#/components/schemas/chargeback_funding_source_model'
          directdeposit: '#/components/schemas/direct_deposit_funding_source_model'
          paymentcard: '#/components/schemas/payment_card_funding_source_model'
          program: '#/components/schemas/program_funding_source_model'
          programgateway: '#/components/schemas/program_gateway_funding_source_model'
        propertyName: type
      properties:
        active:
          default: false
          description: Whether the funding source is active.
          type: boolean
        created_time:
          description: Date and time when the funding source was created, in UTC.
          format: date-time
          type: string
        is_default_account:
          default: false
          description: Whether the GPA order unload's funding source is the default funding account.
          type: boolean
        last_modified_time:
          description: Date and time when the funding source was last modified, in UTC.
          format: date-time
          type: string
        token:
          description: Unique identifier of the funding source.
          type: string
        type:
          description: Funding type of the funding source.
          type: string
      required:
      - active
      - created_time
      - is_default_account
      - last_modified_time
      - token
      - type
      type: object
    images:
      description: Specifies personalized images that appear on the card.
      properties:
        card:
          $ref: '#/components/schemas/images_card'
        carrier:
          $ref: '#/components/schemas/ImagesCarrier'
        carrier_return_window:
          $ref: '#/components/schemas/images_carrier_return_window'
        signature:
          $ref: '#/components/schemas/images_signature'
      t

# --- truncated at 32 KB (189 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/marqeta/refs/heads/main/openapi/marqeta-simulate-api-openapi.yml