> ## Documentation Index
> Fetch the complete documentation index at: https://developers.portao3.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Answer a 3D Secure challenge

> Answers a 3D Secure challenge with the cardholder's decision.

Send the challenge's `_id` as `threedsTransactionId`, when the cardholder answered and what they answered. The card issuer then approves or declines the purchase, and `status` tells you which. A challenge can be answered only once, within 5 minutes of arriving — unless the issuer doesn't accept the answer (`INVALID_TRANSACTION`, `NOT_AUTHORIZED`), which keeps it pending.

Admins of the organization can answer any challenge of the account; other users only those of the wallets they own.


## OpenAPI

````yaml /api-reference/banking.openapi.json post /realms/{realmId}/organizations/{organizationId}/accounts/{accountId}/threeds/submit
openapi: 3.0.3
info:
  title: Banking
  version: 1.0.0
  description: >-
    Portão 3 banking API. Every endpoint requires a bearer token in the
    Authorization header (Authorization: Bearer <token>) unless its page states
    otherwise; see the Authentication guide. That requirement is not repeated
    per endpoint. Generated by tools/openapi from code (routes + security) and
    the hand-written spec (request/response bodies). Banking attaches a zod
    validationSchema at the route; request bodies are resolved from it (object +
    array roots). Responses have no presenter layer, so they stay tier=unknown.
    Confidence tiers: generated:typed=215 copied:manual=4 unknown=52.
servers:
  - url: https://api.banking.v2.portao3.com.br/
    description: production
  - url: https://api.banking.dev.3pers.com.br/
    description: development
security: []
tags:
  - name: Accounts
  - name: Account Limits
  - name: Wallets
  - name: Cards
  - name: Card Limits
  - name: Cards 3DS
  - name: PIX
  - name: PIX Keys (DICT)
  - name: PIX Charges
  - name: PIX Automatic
  - name: PIX Initiation (Open Finance)
  - name: PIX Infractions (MED)
  - name: Boleto
  - name: Boleto Charges
  - name: TED
  - name: Transfers
  - name: Transactions
  - name: Cashback
  - name: Currency Codes
  - name: Reversals
