openapi: 3.0.3
info:
  title: Astrada bank-accounts card-verification API
  version: '2024-02-28'
  contact:
    email: developer@astrada.co
  description: 'Welcome to our API Reference. 👋

    '
servers:
- url: https://api.astrada.co
security: null
tags:
- name: card-verification
  description: Card Verification
paths:
  /card-verifications/unlock:
    post:
      tags:
      - card-verification
      summary: Unlock a card's verification attempt lockout
      description: 'Clear the cross-network verification **attempt lockout** for a card,

        identified by its `cardId`. This re-enables verification attempts for the

        card after it has been throttled by too many recent hard failures — the

        account-scoped, cross-network throttle that protects the non-HIGHEST tiers

        (Visa/Stripe, Mastercard/TNS). Idempotent: unlocking a card that has no

        active lock succeeds and clears nothing. The HIGHEST per-fingerprint lockout

        is **not** affected by this endpoint.

        '
      security:
      - main-auth:
        - subaccounts:write
      operationId: CardVerificationAttemptLockoutUnlock
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - cardId
              properties:
                cardId:
                  description: Identifier of the card whose attempt lockout to clear.
                  type: string
                  format: uuid
            examples:
              UnlockAttemptLockoutRequestExample:
                value:
                  cardId: 00cdba2d-01f0-46bb-b34a-c76d9699e991
      responses:
        '200':
          description: 'The card''s attempt lockout was cleared, or the card had no active lock

            (idempotent).

            '
          content:
            application/hal+json:
              schema:
                type: object
                required:
                - unlocked
                properties:
                  unlocked:
                    description: Always `true` on success.
                    type: boolean
                    enum:
                    - true
                  vaultCardFingerprint:
                    description: 'The provider-independent vault fingerprint that was cleared.

                      Present only when an active lock existed for the card.

                      '
                    type: string
              examples:
                UnlockAttemptLockoutResponseExample:
                  value:
                    unlocked: true
                    vaultCardFingerprint: 1f1d2c3b-4a5e-6f70-8192-a3b4c5d6e7f8
        '400':
          $ref: '#/components/responses/bad-request'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '500':
          $ref: '#/components/responses/server-error'
  /card-verifications/3ds:
    get:
      tags:
      - card-verification
      summary: List a card's 3DS verifications
      description: 'List the 3DS verifications for a card, most recent first. Use the optional `state`

        filter (e.g. `state=failed`) to retrieve only failed verifications — each failed

        verification carries a `failureReason` explaining why it failed. This includes

        cards declined synchronously at creation (the `POST` returned `400`): those

        attempts are persisted as failed verifications with `currentStepId: null`.

        '
      security:
      - main-auth:
        - card-verifications:read
      operationId: CardVerificationList
      parameters:
      - $ref: '#/components/parameters/card-id.required'
      - in: query
        name: state
        required: false
        description: Optional filter to retrieve only verifications in the given state.
        schema:
          type: string
          enum:
          - completed
          - failed
          - in-progress
      responses:
        '200':
          description: Successful operation
          content:
            application/hal+json:
              schema:
                type: object
                required:
                - _links
                - _embedded
                - totalItems
                properties:
                  _links:
                    type: object
                    required:
                    - self
                    properties:
                      self:
                        $ref: '#/components/schemas/link'
                  _embedded:
                    type: object
                    required:
                    - cardVerifications
                    properties:
                      cardVerifications:
                        type: array
                        items:
                          $ref: '#/components/schemas/card-verification'
                  totalItems:
                    type: integer
              examples:
                Example list filtered by state=failed:
                  value:
                    _links:
                      self:
                        href: /card-verifications/3ds?cardId=8309b5f8-d5d8-49bb-9001-38bf1bb0f1e4&state=failed
                    _embedded:
                      cardVerifications:
                      - _links:
                          self:
                            href: /card-verifications/3ds/9fab1bea-bc1e-4757-bd47-479422e5983b
                          steps:
                            href: /card-verifications/3ds/9fab1bea-bc1e-4757-bd47-479422e5983b/steps
                        id: 9fab1bea-bc1e-4757-bd47-479422e5983b
                        subaccountId: f297d659-c13d-4219-aeaa-e10a845140a5
                        cardId: 8309b5f8-d5d8-49bb-9001-38bf1bb0f1e4
                        type: 3DS
                        state: failed
                        authenticationFlow: frictionless
                        failureReason:
                          category: authentication_declined
                          description: The card issuer declined the 3-D Secure authentication.
                          retryable: true
                          code: '05'
                          providerMessage: The card issuer declined this authentication attempt.
                        createdAt: '2024-01-04T18:53:32.000Z'
                        updatedAt: '2024-01-04T18:55:12.000Z'
                    totalItems: 1
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '500':
          $ref: '#/components/responses/server-error'
  /card-verifications/3ds/{verificationId}:
    parameters:
    - $ref: '#/components/parameters/verification-id'
    get:
      tags:
      - card-verification
      summary: Retrieve 3DS verification
      description: Returns the current status and detailed information of a specific 3DS verification by its identifier.
      security:
      - main-auth:
        - card-verifications:read
      operationId: GetCardVerification
      responses:
        '200':
          description: Successful operation
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/card-verification'
              examples:
                Example Get Card Verification Response:
                  $ref: '#/components/examples/card-verification'
                Example Failed Verification with failureReason:
                  $ref: '#/components/examples/card-verification-failed'
        '400':
          $ref: '#/components/responses/bad-request'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/not-found'
        '500':
          $ref: '#/components/responses/server-error'
