Marqeta gpa orders API

openapi: 3.2.0
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 gpa orders API
  version: 3.0.39
servers:
- url: /v3
security:
- mqAppAndAccessToken: []
tags:
- name: gpa orders
paths:
  /gpaorders:
    post:
      operationId: postGpaorders
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/gpa_request'
        required: false
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/gpa_response'
          description: Success
        '400':
          content: {}
          description: Bad request
        '409':
          content: {}
          description: Request already processed with a different payload
        '422':
          content: {}
          description: Rule violations or declined transactions from funding source
        '500':
          content: {}
          description: Server error
      summary: Funds a user's GPA account
      tags:
      - gpa orders
  /gpaorders/unloads:
    get:
      operationId: getGpaordersUnloads
      parameters:
      - description: Number of GPA unloads 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
      - description: User token
        explode: true
        in: query
        name: user_token
        required: false
        schema:
          type: string
        style: form
      - description: Business token
        explode: true
        in: query
        name: business_token
        required: false
        schema:
          type: string
        style: form
      - description: Original order token
        explode: true
        in: query
        name: original_order_token
        required: false
        schema:
          type: string
        style: form
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GPAUnloadListResponse'
          description: Success
        '400':
          content: {}
          description: Bad request
        '500':
          content: {}
          description: Server error
      summary: Lists all GPA returns
      tags:
      - gpa orders
    post:
      operationId: postGpaordersUnloads
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/unload_request_model'
        required: false
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/gpa_returns'
          description: Success
        '400':
          content: {}
          description: Bad request
        '404':
          content: {}
          description: GPA order token not found
        '412':
          content: {}
          description: Pre-condition failed. Unload amount is greater than load amount
        '500':
          content: {}
          description: Server error
      summary: Returns a GPA order
      tags:
      - gpa orders
  /gpaorders/unloads/{unload_token}:
    get:
      operationId: getGpaordersUnloadsUnloadtoken
      parameters:
      - description: Unload token
        explode: false
        in: path
        name: unload_token
        required: true
        schema:
          type: string
        style: simple
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/gpa_returns'
          description: Success
        '400':
          content: {}
          description: Bad request
        '404':
          content: {}
          description: Return not found
        '500':
          content: {}
          description: Server error
      summary: Returns a specific GPA return
      tags:
      - gpa orders
  /gpaorders/{token}:
    get:
      operationId: getGpaordersToken
      parameters:
      - explode: false
        in: path
        name: token
        required: true
        schema:
          type: string
        style: simple
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/gpa_response'
          description: Success
        '404':
          content: {}
          description: GPA order token not found
        '500':
          content: {}
          description: Server error
      summary: Returns a GPA order
      tags:
      - gpa orders
