Details

--- openapi: 3.0.0 info: version: '0.0' title: Cards Details servers: - url: 'https://{API_ENVIRONMENT}/a/consumer/api/v0' variables: API_ENVIRONMENT: default: digital.garden-fi.com description: FI specific hostname tags: - name: Basic Cards description: Basic Card Functionality - name: Advanced Cards description: Advanced card configuration - name: Travel Notices description: Creation, editing, and deletion of travel notices paths: '/users/{userId}/cards': get: tags: - Basic Cards description: >- Returns (OnDot and Passport) debit and (OnDot only) credit cards. security: - OpenID_Connect: - 'https://api.banno.com/consumer/auth/cardcontrols.readonly' - 'https://api.banno.com/consumer/auth/cardcontrols.readwrite' parameters: - in: path name: userId description: ID of the Banno user required: true schema: type: string format: uuid example: "00000000-0000-0000-0000-000000000000" responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/GetCardsResponse' '404': description: Not found '500': description: Server error '/users/{userId}/cards/{cardId}/{cardType}/status': put: tags: - Basic Cards description: >- Wraps existing update endpoint and uses OnDot on/off (if applicable) security: - OpenID_Connect: - 'https://api.Banno.com/consumer/auth/cardcontrols.readwrite' parameters: - in: path name: userId description: ID of the Banno user required: true schema: type: string format: uuid example: 00000000-0000-0000-0000-000000000000 - in: path name: cardId description: ID of the Banno card required: true schema: type: string format: uuid example: 00000000-0000-0000-0000-000000000000 - in: path name: cardType description: Type of card required: true schema: $ref: '#/components/schemas/CardType' requestBody: content: application/json: schema: type: object properties: status: type: string enum: - Activate - On - Off - Reordered - Lost - Stolen creditCardLostState: type: string description: >- State Abreviation (e.g. CO, IA, IL) for a credit card. This value is optional and will default to the state the user lives in. This field is only used when updating a credit card to lost or stolen. This value should be used to indicate which state the card was lost in. responses: '200': description: Card updated. content: application/json: schema: type: object required: - data properties: data: type: object required: - availableCardActions - display properties: availableCardActions: $ref: '#/components/schemas/AvailableCardActions' display: $ref: '#/components/schemas/CardDisplay' '400': description: >- The request was malformed. If this update is a 'report lost' but the user does not have a known address with a known state, the title of the error will be "User record missing address."" content: application/problem+json: schema: "$ref": "#/components/schemas/RFC7807ErrorResponse" '403': description: >- The associated institution is not supported '404': description: >- The user or card not found or the user is not authorized to view this resource '500': description: Internal error '/users/{userId}/cards/advanced/configuration': get: tags: - Advanced Cards description: Get the configured alerts and controls for all cards security: - OpenID_Connect: - 'https://api.Banno.com/consumer/auth/cardcontrols.readonly' - 'https://api.Banno.com/consumer/auth/cardcontrols.readwrite' parameters: - in: path name: userId description: ID of the Banno user required: true schema: type: string format: uuid example: 00000000-0000-0000-0000-000000000000 responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/GetCardsConfigurationResponse' '/users/{userId}/cards/{cardId}/{cardType}/advanced/configuration': put: tags: - Advanced Cards description: Set the configured alerts and controls for all cards security: - OpenID_Connect: - 'https://api.Banno.com/consumer/auth/cardcontrols.readwrite' parameters: - in: path name: userId description: ID of the Banno user required: true schema: type: string format: uuid example: 00000000-0000-0000-0000-000000000000 - in: path name: cardId description: ID of the card with advanced card controls enabled required: true schema: type: string format: uuid example: 00000000-0000-0000-0000-000000000000 - in: path name: cardType description: ID of the card with advanced card controls enabled required: true schema: $ref: '#/components/schemas/CardType' requestBody: content: application/json: schema: $ref: '#/components/schemas/PutCardsConfigurationRequest' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/PutCardsConfigurationResponse' '400': description: Bad request '401': description: >- Failed to provide a valid fully authenticated JWT or the path's userId does not match the JWT-extracted userId '403': description: User or card cannot modify advanced card configuration '404': description: The user or card was not found '500': description: Internal error '/users/{userId}/cards/{cardId}/travel-notice': put: tags: - Travel Notices description: Applies the given travel notice to the card security: - OpenID_Connect: - 'https://api.banno.com/consumer/auth/travelnotice.write' parameters: - in: path name: userId description: ID of the Banno user required: true schema: type: string format: uuid example: 00000000-0000-0000-0000-000000000000 - in: path name: cardId description: ID of the Banno card required: true schema: type: string format: uuid example: 00000000-0000-0000-0000-000000000000 requestBody: content: application/json: schema: $ref: '#/components/schemas/UpdateTravelNoticeCommand' responses: '204': description: Travel notice updated '400': description: Malformed JSON or date/comment field validation failure '401': description: >- Failed to provide a valid fully authenticated JWT or the path's userId does not match JWT-extracted userId '403': description: User is not permitted to use the Travel Notices feature '404': description: The user or card not found '500': description: Internal error delete: tags: - Travel Notices description: Deletes the current travel notice on the card security: - OpenID_Connect: - 'https://api.banno.com/consumer/auth/travelnotice.write' parameters: - in: path name: userId description: ID of the Banno user required: true schema: type: string format: uuid example: 00000000-0000-0000-0000-000000000000 - in: path name: cardId description: ID of the Banno card required: true schema: type: string format: uuid example: 00000000-0000-0000-0000-000000000000 responses: '204': description: Travel notice deleted '400': description: Malformed JSON sent '401': description: >- Failed to provide a valid fully authenticated JWT or path's userId does not match the JWT-extracted userId '403': description: User is not permitted to use the Travel Notices feature '404': description: The user or card not found '500': description: Internal error components: securitySchemes: OpenID_Connect: type: openIdConnect description: OpenID Connect - Discovery endpoint will be institution specific openIdConnectUrl: >- https://digital.garden-fi.com/a/consumer/api/v0/oidc/.well-known/openid-configuration schemas: PutCardsConfigurationRequest: type: object required: - selectedNotifyDeliveryOptions - selectedBlockDeliveryOptions - configurations properties: selectedNotifyDeliveryOptions: type: array items: $ref: '#/components/schemas/DeliveryOption' selectedBlockDeliveryOptions: type: array items: $ref: '#/components/schemas/DeliveryOption' configurations: $ref: '#/components/schemas/PutCardAlertConfig' GetCardsConfigurationResponse: type: object properties: data: type: array items: $ref: '#/components/schemas/AdvancedCardConfiguration' PutCardsConfigurationResponse: type: object description: >- PUT response object, the AdvancedCardConfiguration is required, while the failures are optional. The failures object indicates some of the updates did not go through required: - data properties: data: $ref: '#/components/schemas/AdvancedCardConfiguration' failures: $ref: '#/components/schemas/PutCardsConfigurationFailures' PutCardsConfigurationFailures: type: object description: >- This object indicates some of the updates did not go through. All the following fields are optional based on if they failed or not, if this object is present one of these fields needs to be supplied as non-optional properties: allTransactions: type: string description: >- All Transactions failure, if value supplied then this control failed to update example: error international: type: string description: >- International failure, if value supplied then this control failed to update example: error transactionTypes: type: array description: >- Transaction Type failures, will return failures for specific rule updates items: type: integer description: >- ID matches the ID of the failed merchant/transaction rule type. merchantTypes: type: array description: >- Merchant Type failures, will return failures for specific rule updates items: type: integer description: >- ID matches the ID of the failed merchant/transaction rule type. spendingLimitByMonth: $ref: '#/components/schemas/PutFailureSpendingLimitItem' spendingLimitByTransaction: $ref: '#/components/schemas/PutFailureSpendingLimitItem' AdvancedCardConfiguration: type: object required: - type - availableDeliveryOptions - selectedNotifyDeliveryOptions - selectedBlockDeliveryOptions - configurations - cardNumber - cardId - commonName - display properties: type: $ref: '#/components/schemas/CardType' commonName: type: string example: George Washington cardId: $ref: '#/components/schemas/CardId' cardNumber: $ref: '#/components/schemas/MaskedCardNumber' availableDeliveryOptions: type: array items: $ref: '#/components/schemas/DeliveryOption' selectedNotifyDeliveryOptions: type: array items: $ref: '#/components/schemas/DeliveryOption' selectedBlockDeliveryOptions: type: array items: $ref: '#/components/schemas/DeliveryOption' configurations: $ref: '#/components/schemas/CardAlertConfig' display: $ref: '#/components/schemas/CardDisplay' DeliveryOption: type: string enum: - SMS - PUSH - EMAIL PutCardAlertConfig: type: object properties: allTransactions: $ref: '#/components/schemas/State' international: $ref: '#/components/schemas/State' transactionTypes: type: array items: $ref: '#/components/schemas/PutDiscretePreference' merchantTypes: type: array items: $ref: '#/components/schemas/PutDiscretePreference' spendingLimitByMonth: $ref: '#/components/schemas/ContinuousPreference' spendingLimitByTransaction: $ref: '#/components/schemas/ContinuousPreference' CardAlertConfig: type: object properties: allTransactions: $ref: '#/components/schemas/State' international: $ref: '#/components/schemas/State' transactionTypes: type: array items: $ref: '#/components/schemas/DiscretePreference' merchantTypes: type: array items: $ref: '#/components/schemas/DiscretePreference' spendingLimitByMonth: $ref: '#/components/schemas/ContinuousPreference' spendingLimitByTransaction: $ref: '#/components/schemas/ContinuousPreference' PutDiscretePreference: type: object description: >- Represents preferences like merchant and transaction types which use discrete values to specify thresholds for alerts and controls required: - id - state properties: id: type: number state: $ref: '#/components/schemas/State' PutFailureSpendingLimitItem: type: object description: >- Spending limits failures, properties are non-null if an error occurred properties: block: type: string description: the notification limit failed to update example: error notify: description: the blocking limit failed to update type: string example: error DiscretePreference: type: object description: >- Represents preferences like merchant and transaction types which use discrete values to specify thresholds for alerts and controls required: - id - name - state - description properties: id: type: number description: type: string description: >- Banno supplied elaboration on what the category represents name: type: string example: Category Name state: $ref: '#/components/schemas/State' State: enum: - BLOCK - NOTIFY - NONE example: BLOCK ContinuousPreference: type: object description: >- Represents preferences like spending limits that use a continuous value to specify thresholds for alerts and controls required: - id properties: id: type: number blockAmount: type: number example: 100 notifyAmount: type: number example: 100 CardId: type: string format: uuid description: >- Banno identifier for the debit card. For credit cards, the card id is equivalent to the account id. MaskedCardNumber: type: string description: A masked representation of the card number example: XXXXX1234 GetCardsResponse: type: object required: - data properties: data: type: array items: oneOf: - $ref: '#/components/schemas/DebitCard' - $ref: '#/components/schemas/CreditCard' BaseCard: type: object required: - id - name - number - type - availableCardActions - canManageTravelNotices properties: id: $ref: '#/components/schemas/CardId' name: type: string example: Jane Doe number: $ref: '#/components/schemas/MaskedCardNumber' type: $ref: '#/components/schemas/CardType' availableCardActions: $ref: '#/components/schemas/AvailableCardActions' canManageTravelNotices: type: boolean description: Indicates whether a user can create / manage travel notices. travelNotice: $ref: '#/components/schemas/TravelNotice' display: $ref: '#/components/schemas/CardDisplay' DebitCard: allOf: - $ref: '#/components/schemas/BaseCard' - type: object required: - accountIds properties: type: enum: - Debit accountIds: type: array items: type: string format: uuid CreditCard: allOf: - $ref: '#/components/schemas/BaseCard' - type: object required: - accountId properties: type: enum: - Credit accountId: type: string format: uuid isPrimary: type: boolean description: indicates that this credit cards is the primary credit card for the underlying account. UpdateTravelNoticeCommand: type: object required: - startDate - endDate - comment properties: startDate: type: string format: date endDate: type: string format: date comment: type: string description: >- A user supplied comment. Max length determined by provided configuration value. example: Vacationing in Spain TravelNotice: type: object required: - startDate - endDate properties: startDate: type: string format: date endDate: type: string format: date comment: type: string description: >- A user supplied comment. Max length determined by provided configuration value. example: Vacationing in Spain AvailableCardActions: type: object description: >- Returns the set of card actions that are not dependent on the presence of any advanced card state required: - canReportLostStolen - canReorder - canActivateNew - canManageAlertsAndProtections - canManageTravelNotices - digitalProvisioning properties: canReportLostStolen: type: boolean description: Can the user report this card lost or stolen? canReorder: type: boolean description: Can the user reorder this card? canActivateNew: type: boolean description: Can the user activate this card? canManageAlertsAndProtections: type: boolean description: Can the user navigate the the advanced card controls UI? canManageTravelNotices: type: boolean description: Can the user manage travel notices on the card? digitalProvisioning: description: >- List of zero or more digital provisioning integrations available for the card. $ref: '#/components/schemas/DigitalProvisioningConfiguration' CardDisplay: type: object description: >- Returns the display properties. This occurs on the V2 endpoint for FIs that don't have advanced cards and always on the advanced configuration endpoint required: - shouldDisplayToggle - isCardToggleActive - cardStateCategory - friendlyStatus properties: shouldDisplayToggle: type: boolean description: >- Does the card have the ability to lock/unlock the card? if true card has the ability, if false card does not have the ability. isCardToggleActive: type: boolean description: >- Is the toggle in the active/on state? if true card toggle is on, if false and shouldDisplayToggle is true then the toggle is off cardStateCategory: type: string description: Additional classification of the card status by severity enum: - NORMAL - INFO - WARNING friendlyStatus: type: string description: Friendly description of the card status for display example: Locked supportMessage: type: string description: If applicable, text to prompt the user to contact the FI example: >- This card can no longer be used, contact us to order a new one. CardType: type: string enum: - Credit - Debit DigitalProvisioningConfiguration: type: array description: >- The institution's configured digital provisioning integrations uniqueItems: true items: type: string enum: - MastercardTokenConnect - VisaWallet RFC7807ErrorResponse: type: object description: >- A description of the error. This value will conform to a RFC 7807 http problem. additionalProperties: true properties: title: type: string description: >- A high level description of the problem. This description will not be specific to this instance of the prbolem. detail: type: string description: >- A specific description of the problem and why it occurred.