October 4, 2023
cancel
Showing results for 
Search instead for 
Did you mean: 
Help

OpenAPI specifications missing schemas and inconsistencies

OpenAPI specifications missing schemas and inconsistencies

aleb
New Contributor

Hi, I am struggling to generate client code starting from your openapi 3.0 specifications

The problem is that the openapi declares schemas which are not defined:

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'

Is it possible for you to integrate those schemas inside your API file?

On top of that I would also want to highlight some inconsistencies between the openapi file and the real exposed APIs:

  1. The controltoken_type property defined in control_token_request has a wrong SHOW_PIN value instead of REVEAL_PIN
  2. the /pins/reveal operation is missing the response schema, I would expect a schema which includes the PIN.
  3. The balances property inside the cardholder_balance is marked as required, and its type is always a cardholder_balance, creating a circular dependency. I would expect it not to be marked as required, or at least defined with a different model which excludes the nesting of another balances property.

These 3 inconsistencies are present both in the openapi 3.0, which I understand is in beta, and in the 2.0 which is not.

4 REPLIES 4

twalson
Community Manager
Community Manager

Hi! Thanks for your post in the Community. We are aware of some issues in Swagger and the OpenAPI specs, and believe this is a possible outcome of an OAS mismatch. Our Marqeta Engineers are working on this and we hope to resolve it soon. 

We will follow up when this is fixed. Thanks again!

aleb
New Contributor

Glad to hear that! Looking forward! Keep up the great work 

twalson
Community Manager
Community Manager

Hey there - our DX team got to work on this. It should be all fixed - https://github.com/marqeta/marqeta-openapi

Let me know if you run into any other issues. This is always valuable feedback!

- Tyler

aleb
New Contributor

Hi twalson. I can confirm the first issue about the missing schemas is now correctly fixed. The last three issues I listed are still present though:

  1. The controltoken_type property defined in control_token_request has a wrong SHOW_PIN value instead of REVEAL_PIN:

 

 

    control_token_request:
      properties:
        card_token:
          description: The unique identifier of the card for which you want to generate
            a control token.
          maxLength: 36
          minLength: 1
          type: string
        controltoken_type:
          description: |-
            Specifies the type of action completed by this request.

            *WARNING:* Sending a request to this endpoint with a `REVEAL_PIN` control token requires PCI DSS compliance.

            The lifespan of the control token depends on the token type:

            * *SET_PIN:* 60 minutes
            * *REVEAL_PIN:* 5 minutes
          enum:
            - SET_PIN
            - SHOW_PIN​

 

 

  • the /pins/reveal operation is missing the response schema, I would expect a schema which includes the PIN:

 

 

  /pins/reveal:
    post:
      description: |-
        Reveals the personal identification number (PIN) of an existing, active card.

        *WARNING:* Only use this endpoint to access a PIN in order to reveal it to its cardholder.
        Do not use this endpoint for the purpose of storing a PIN at any location.

        Sending a request to this endpoint requires PCI DSS compliance.
        You must comply with PCI DSS data security requirements if you want to store, transmit, or process sensitive card data such as the cardholder's primary account number (PAN), personal identification number (PIN), and card expiration date.

        If you want instead to update a card's PIN, send a `PUT` request to the `/pins` endpoint.
        See <</core-api/pins#putPins, Create or Update PIN>> on this page for details.

        Revealing a card's PIN is a two-step process.
        You must first create a new control token for the card by sending a `POST` request to `/pins/controltoken`, and then use that token to reveal the PIN.
      operationId: revealPins
      requestBody:
        content:
          application/json:
            example:
              cardholder_verification_method: BIOMETRIC_FINGERPRINT
              control_token: b4647c9a-d4b8-4091-a5ff-dd67a7bb9ffc
            schema:
              $ref: '#/components/schemas/pin_reveal_request'
        required: false
      responses:
        '204':
          content: {
            }
          description: PIN was successfully revealed​

 

 

  • The balances property inside the cardholder_balance is marked as required, and its type is always a cardholder_balance, creating a circular dependency. I would expect it not to be marked as required, or at least defined with a different model which excludes the nesting of another balances property:

 

 

    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​

 

 

I have also one final question, which is about the data models we should use for a webhook we are exposing, and that will receive transaction events from Marqeta. Are we safe in using the same TransactionModel which is currently returned by the transactions core API? Here the documentation says "See all transaction response fields in Transactions.", so I guess we are safe?