Marqeta gpa orders 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 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:
    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
    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
    cardholder_balance:
      description: Returns general purpose account (GPA) balances for a user or business.
      properties:
        available_balance:
          description: 'Ledger balance minus any authorized transactions that have not yet cleared.

            Also known as the cardholder''s purchasing power.

            When using JIT Funding, this balance is usually equal to $0.00.'
          type: number
        balances:
          additionalProperties:
            $ref: '#/components/schemas/cardholder_balance'
          description: Contains GPA balance information, organized by currency code.
          type: object
        cached_balance:
          description: Not currently in use.
          type: number
        credit_balance:
          description: Not currently in use.
          type: number
        currency_code:
          description: Three-digit ISO 4217 currency code.
          type: string
        impacted_amount:
          description: Balance change based on the amount of the transaction.
          type: number
        last_updated_time:
          description: Date and time when the resource was last updated, in UTC.
          format: date-time
          type: string
        ledger_balance:
          description: 'When using standard funding: The funds that are available to spend immediately, including funds from any authorized transactions that have not yet cleared.

            When using Just-in-Time (JIT) Funding: Authorized funds that are currently on hold, but not yet cleared.'
          type: number
        pending_credits:
          description: ACH loads that have been accepted, but for which the funding time has not yet elapsed.
          type: number
      required:
      - available_balance
      - balances
      - credit_balance
      - currency_code
      - last_updated_time
      - ledger_balance
      - pending_credits
      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
    jit_account_name_verification:
      description: 'Contains account name verification data used to make JIT Funding decisions from one of the following objects:


        * The `gateway` object, which contains account name verification data from your JIT Funding gateway.

        * The `issuer` object, which contains account name verification data from the Marqeta platform.

        * The `request` object, which contains account name verification data as it appears in a JIT Funding request.'
      properties:
        gateway:
          $ref: '#/components/schemas/account_name_verification_source'
        issuer:
          $ref: '#/components/schemas/account_name_verification_source'
        request:
          $ref: '#/components/schemas/ani_information'
      type: object
    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
    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
    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
    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
    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
    gpa_request:
      properties:
        amount:
          type: number
        business_token:
          description: Required if 'user_token' is null
          maxLength: 36
          minLength: 1
          type: string
        currency_code:
          type: string
        fees:
          items:
            $ref: '#/components/schemas/fee_model'
          type: array
        funding_source_address_token:
          maxLength: 36
          minLength: 1
          type: string
        funding_source_token:
          maxLength: 36
          minLength: 1
          type: string
        memo:
          maxLength: 99
          minLength: 1
          type: string
        tags:
          maxLength: 255
          minLength: 1
          type: string
        token:
          maxLength: 36
          minLength: 1
          type: string
        user_token:
          description: Required if 'business_token' is null
          maxLength: 36
          minLength: 1
          type: string
      required:
      - amount
      - currency_code
      - funding_source_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
    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_token
      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
    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
    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
    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
    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.
          exclusiveMinimum: false
          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_CARD

# --- 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