components:
  schemas:
    jit_address_verification:
      description: Contains address verification data used to make JIT Funding decisions.
      properties:
        gateway:
          $ref: '#/components/schemas/address_verification_source'
        issuer:
          $ref: '#/components/schemas/address_verification_source'
        request:
          $ref: '#/components/schemas/avs_information'
      type: object
    response:
      description: Response codes and memos for account name verification, address verification, card security verification, and transactions.
      properties:
        additional_information:
          description: 'Additional information about the transaction, such as velocity control details.


            This field is returned in transaction response objects only.

            It is not returned in address verification or card security verification response objects.'
          type: string
        code:
          description: 'Four-digit response code for address verification, card security code verification, or transactions.


            For account name verification, the four digits correspond with assertions that the first, middle, last, and full name of the cardholder on the Marqeta platform match the data provided by the cardholder.


            * `0` indicates no validation was performed

            * `1` indicates the match was unsuccessful (not matched)

            * `2` indicates the match was partial

            * `3` indicates the match was exact


            For example:


            [cols="2,3,3,3,3"]

            !===

            ! Code ! First Name ! Middle Name ! Last Name ! Full Name


            ! `0000`

            ! Not validated

            ! Not validated

            ! Not validated

            ! Not validated


            ! `1111`

            ! Not matched

            ! Not matched

            ! Not matched

            ! Not matched


            ! `3333`

            ! Exact match

            ! Exact match

            ! Exact match

            ! Exact match


            ! `1232`

            ! Not matched

            ! Partial match

            ! Exact match

            ! Partial match

            !===


            For address verification responses, the code is an assertion by the Marqeta platform as to whether its address verification data matches that provided by the cardholder:


            [cols="2,3,3"]

            !===

            ! Code ! Address ! Postal Code


            ! `0000`

            ! Match

            ! Match


            ! `0001`

            ! Match

            ! Not matched


            ! `0100`

            ! Not matched

            ! Match


            ! `0101`

            ! Not matched

            ! Not matched


            ! `0200`

            ! Data not present

            ! Match


            ! `0201`

            ! Data not present

            ! Not matched


            ! `0002`

            ! Match

            ! Data not present


            ! `0102`

            ! Not matched

            ! Data not present


            ! `0303`

            ! Not validated

            ! Not validated

            !===


            For card security verification, the code indicates whether the verification check passed and can have these possible values:


            * `0000` – Passed

            * `0001` – Did not pass


            For a transaction, the code describes the outcome of the attempted transaction.

            For the full list of transaction codes, see <</developer-guides/about-transactions#_transaction_response_codes, Transaction response codes>>.'
          type: string
        memo:
          description: Additional text that describes the response.
          type: string
      required:
      - code
      type: object
    flex:
      description: Contains information about a Flexible Credential transaction.
      properties:
        action:
          description: Indicates whether the Flexible Credential transaction object is actionable (`inquiry`) or merely informative (`advice`).
          enum:
          - inquiry
          - advice
          type: string
        eligible:
          description: Indicates whether or not the transaction is eligible for Flexible Credential transactions.
          type: string
        eligible_products:
          description: 'Specifies which of the payment instrument''s credentials is eligible for this transaction:


            * A value of `DEBIT` indicates the primary credential.

            * A value of `LOAN` indicates the secondary credential.'
          items:
            type: string
          type: array
        secondary_credential_identifier:
          description: Identifies the secondary credential used in the transaction, if applicable.
          type: string
        selected_product:
          description: Indicates the eligible product that was used in the transaction.
          type: string
      type: object
    address_verification_source:
      description: Contains address verification data consisting of address data entered by the cardholder, address data held by the Marqeta platform, and an assertion by the Marqeta platform as to whether the two sets of data match.
      properties:
        on_file:
          $ref: '#/components/schemas/avs_information'
        response:
          $ref: '#/components/schemas/response'
      type: object
    jit_funding_api:
      description: 'Contains information about the JIT Funding load event, in which funds are loaded into an account.


        This object is returned if your program uses JIT Funding.'
      properties:
        account_name_verification:
          $ref: '#/components/schemas/jit_account_name_verification'
        acting_user_token:
          description: 'User who conducted the transaction.


            Can be a child user configured to share its parent''s account balance.'
          maxLength: 36
          minLength: 0
          type: string
        address_verification:
          $ref: '#/components/schemas/jit_address_verification'
        amount:
          description: Requested amount of funding.
          minimum: 0
          type: number
        anticipated_amount_supported:
          type: boolean
        balances:
          additionalProperties:
            $ref: '#/components/schemas/cardholder_balance'
          description: Contains the GPA's balance details.
          type: object
        business_token:
          description: Holder of the business account that was funded.
          maxLength: 36
          minLength: 0
          type: string
        decline_reason:
          description: Reason why the transaction was declined.
          enum:
          - INVALID_AMOUNT
          - INSUFFICIENT_FUNDS
          - TRANSACTION_NOT_PERMITTED
          - SUSPECTED_FRAUD
          - AMOUNT_LIMIT_EXCEEDED
          - TRANSACTION_COUNT_LIMIT_EXCEEDED
          - DUPLICATE_TRANSACTION
          - INVALID_MERCHANT
          - INVALID_CARD
          - NO_CREDIT_ACCOUNT
          - EXPIRED_CARD
          - NO_CHECKING_ACCOUNT
          - NO_SAVINGS_ACCOUNT
          - STOP_PAYMENT
          - REVOCATION_AUTHORIZATION_ORDER
          - REVOCATION_ALL_AUTHORIZATION_ORDER
          - SOFT_DECLINE_AUTHENTICATION_REQUIRED
          - CLOSED_ACCOUNT
          - SOFT_DECLINE_PIN_REQUIRED
          - CARD_NOT_ACTIVE
          - CARDHOLDER_NOT_ACTIVE
          - BLOCKED_BY_ISSUER
          - BLOCKED_BY_CARDHOLDER
          - BLOCKED_MERCHANT_BY_CARDHOLDER
          - INVALID_DRIVER_NUMBER
          - INVALID_VEHICLE_NUMBER
          type: string
        incremental_authorization_jit_funding_tokens:
          description: 'Array of tokens referencing the JIT Funding tokens of all previous associated incremental authorization JIT Funding requests.

            Useful for ascertaining the final transaction amount when the original amount was incremented.'
          items:
            type: string
          type: array
        jit_account_name_verification:
          $ref: '#/components/schemas/jit_account_name_verification'
        memo:
          description: Additional information that describes the JIT Funding transaction.
          maxLength: 99
          minLength: 0
          type: string
        method:
          description: 'JIT Funding response type.

            See <</core-api/gateway-jit-funding-messages#_the_jit_funding_object, The jit_funding object>> for the purpose, funding event type, and description of each method.'
          enum:
          - pgfs.authorization
          - pgfs.authorization.clearing
          - pgfs.authorization.advice
          - pgfs.authorization.incremental
          - pgfs.authorization.capture
          - pgfs.authorization.reversal
          - pgfs.authorization.cashback
          - pgfs.balanceinquiry
          - pgfs.auth_plus_capture
          - pgfs.refund
          - pgfs.refund.authorization
          - pgfs.refund.authorization.reversal
          - pgfs.refund.authorization.clearing
          - pgfs.force_capture
          - pgfs.authorization.capture.chargeback
          - pgfs.authorization.capture.chargeback.reversal
          - pgfs.pindebit
          - pgfs.pindebit.chargeback
          - pgfs.pindebit.chargeback.reversal
          - pgfs.pindebit.cashback
          - pgfs.pindebit.refund
          - pgfs.pindebit.authorization
          - pgfs.pindebit.authorization.clearing
          - pgfs.pindebit.authorization.reversal
          - pgfs.pindebit.atm.withdrawal
          - pgfs.pindebit.balanceinquiry
          - pgfs.pindebit.quasi.cash
          - pgfs.dispute.credit
          - pgfs.dispute.debit
          - pgfs.directdeposit.credit
          - pgfs.directdeposit.debit
          - pgfs.directdeposit.credit.reversal
          - pgfs.directdeposit.debit.reversal
          - pgfs.adjustment.credit
          - pgfs.adjustment.debit
          - pgfs.auth_plus_capture.standin
          - pgfs.authorization.standin
          - pgfs.network.load
          - pgfs.original.credit.authorization
          - pgfs.original.credit.auth_plus_capture
          - pgfs.original.credit.authorization.clearing
          - pgfs.original.credit.authorization.reversal
          - pgfs.billpayment
          - pgfs.billpayment.capture
          - pgfs.billpayment.reversal
          - pgfs.atm.withdrawal
          - pgfs.atm.clearing.withdrawal
          - pgfs.authorization.quasi.cash
          - pgfs.authorization.clearing.quasi.cash
          - pgfs.authorization.account_verification
          - pgfs.product.inquiry
          type: string
        original_jit_funding_token:
          description: 'Unique identifier of the first associated JIT Funding message.

            Useful for correlating related JIT Funding messages (that is, those associated with the same GPA order).

            Not included in the first of any set of related messages.'
          maxLength: 36
          minLength: 0
          type: string
        tags:
          description: Customer-defined tags related to the JIT Funding transaction.
          maxLength: 255
          minLength: 0
          type: string
        token:
          description: 'Existing JIT Funding token matching the `funding.gateway_log.transaction_id` field of the associated GPA order.


            *NOTE:* The `transaction_id` field updates if a subsequent JIT Funding message associated with that GPA order is sent.

            If multiple JIT Funding messages are associated with the same GPA order, the `transaction_id` field matches the token of the most recent message.'
          maxLength: 36
          minLength: 0
          type: string
        user_token:
          description: Holder of the user account that was funded.
          maxLength: 36
          minLength: 0
          type: string
      required:
      - amount
      - method
      - token
      - user_token
      type: object
    GPAUnloadListResponse:
      properties:
        count:
          format: int32
          type: integer
        data:
          items:
            $ref: '#/components/schemas/gpa_returns'
          type: array
        end_index:
          format: int32
          type: integer
        is_more:
          default: false
          type: boolean
        start_index:
          format: int32
          type: integer
      type: object
    avs_information:
      description: Contains address verification information.
      properties:
        postal_code:
          description: Postal code of the address.
          type: string
        street_address:
          description: Street name and number of the address.
          type: string
        zip:
          description: United States ZIP code of the address.
          type: string
      type: object
    jit_program_response:
      description: Contains the gateway's information about the JIT Funding transaction.
      properties:
        flex:
          $ref: '#/components/schemas/flex'
        jit_funding:
          $ref: '#/components/schemas/jit_funding_api'
        network_metadata:
          $ref: '#/components/schemas/network_metadata'
      required:
      - jit_funding
      type: object
    CardholderAddressResponse:
      description: Contains information about the billing address of the funding source.
      properties:
        active:
          default: false
          description: Whether the address is active.
          type: boolean
        address_1:
          description: Street address of the funding source.
          maxLength: 255
          minLength: 0
          type: string
        address_2:
          description: 'Additional address information for the funding source.


            This field is returned if it exists in the resource.'
          maxLength: 255
          minLength: 0
          type: string
        business_token:
          description: 'Unique identifier of the business account holder associated with the address.


            This field is returned if it exists in the resource.'
          maxLength: 36
          minLength: 1
          type: string
        city:
          description: City of the funding source.
          maxLength: 40
          minLength: 0
          type: string
        country:
          description: Country of the funding source.
          maxLength: 40
          minLength: 1
          type: string
        created_time:
          description: Date and time when the address was created, in UTC.
          format: date-time
          type: string
        first_name:
          description: First name of the account holder associated with the funding source.
          maxLength: 40
          minLength: 0
          type: string
        is_default_address:
          default: false
          description: Whether this address is the default address used by the funding source.
          type: boolean
        last_modified_time:
          description: 'Date and time when the address was last modified, in UTC.


            This field is returned if it exists in the resource.'
          format: date-time
          type: string
        last_name:
          description: Last name of the account holder associated with the funding source.
          maxLength: 40
          minLength: 0
          type: string
        phone:
          description: 'Phone number of the funding source.


            This field is returned if it exists in the resource.'
          maxLength: 255
          minLength: 0
          type: string
        postal_code:
          description: Postal code of the funding source.
          maxLength: 10
          minLength: 0
          type: string
        state:
          description: 'Two-character state, provincial, or territorial abbreviation.


            For the complete list, see <</core-api/kyc-verification#_valid_state_provincial_territorial_and_federal_abbreviations, Valid state, provincial, territorial, and federal abbreviations>>.'
          maxLength: 2
          minLength: 0
          type: string
        token:
          description: Unique identifier of the `funding_source_address` object.
          maxLength: 36
          minLength: 1
          type: string
        user_token:
          description: 'Unique identifier of the user account holder associated with the address.


            This field is returned if it exists in the resource.'
          maxLength: 36
          minLength: 1
          type: string
        zip:
          description: United States ZIP code of the funding source.
          maxLength: 10
          minLength: 0
          type: string
      required:
      - address_1
      - city
      - country
      - created_time
      - first_name
      - last_modified_time
      - last_name
      - postal_code
      - state
      - token
      - zip
      type: object
    unload_request_model:
      properties:
        amount:
          type: number
        funding_source_address_token:
          maxLength: 36
          minLength: 1
          type: string
        memo:
          maxLength: 99
          minLength: 0
          type: string
        original_order_token:
          maxLength: 36
          minLength: 1
          type: string
        tags:
          maxLength: 255
          minLength: 0
          type: string
        token:
          maxLength: 36
          minLength: 1
          type: string
      required:
      - amount
      - original_order_token
      type: object
    fee_detail:
      description: Contains details about a fee.
      properties:
        fee:
          $ref: '#/components/schemas/fee'
        memo:
          description: Additional text describing the fee.
          maxLength: 99
          minLength: 1
          type: string
        overrideAmount:
          description: Dynamic fee amount that overrides the `fee.amount` field value.
          type: number
        tags:
          description: Descriptive metadata about the fee.
          maxLength: 255
          minLength: 0
          type: string
        token:
          description: Unique identifier of the fee.
          maxLength: 36
          minLength: 1
          type: string
        transaction_token:
          description: Unique identifier of the fee transaction.
          type: string
      required:
      - fee
      - token
      - transaction_token
      type: object
    funding:
      description: Contains funding information for the transaction, including funding amount, type, and time.
      properties:
        amount:
          description: Amount of funds loaded into the GPA.
          type: number
        gateway_log:
          $ref: '#/components/schemas/gateway_log_model'
        source:
          $ref: '#/components/schemas/funding_source_model'
        source_address:
          $ref: '#/components/schemas/CardholderAddressResponse'
      required:
      - source
      type: object
    network_metadata:
      description: 'Contains network-related metadata for the transaction, including details about the card program and the card product.

        Returned if provided by the card network'
      properties:
        account_identification_1:
          type: string
        incoming_response_code:
          description: 'Network response code, as provided by the card network.


            For example, Visa response code `59` indicates suspected fraud.'
          type: string
        message_reason_code:
          type: string
        network_funding_txn_type:
          description: Transaction type indicator provided by the card network for original credit and account funding transactions.
          type: string
        outgoing_response_code:
          description: 'Network response code, as provided by Marqeta.


            For example, Visa response code `59` indicates suspected fraud.'
          type: string
        product_id:
          description: 'Product identification value assigned by the card network to each card product.

            Can be used to track card-level activity by individual account number for premium card products.'
          type: string
        program_id:
          description: Program identification number used with `product_id` that identifies the programs associated with a card within a program registered by the issuer with the card network.
          type: string
        spend_qualifier:
          description: Indicates whether or not the base spend-assessment threshold defined by the card network has been met.
          type: string
        surcharge_free_atm_network:
          description: Name of the surcharge-free ATM network used to complete the transaction.
          type: string
        terminal_verification_results:
          type: string
      type: object
    gateway_log_model:
      description: Contains information from the JIT Funding gateway in response to a funding request.
      properties:
        duration:
          description: Length of time in milliseconds that the gateway took to respond to a funding request.
          format: int64
          type: integer
        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.'
          type: string
        order_number:
          description: Customer order number, same value as `transaction.token`.
          type: string
        response:
          $ref: '#/components/schemas/gateway_response'
        timed_out:
          default: false
          description: Whether the gateway sent a response (`true`) or timed out (`false`).
          type: boolean
        transaction_id:
          description: Customer-defined identifier for the transaction.
          type: string
      required:
      - message
      - order_number
      - transaction_id
      type: object
    fee_model:
      description: 'Contains attributes that define characteristics of one or more fees.

        This array is returned in the response when it is included in the request.'
      properties:
        memo:
          description: Additional text describing the fee.
          maxLength: 99
          minLength: 1
          type: string
        overrideAmount:
          description: Dynamic fee amount that overrides the `fee.amount` field value.
          type: number
        tags:
          description: Descriptive metadata about the fee.
          maxLength: 255
          minLength: 0
          type: string
        token:
          description: Unique identifier of the fee.
          maxLength: 36
          minLength: 1
          type: string
      required:
      - token
      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
    account_name_verification_source:
      description: Contains account name verification data used to make JIT Funding decisions.
      properties:
        first_name:
          description: First or given name of the cardholder.
          type: string
        last_name:
          description: Last or family name of the cardholder.
          type: string
        middle_name:
          description: Middle name of the cardholder.
          type: string
        on_file:
          $ref: '#/components/schemas/ani_information'
        response:
          $ref: '#/components/schemas/response'
      type: object
    gateway_response:
      description: Contains information from the gateway in response to a funding request.
      properties:
        code:
          description: Code received from the gateway.
          type: string
        data:
          $ref: '#/components/schemas/jit_program_response'
      required:
      - code
      type: object
    gpa_returns:
      description: Contains information about a GPA unload order.
      properties:
        amount:
          description: Amount of funds returned to the funding source.
          type: number
        created_time:
          description: Date and time when the GPA unload order was created, in UTC.
          format: date-time
          type: string
        funding:
          $ref: '#/components/schemas/funding'
        funding_source_address_token:
          description: Identifies the funding source used for this order.
          type: string
        funding_source_token:
          description: Identifies the funding source used for this order.
          type: string
        jit_funding:
          $ref: '#/components/schemas/jit_funding_api'
        last_modified_time:
          description: Date and time when the GPA unload order was last modified, in UTC.
          format: date-time
          type: string
        memo:
          description: Additional descriptive text.
          type: string
        original_order_token:
          description: Identifies the original GPA order.
          type: string
        response:
          $ref: '#/components/schemas/response'
        state:
          description: Current status of the GPA unload order.
          type: string
        tags:
          description: Comma-delimited list of tags describing the GPA order.
          type: string
        token:
          description: Unique identifier of the GPA unload order.
          type: string
        transaction_token:
          description: Unique identifier of the transaction.
          type: string
      required:
      - amount
      - created_time
      - funding
      - funding_source_token
      - last_modified_time
      - response
      - state
      - token
      - transaction_tok

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