Marqeta cards 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 cards API
  version: 3.0.39
servers:
- url: /v3
security:
- mqAppAndAccessToken: []
tags:
- name: cards
paths:
  /cards:
    get:
      operationId: getCards
      parameters:
      - description: Number of cards to retrieve
        explode: true
        in: query
        name: count
        required: false
        schema:
          default: 5
          format: int32
          type: integer
        style: form
      - description: Start index
        explode: true
        in: query
        name: start_index
        required: false
        schema:
          default: 0
          format: int32
          type: integer
        style: form
      - description: Last four digits of card number
        explode: true
        in: query
        name: last_four
        required: true
        schema:
          type: string
        style: form
      - description: Comma-delimited list of fields to return (e.g. field_1,field_2,..). Leave blank to return all fields.
        explode: true
        in: query
        name: fields
        required: false
        schema:
          type: string
        style: form
      - description: Sort order
        explode: true
        in: query
        name: sort_by
        required: false
        schema:
          default: -lastModifiedTime
          type: string
        style: form
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CardListResponse'
          description: Success
        '400':
          content: {}
          description: Bad request
        '500':
          content: {}
          description: Server error
      summary: Lists cards by the last 4 digits
      tags:
      - cards
    post:
      operationId: postCards
      parameters:
      - description: Show CVV
        explode: true
        in: query
        name: show_cvv_number
        required: false
        schema:
          default: false
          type: boolean
        style: form
      - description: Show PAN
        explode: true
        in: query
        name: show_pan
        required: false
        schema:
          default: false
          type: boolean
        style: form
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/card_request'
        required: false
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/card_response'
          description: Success
        '400':
          content: {}
          description: User input error/Bad request
        '409':
          content: {}
          description: Token already associated with a different payload
        '500':
          content: {}
          description: Server error
      summary: Creates a card
      tags:
      - cards
  /cards/barcode/{barcode}:
    get:
      operationId: getCardsBarcodeBarcode
      parameters:
      - description: Barcode
        explode: false
        in: path
        name: barcode
        required: true
        schema:
          type: string
        style: simple
      - description: Comma-delimited list of fields to return (e.g. field_1,field_2,..). Leave blank to return all fields.
        explode: true
        in: query
        name: fields
        required: false
        schema:
          type: string
        style: form
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/card_response'
          description: Success
        '400':
          content: {}
          description: User input error/Bad request
        '404':
          content: {}
          description: Card does not exist
        '500':
          content: {}
          description: Server error
      summary: Returns a card's metadata
      tags:
      - cards
  /cards/getbypan:
    post:
      operationId: postCardsGetbypan
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/pan_request'
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/pan_response'
          description: Success
        '400':
          content: {}
          description: User input error/Bad request
        '500':
          content: {}
          description: Server error
      summary: Returns user and card tokens for the specified PAN
      tags:
      - cards
  /cards/user/{token}:
    get:
      operationId: getCardsUserToken
      parameters:
      - description: User token
        explode: false
        in: path
        name: token
        required: true
        schema:
          type: string
        style: simple
      - description: Number of items to retrieve
        explode: true
        in: query
        name: count
        required: false
        schema:
          default: 5
          format: int32
          type: integer
        style: form
      - description: Start index
        explode: true
        in: query
        name: start_index
        required: false
        schema:
          default: 0
          format: int32
          type: integer
        style: form
      - description: Comma-delimited list of fields to return (e.g. field_1,field_2,..). Leave blank to return all fields.
        explode: true
        in: query
        name: fields
        required: false
        schema:
          type: string
        style: form
      - description: Sort order
        explode: true
        in: query
        name: sort_by
        required: false
        schema:
          default: -lastModifiedTime
          type: string
        style: form
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CardListResponse'
          description: Success
        '400':
          content: {}
          description: User input error/Bad request
        '500':
          content: {}
          description: Server error
      summary: Lists all cards for a specific user
      tags:
      - cards
  /cards/{token}:
    get:
      operationId: getCardsToken
      parameters:
      - description: Card token
        explode: false
        in: path
        name: token
        required: true
        schema:
          type: string
        style: simple
      - description: Comma-delimited list of fields to return (e.g. field_1,field_2,..). Leave blank to return all fields.
        explode: true
        in: query
        name: fields
        required: false
        schema:
          type: string
        style: form
      - description: Object to expand
        explode: true
        in: query
        name: expand
        required: false
        schema:
          type: string
        style: form
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/card_response'
          description: Success
        '400':
          content: {}
          description: User input error/Bad request
        '404':
          content: {}
          description: Card not found
        '500':
          content: {}
          description: Server error
      summary: Returns a specific card
      tags:
      - cards
    put:
      operationId: putCardsToken
      parameters:
      - description: Card token
        explode: false
        in: path
        name: token
        required: true
        schema:
          type: string
        style: simple
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/card_update_request'
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/card_response'
          description: Success
        '400':
          content: {}
          description: User input error/Bad request
        '500':
          content: {}
          description: Server error
      summary: Updates a specific card
      tags:
      - cards
  /cards/{token}/showpan:
    get:
      operationId: getCardsTokenShowpan
      parameters:
      - description: Card token
        explode: false
        in: path
        name: token
        required: true
        schema:
          type: string
        style: simple
      - description: Comma-delimited list of fields to return (e.g. field_1,field_2,..). Leave blank to return all fields.
        explode: true
        in: query
        name: fields
        required: false
        schema:
          type: string
        style: form
      - explode: true
        in: query
        name: show_cvv_number
        required: false
        schema:
          type: boolean
        style: form
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/card_response'
          description: Success
        '400':
          content: {}
          description: User input error/Bad request
        '404':
          content: {}
          description: Card not found
        '500':
          content: {}
          description: Server error
      summary: Returns a specific card - PAN visible
      tags:
      - cards
  /cards/{token}/stoporders:
    get:
      operationId: getStopOrders
      parameters:
      - description: Card token
        explode: false
        in: path
        name: token
        required: true
        schema:
          type: string
        style: simple
      - description: Number of stop orders to retrieve
        explode: true
        in: query
        name: count
        required: false
        schema:
          default: 5
          format: int32
          type: integer
        style: form
      - description: Start index
        explode: true
        in: query
        name: start_index
        required: false
        schema:
          default: 0
          format: int32
          type: integer
        style: form
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StopOrderListResponse'
          description: Success
        '404':
          content: {}
          description: Not found
        '500':
          content: {}
          description: Server error
      summary: Lists all stop orders for a card
      tags:
      - cards
    post:
      operationId: postStopOrders
      parameters:
      - description: Card token
        explode: false
        in: path
        name: token
        required: true
        schema:
          type: string
        style: simple
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/stop_order_request'
        required: false
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/stop_order_response'
          description: Success
        '400':
          content: {}
          description: User input error/Bad request
        '404':
          content: {}
          description: Not found
        '409':
          content: {}
          description: Token already associated with a different payload
        '500':
          content: {}
          description: Server error
      summary: Creates a stop order for a card transaction
      tags:
      - cards
  /cards/{token}/stoporders/{stop_order_token}:
    get:
      operationId: getStopOrder
      parameters:
      - description: Card token
        explode: false
        in: path
        name: token
        required: true
        schema:
          type: string
        style: simple
      - description: Stop order token
        explode: false
        in: path
        name: stop_order_token
        required: true
        schema:
          type: string
        style: simple
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/stop_order_response'
          description: Success
        '404':
          content: {}
          description: Not found
        '500':
          content: {}
          description: Server error
      summary: Retrieves a specific stop order
      tags:
      - cards
    put:
      operationId: putStopOrders
      parameters:
      - description: Card token
        explode: false
        in: path
        name: token
        required: true
        schema:
          type: string
        style: simple
      - description: Stop order token
        explode: false
        in: path
        name: stop_order_token
        required: true
        schema:
          type: string
        style: simple
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/stop_order_update_request'
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/stop_order_response'
          description: Success
        '400':
          content: {}
          description: User input error/Bad request
        '404':
          content: {}
          description: Not found
        '422':
          content: {}
          description: Unprocessable entity
        '500':
          content: {}
          description: Server error
      summary: Updates a stop order by token
      tags:
      - cards
  /cards/{token}/transactions:
    get:
      operationId: getCardTransactions
      parameters:
      - description: Number of transactions to retrieve
        explode: true
        in: query
        name: count
        required: false
        schema:
          default: 10
          format: int32
          type: integer
        style: form
      - description: Start index
        explode: true
        in: query
        name: start_index
        required: false
        schema:
          default: 0
          format: int32
          type: integer
        style: form
      - description: Card token
        explode: false
        in: path
        name: token
        required: true
        schema:
          type: string
        style: simple
      - description: User token
        explode: true
        in: query
        name: user_token
        required: false
        schema:
          type: string
        style: form
      - description: Start date (yyyy-MM-dd | yyyy-MM-ddTHH:mm:ss.SS)
        explode: true
        in: query
        name: start_date
        required: false
        schema:
          type: string
        style: form
      - description: End date (yyyy-MM-dd | yyyy-MM-ddTHH:mm:ss.SS)
        explode: true
        in: query
        name: end_date
        required: false
        schema:
          type: string
        style: form
      - description: Filter by recurring transaction flag
        explode: true
        in: query
        name: is_recurring
        required: false
        schema:
          type: boolean
        style: form
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionModelListResponse'
          description: Success
        '400':
          content: {}
          description: User input error/Bad request
        '500':
          content: {}
          description: Server error
      summary: Returns transactions for a specific card
      tags:
      - cards
  /views/cards/{time_agg}:
    get:
      operationId: getCards
      summary: Retrieve card state and history data
      description: Returns card state and history data aggregated at card level or by time period. Use this endpoint to report on card issuance volume, card state distribution, and card activity across your program.
      tags:
      - cards
      parameters:
      - $ref: '#/components/parameters/time_agg'
      - $ref: '#/components/parameters/program'
      - $ref: '#/components/parameters/fields'
      - $ref: '#/components/parameters/start_date'
      - $ref: '#/components/parameters/end_date'
      - $ref: '#/components/parameters/format'
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/offset'
      responses:
        '200':
          description: Card data for the specified time period.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CardsResponse'
            text/csv:
              schema:
                type: string
                description: CSV-formatted card data.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /views/cards/detail:
    get:
      operationId: getCardsDetail
      summary: Retrieve detailed card information
      description: Returns detailed information for each card in your program, including the full card lifecycle history, current state, expiration, and associated user. Use this endpoint for granular card-level reporting and auditing.
      tags:
      - cards
      parameters:
      - $ref: '#/components/parameters/program'
      - $ref: '#/components/parameters/fields'
      - $ref: '#/components/parameters/format'
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/offset'
      responses:
        '200':
          description: Detailed card records.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CardsDetailResponse'
            text/csv:
              schema:
                type: string
                description: CSV-formatted detailed card data.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
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 loc

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