paths:
  /realms/{realmId}/organizations/{organizationId}/accounts/{accountId}/threeds/submit:
    post:
      tags:
        - Cards 3DS
      summary: Answer a 3D Secure challenge
      description: Answers a 3D Secure challenge with the cardholder's decision.
      operationId: >-
        postRealmsByRealmIdOrganizationsByOrganizationIdAccountsByAccountIdThreedsSubmit
      parameters:
        - name: realmId
          in: path
          required: true
          description: |-
            ID of your realm.

            Format: `UUID`
          schema:
            type: string
            format: uuid
          example: f495ff0c-ab54-4f99-8e92-ca8682e4de9b
        - name: organizationId
          in: path
          required: true
          description: |-
            ID of the organization the account belongs to.

            Format: `UUID`
          schema:
            type: string
            format: uuid
          example: c4bd3f21-dfbd-44e8-8055-68ba15bed410
        - name: accountId
          in: path
          required: true
          description: ID of the organization's account (24 hexadecimal characters).
          schema:
            type: string
            pattern: ^[0-9a-fA-F]{24}$
          example: 66f2a1c7b4d3e80012c9a0b4
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                threedsTransactionId:
                  type: string
                  pattern: ^[0-9a-fA-F]{24}$
                  description: >-
                    ID of the challenge you answer — the `_id` of a challenge
                    returned by the list-3D-Secure-challenges endpoint.
                  example: 66f2a6d4b4d3e80012c9a101
                authenticationTime:
                  type: string
                  format: date-time
                  pattern: >-
                    ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
                  description: >-
                    When the cardholder answered, as an ISO 8601 date-time (UTC
                    or with an offset).
                  example: '2026-11-02T14:31:07Z'
                authenticationResult:
                  type: string
                  enum:
                    - VALID_BIOMETRICS_AND_TRANSACTION
                    - NOT_VALID_BIOMETRICS
                    - TRANSACTION_DONT_RECOGNIZED
                  description: >-
                    The cardholder's answer: `VALID_BIOMETRICS_AND_TRANSACTION`
                    (verified, and confirms the purchase),
                    `NOT_VALID_BIOMETRICS` (the cardholder couldn't be verified)
                    or `TRANSACTION_DONT_RECOGNIZED` (the cardholder doesn't
                    recognize the purchase).
                  example: VALID_BIOMETRICS_AND_TRANSACTION
              required:
                - threedsTransactionId
                - authenticationTime
                - authenticationResult
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                      - TRANSACTION_AUTHENTICATED
                      - TRANSACTION_DECLINED
                      - INVALID_TRANSACTION
                      - NOT_AUTHORIZED
                    description: >-
                      `TRANSACTION_AUTHENTICATED` (the purchase is approved),
                      `TRANSACTION_DECLINED` (it is declined),
                      `INVALID_TRANSACTION` or `NOT_AUTHORIZED` (the answer
                      wasn't accepted — the challenge stays pending and you can
                      answer it again while it is valid).
                    example: TRANSACTION_AUTHENTICATED
                required:
                  - status
                description: The card issuer's verdict on an answered challenge.
        '400':
          description: >-
            `THREE_DS_TRANSACTION_EXPIRED` — More than 5 minutes have passed
            since the challenge arrived.
          content:
            application/json:
              schema:
                type: object
                properties:
                  traceId:
                    type: string
                    description: >-
                      Identifier of the request that failed. Quote it when
                      contacting support.
                    example: 1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b
                  code:
                    type: string
                    enum:
                      - THREE_DS_TRANSACTION_EXPIRED
                    description: >-
                      Stable, machine-readable error code. Branch on this, never
                      on `message`.
                  origin:
                    type: string
                    enum:
                      - BANKING
                    description: Service that produced the error.
                  message:
                    type: string
                    description: >-
                      Human-readable explanation. Its wording may change without
                      notice.
                required:
                  - traceId
                  - code
                  - origin
                  - message
              example:
                traceId: 1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b
                code: THREE_DS_TRANSACTION_EXPIRED
                origin: BANKING
                message: 3DS transaction has expired
        '403':
          description: >-
            `THREE_DS_USER_NOT_AUTHORIZED` — You are not an admin of the
            organization nor the owner of the card's wallet.
          content:
            application/json:
              schema:
                type: object
                properties:
                  traceId:
                    type: string
                    description: >-
                      Identifier of the request that failed. Quote it when
                      contacting support.
                    example: 1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b
                  code:
                    type: string
                    enum:
                      - THREE_DS_USER_NOT_AUTHORIZED
                    description: >-
                      Stable, machine-readable error code. Branch on this, never
                      on `message`.
                  origin:
                    type: string
                    enum:
                      - BANKING
                    description: Service that produced the error.
                  message:
                    type: string
                    description: >-
                      Human-readable explanation. Its wording may change without
                      notice.
                required:
                  - traceId
                  - code
                  - origin
                  - message
              example:
                traceId: 1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b
                code: THREE_DS_USER_NOT_AUTHORIZED
                origin: BANKING
                message: User is not authorized to authenticate this transaction
        '404':
          description: >-
            `THREE_DS_TRANSACTION_NOT_FOUND` — No challenge with this ID exists
            in the account.
          content:
            application/json:
              schema:
                type: object
                properties:
                  traceId:
                    type: string
                    description: >-
                      Identifier of the request that failed. Quote it when
                      contacting support.
                    example: 1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b
                  code:
                    type: string
                    enum:
                      - THREE_DS_TRANSACTION_NOT_FOUND
                    description: >-
                      Stable, machine-readable error code. Branch on this, never
                      on `message`.
                  origin:
                    type: string
                    enum:
                      - BANKING
                    description: Service that produced the error.
                  message:
                    type: string
                    description: >-
                      Human-readable explanation. Its wording may change without
                      notice.
                required:
                  - traceId
                  - code
                  - origin
                  - message
              example:
                traceId: 1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b
                code: THREE_DS_TRANSACTION_NOT_FOUND
                origin: BANKING
                message: 3DS transaction not found
        '409':
          description: >-
            `THREE_DS_TRANSACTION_ALREADY_PROCESSED` — The challenge was already
            answered.
          content:
            application/json:
              schema:
                type: object
                properties:
                  traceId:
                    type: string
                    description: >-
                      Identifier of the request that failed. Quote it when
                      contacting support.
                    example: 1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b
                  code:
                    type: string
                    enum:
                      - THREE_DS_TRANSACTION_ALREADY_PROCESSED
                    description: >-
                      Stable, machine-readable error code. Branch on this, never
                      on `message`.
                  origin:
                    type: string
                    enum:
                      - BANKING
                    description: Service that produced the error.
                  message:
                    type: string
                    description: >-
                      Human-readable explanation. Its wording may change without
                      notice.
                required:
                  - traceId
                  - code
                  - origin
                  - message
              example:
                traceId: 1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b
                code: THREE_DS_TRANSACTION_ALREADY_PROCESSED
                origin: BANKING
                message: 3DS transaction has already been processed
        '422':
          description: >-
            `BAD_REQUEST` — A path parameter is not a valid ID or the body
            failed validation; `fields` lists each offending field.
          content:
            application/json:
              schema:
                type: object
                properties:
                  traceId:
                    type: string
                    description: >-
                      Identifier of the request that failed. Quote it when
                      contacting support.
                    example: 1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b
                  code:
                    type: string
                    enum:
                      - BAD_REQUEST
                    description: >-
                      Stable, machine-readable error code. Branch on this, never
                      on `message`.
                  origin:
                    type: string
                    enum:
                      - BANKING
                    description: Service that produced the error.
                  message:
                    type: string
                    description: >-
                      Human-readable explanation. Its wording may change without
                      notice.
                  fields:
                    type: array
                    description: >-
                      One entry per invalid request field (validation errors
                      only).
                    items:
                      type: object
                      properties:
                        field:
                          type: string
                          description: >-
                            Path of the invalid field, e.g. `label` or
                            `values[0].value`.
                          example: label
                        message:
                          type: string
                          description: Why the field was rejected.
                          example: label is required
                        code:
                          type: string
                          description: >-
                            `<FIELD>_<REASON>` — e.g. `LABEL_REQUIRED`,
                            `TYPE_ONE_OF`, `VALUES_VALUE_TYPE_ERROR`.
                          example: LABEL_REQUIRED
                        values:
                          type: array
                          items:
                            type: string
                          description: >-
                            The accepted values, when the field is an
                            enumeration.
                      required:
                        - field
                        - message
                        - code
                required:
                  - traceId
                  - code
                  - origin
                  - message
              example:
                traceId: 1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b
                code: BAD_REQUEST
                origin: BANKING
                message: >-
                  Bad Request: Your request is invalid or incomplete. Please
                  make sure you are requesting with the right fields.
                fields:
                  - field: threedsTransactionId
                    message: 'Invalid input: expected string, received undefined'
                    code: THREEDSTRANSACTIONID_REQUIRED
        '500':
          description: >-
            `BANKING_PROVIDER_UNAVAILABLE` — The card issuer failed, or its
            answer never arrived. Retry while the challenge is valid.
          content:
            application/json:
              schema:
                type: object
                properties:
                  traceId:
                    type: string
                    description: >-
                      Identifier of the request that failed. Quote it when
                      contacting support.
                    example: 1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b
                  code:
                    type: string
                    enum:
                      - BANKING_PROVIDER_UNAVAILABLE
                    description: >-
                      Stable, machine-readable error code. Branch on this, never
                      on `message`.
                  origin:
                    type: string
                    enum:
                      - BANKING
                    description: Service that produced the error.
                  message:
                    type: string
                    description: >-
                      Human-readable explanation. Its wording may change without
                      notice.
                required:
                  - traceId
                  - code
                  - origin
                  - message
              example:
                traceId: 1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b
                code: BANKING_PROVIDER_UNAVAILABLE
                origin: BANKING
                message: Banking provider temporarily unavailable, please retry
        '502':
          description: >-
            `BANKING_PROVIDER_UNAVAILABLE` — The card issuer answered with a
            server error. Retry while the challenge is valid.
          content:
            application/json:
              schema:
                type: object
                properties:
                  traceId:
                    type: string
                    description: >-
                      Identifier of the request that failed. Quote it when
                      contacting support.
                    example: 1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b
                  code:
                    type: string
                    enum:
                      - BANKING_PROVIDER_UNAVAILABLE
                    description: >-
                      Stable, machine-readable error code. Branch on this, never
                      on `message`.
                  origin:
                    type: string
                    enum:
                      - BANKING
                    description: Service that produced the error.
                  message:
                    type: string
                    description: >-
                      Human-readable explanation. Its wording may change without
                      notice.
                required:
                  - traceId
                  - code
                  - origin
                  - message
              example:
                traceId: 1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b
                code: BANKING_PROVIDER_UNAVAILABLE
                origin: BANKING
                message: Banking provider temporarily unavailable, please retry
        '503':
          description: >-
            `BANKING_PROVIDER_UNAVAILABLE` — The card issuer is unavailable.
            Retry while the challenge is valid.
          content:
            application/json:
              schema:
                type: object
                properties:
                  traceId:
                    type: string
                    description: >-
                      Identifier of the request that failed. Quote it when
                      contacting support.
                    example: 1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b
                  code:
                    type: string
                    enum:
                      - BANKING_PROVIDER_UNAVAILABLE
                    description: >-
                      Stable, machine-readable error code. Branch on this, never
                      on `message`.
                  origin:
                    type: string
                    enum:
                      - BANKING
                    description: Service that produced the error.
                  message:
                    type: string
                    description: >-
                      Human-readable explanation. Its wording may change without
                      notice.
                required:
                  - traceId
                  - code
                  - origin
                  - message
              example:
                traceId: 1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b
                code: BANKING_PROVIDER_UNAVAILABLE
                origin: BANKING
                message: Banking provider temporarily unavailable, please retry
        '504':
          description: >-
            `BANKING_PROVIDER_UNAVAILABLE` — The card issuer didn't answer in
            time. Retry while the challenge is valid.
          content:
            application/json:
              schema:
                type: object
                properties:
                  traceId:
                    type: string
                    description: >-
                      Identifier of the request that failed. Quote it when
                      contacting support.
                    example: 1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b
                  code:
                    type: string
                    enum:
                      - BANKING_PROVIDER_UNAVAILABLE
                    description: >-
                      Stable, machine-readable error code. Branch on this, never
                      on `message`.
                  origin:
                    type: string
                    enum:
                      - BANKING
                    description: Service that produced the error.
                  message:
                    type: string
                    description: >-
                      Human-readable explanation. Its wording may change without
                      notice.
                required:
                  - traceId
                  - code
                  - origin
                  - message
              example:
                traceId: 1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b
                code: BANKING_PROVIDER_UNAVAILABLE
                origin: BANKING
                message: Banking provider did not respond in time, please retry

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.