components:
  responses:
    bad-request:
      description: The server cannot or will not process the request due to something that is perceived to be a client error
      content:
        application/problem+json:
          schema:
            type: object
            properties:
              detail:
                type: string
              title:
                type: string
                enum:
                - Bad Request
              errors:
                type: array
                items:
                  type: object
                  properties:
                    title:
                      type: string
                    detail:
                      type: string
                  required:
                  - title
                  - detail
            required:
            - detail
            - title
          examples:
            Example Generic Bad Request Payload Response:
              value:
                title: Bad Request
                detail: Request object failed validation.
            Example Generic Bad Request Parameters Response:
              value:
                title: Bad Request
                detail: Request parameters are invalid.
    not-found:
      description: The requested resource was not found on the server
      content:
        application/problem+json:
          schema:
            type: object
            properties:
              type:
                type: string
              instance:
                type: string
              detail:
                type: string
              title:
                type: string
                enum:
                - Not Found
            required:
            - detail
            - title
          example:
            title: Not Found
            detail: The requested resource was not found on the server.
    unauthorized:
      description: Authentication credentials were either missing or incorrect
      content:
        application/problem+json:
          schema:
            type: object
            properties:
              detail:
                type: string
              title:
                type: string
                enum:
                - Unauthorized
            required:
            - detail
            - title
          example:
            title: Unauthorized
            detail: Authentication credentials were either missing or incorrect.
    forbidden:
      description: Authentication credentials used do not have have permissions to perform the request
      content:
        application/problem+json:
          schema:
            type: object
            properties:
              detail:
                type: string
              title:
                type: string
                enum:
                - Forbidden
            required:
            - detail
            - title
          example:
            title: Forbidden
            detail: You do not have permission to access the requested resource.
    server-error:
      description: The server encountered an unexpected condition that prevented it from fulfilling the request
      content:
        application/problem+json:
          schema:
            type: object
            properties:
              detail:
                type: string
              title:
                type: string
                enum:
                - Internal Server Error
            required:
            - detail
            - title
          example:
            title: Internal Server Error
            detail: The server encountered an unexpected condition that prevented it from fulfilling the request.
  schemas:
    card-verification:
      type: object
      properties:
        _links:
          type: object
          properties:
            self:
              $ref: '#/components/schemas/link'
              description: The link to this verification resource.
            steps:
              $ref: '#/components/schemas/link'
              description: The link to this verification's steps (`/card-verifications/3ds/{verificationId}/steps`).
            currentStep:
              $ref: '#/components/schemas/link'
              description: 'The link to the step the client should execute next. Absent once the

                verification reaches a terminal `state` (`completed` or `failed`).

                '
          required:
          - self
          - steps
        id:
          description: The unique identifier of the Verification entity.
          type: string
          format: uuid
        subaccountId:
          description: The unique identifier of the subaccount related to this entity.
          type: string
          format: uuid
        cardId:
          description: The unique identifier of the card related to this entity.
          type: string
          format: uuid
        type:
          description: Verification Step Type
          type: string
          enum:
          - 3DS
        currentStepId:
          description: 'The identifier of the next step the client should execute. `null` when

            the verification has no follow-up step — typically because the issuer

            supports frictionless authentication, or because the card did not

            require interactive 3DS. When `null`, `state` will be `completed` on the

            creation response and clients should not call any `/steps/...` endpoint.


            On retrieved/listed verifications, `currentStepId` is also `null` with

            `state: failed` when the card was declined synchronously at creation

            (the creation call returned `400`, and the attempt is persisted as a

            failed verification with its `failureReason`).


            For the HIGHEST tier, a frictionless 3DS outcome does NOT complete the

            verification: it returns `stripe-holds-pending` (the cardholder must

            initiate two small verification holds via `/steps/place-holds`), which

            then advances to `stripe-amount-confirm` (the cardholder reads the two

            amounts back via `/steps/amount-confirm`).

            '
          type: string
          nullable: true
          enum:
          - fingerprint
          - challenge
          - stripe-3ds
          - stripe-holds-pending
          - stripe-amount-confirm
          - null
        state:
          description: Current Verification state
          type: string
          enum:
          - completed
          - failed
          - in-progress
        clientSecret:
          description: Stripe SetupIntent or PaymentIntent client secret, used by the client to run `stripe.handleNextAction`. Returned whenever the verification is on the Stripe 3DS step — on the creation response (`POST /card-verifications/3ds`) and on the retrieve response (`GET /card-verifications/3ds/{verificationId}`) while `currentStepId` is `stripe-3ds`.
          type: string
        stripePublishableKey:
          description: Stripe publishable key to initialize Stripe.js on the client. Returned alongside `clientSecret` (creation response and retrieve response while `currentStepId` is `stripe-3ds`).
          type: string
        authenticationFlow:
          description: 'The 3DS authentication flow attested by the issuer, surfaced at the terminal state.

            `challenge` = the cardholder actively authenticated; `frictionless` = the issuer approved

            without interaction; `null` = 3DS was not engaged (e.g. a low-risk automatic skip).

            '
          type: string
          nullable: true
          enum:
          - challenge
          - frictionless
          - null
        failureReason:
          $ref: '#/components/schemas/failure-reason'
          description: 'Normalized, customer-facing reason the verification failed. Present only when

            `state` is `failed` — read it to triage the failure (category, retryability,

            and the issuer''s message). See the `FailureReason` schema.

            '
        createdAt:
          description: Date and time when this resource was created, in UTC, following ISO 8601 format.
          type: string
          format: date-time
        updatedAt:
          description: Date and time when this resource was last updated, in UTC, following ISO 8601 format.
          type: string
          format: date-time
      required:
      - id
      - subaccountId
      - cardId
      - type
      - state
      - createdAt
      - updatedAt
      - _links
    failure-reason:
      type: object
      description: 'Normalized, customer-facing reason a card verification failed. Present only when the

        verification `state` is `failed`. `category`, `description` and `retryable` are always

        present; `issuerMessage` and `acsReferences` appear only when the issuer returned them

        (typically on a frictionless decline — when the issuer renders its own challenge UI no

        per-attempt message is available).

        '
      properties:
        category:
          description: 'Stable, provider-agnostic failure category an integrator can branch on without

            enumerating raw issuer codes.

            '
          type: string
          enum:
          - authentication_declined
          - authentication_canceled
          - cvc_check_failed
          - card_declined
          - contact_issuer
          - card_blocked
          - too_many_attempts
          - not_supported
          - temporary_issue
          - processing_error
        description:
          description: Human-readable explanation of the failure, safe to relay to the cardholder.
          type: string
        retryable:
          description: Whether the cardholder can retry now and plausibly succeed.
          type: boolean
        issuerMessage:
          description: The issuer's own cardholder-facing message, when provided (frictionless declines only).
          type: string
        code:
          description: 'Raw provider reason code (e.g. a 3DS `transStatusReason` or a Stripe `decline_code`),

            surfaced for support escalation.

            '
          type: string
        providerMessage:
          description: 'The payment provider''s cardholder-safe message for the specific failure code (e.g.

            "Your card does not support this type of purchase."). Finer-grained than the

            category-level `description`; absent when the provider supplied none.

            '
          type: string
        adviceCode:
          description: 'The issuer''s advice code on authorization declines, verbatim from the payment

            provider. Documented values: `try_again_later`, `do_not_try_again`,

            `confirm_card_data`; values the provider introduces later pass through unchanged.

            Absent when the issuer gave no advice (e.g. 3-D Secure authentication failures).

            '
          type: string
        acsReferences:
          description: 3DS ACS reference identifiers, when returned by the issuer — useful when escalating to the issuer.
          type: object
          properties:
            acsTransactionId:
              type: string
            acsReferenceNumber:
              type: string
            dsTransactionId:
              type: string
      required:
      - category
      - description
      - retryable
    link:
      type: object
      properties:
        href:
          type: string
        templated:
          type: boolean
        type:
          type: string
        deprecation:
          type: string
        name:
          type: string
        profile:
          type: string
        title:
          type: string
        hreflang:
          type: string
      required:
      - href
  parameters:
    card-id.required:
      in: query
      name: cardId
      required: true
      schema:
        type: string
        format: uuid
      example: 8164683a-8d23-4421-9694-1a81fc9b9c37
    verification-id:
      in: path
      name: verificationId
      required: true
      schema:
        type: string
        format: uuid
      example: 9cac38a2-6584-4c1f-92fd-85223774979b
  examples:
    card-verification-failed:
      description: Example of a failed Card Verification, with a populated failureReason explaining why the 3DS verification failed.
      value:
        _links:
          self:
            href: /card-verifications/3ds/9fab1bea-bc1e-4757-bd47-479422e5983b
          steps:
            href: /card-verifications/3ds/9fab1bea-bc1e-4757-bd47-479422e5983b/steps
        id: 9fab1bea-bc1e-4757-bd47-479422e5983b
        subaccountId: f297d659-c13d-4219-aeaa-e10a845140a5
        cardId: 8309b5f8-d5d8-49bb-9001-38bf1bb0f1e4
        type: 3DS
        currentStepId: null
        state: failed
        authenticationFlow: frictionless
        failureReason:
          category: authentication_declined
          description: The card issuer declined the 3-D Secure authentication.
          retryable: true
          issuerMessage: Your bank declined this verification. Please contact your bank or try another card.
          code: '05'
          acsReferences:
            acsTransactionId: 8a880dc0-d2d2-4067-bcb1-b08d1690b26e
            acsReferenceNumber: ACME-ACS-2024-0042
            dsTransactionId: 97267598-fae6-494f-8453-2d3807e0c77f
        createdAt: '2024-01-04T18:53:32.000Z'
        updatedAt: '2024-01-04T18:55:12.000Z'
    card-verification:
      description: Example of Card Verification resource
      value:
        _links:
          self:
            href: /card-verifications/3ds/9fab1bea-bc1e-4757-bd47-479422e5983b
          steps:
            href: /card-verifications/3ds/9fab1bea-bc1e-4757-bd47-479422e5983b/steps
          currentStep:
            href: /card-verifications/3ds/9fab1bea-bc1e-4757-bd47-479422e5983b/steps/fingerprint
        id: 9fab1bea-bc1e-4757-bd47-479422e5983b
        subaccountId: f297d659-c13d-4219-aeaa-e10a845140a5
        cardId: 8309b5f8-d5d8-49bb-9001-38bf1bb0f1e4
        type: 3DS
        currentStepId: fingerprint
        state: in-progress
        createdAt: '2024-01-04T18:53:32.000Z'
        updatedAt: '2023-01-04T10:55:12.000Z'
  securitySchemes:
    main-auth:
      type: oauth2
      flows:
        implicit:
          authorizationUrl: https://api.astrada.co/auth/realms/{accountId}/protocol/openid-connect/token
          refreshUrl: https://api.astrada.co/auth/realms/{accountId}/protocol/openid-connect/token
          scopes:
            accounts:write: Accounts write resource
            accounts:read: Accounts read resource
            subaccounts:write: Subaccounts write resource
            subaccounts:read: Subaccounts read resource
            card-connector-data-links:write: card-connector-data-link resource
            card-connector-consents:read: Card Consent read resource
            card-connector-consents:write: Card Consent write resource
            webhooks:read: Read Webhook resources
            webhooks:write: Write Webhook resources
            card-subscriptions:write: Create card subscription
            card-subscriptions:read: Read card subscription
            card-verifications:write: Create card verification
            card-verifications:read: Read Card verification
            cards:read: Read Card resources
            cardholder:read: Read Cardholder resources
            cardholder:write: Write Cardholder resources
            transactions:read: Read Transaction resources
            transaction-messages:read: Read Transaction Message resources
            network-bulk-feeds:read: Read network bulk feed
            network-bulk-feeds:write: Write network bulk feed
            network-links:write: Write network link
            enrollment-methods:write: Write enrollment methods
            simulation:write: Write sandbox simulations
            banking:read: Read banking resources
            banking:write: Write banking resources
            banking:admin: Admin banking operations
            appstore:enrollment:write: Enroll cards via the appstore B2C flow
            appstore:cards:read: View enrolled cards in the appstore
            appstore:transactions:read: View synced transactions in the appstore
            appstore:transactions:sync: Trigger transaction sync in the appstore
            appstore:sessions:read: Read appstore session state
            appstore:sessions:write: Write or delete appstore session state
            appstore:tokens:read: Read appstore stored tokens and connections
            appstore:tokens:write: Write appstore stored tokens and connections
externalDocs:
  description: Find out more about Astrada API.
  url: https://docs.astrada.co/reference