Malga 3DS2 Malga API

openapi: 3.1.0
info:
  version: '0.5'
  title: Documentação Malga 3DS2 Malga API
  description: "# Authentication\n\nOs serviços de API da Malga são protegidos através de chaves de acesso. Você pode gerenciar suas chaves de acesso através do seu dashboard.\n\nÉ importante armazenar suas chaves de maneira privada e segura uma vez que elas possuem privilégios de alteração na sua conta. Não compartilhe suas chaves, não deixe elas fixadas no seu código e nem armazene elas no seu servidor de controle de versão. Recomendamos utilizar variáveis de ambiente secretas para deixar a chave disponível para sua aplicação.\n\nA Autenticação para todos os chamadas da API é feita através de headers HTTP, sendo necessário informar seu identificador de cliente na Malga e a chave secreta de acesso.\n\n## X-Client-ID\n\nIdentificador única da sua conta na Malga. Deve ser enviado no header obrigatóriamente em todas as requisições feitas a API.\n\n| Security Scheme Type | API Key |\n|-----------------------|-----------|\n| Header parameter name | `X-Client-ID` |\n\n## X-Api-Key\n\nSua chave de acesso a API. Funciona em par com o client-id devendo ser enviado no header obrigatóriamente em todas as requisições feitas a API.\n\n| Security Scheme Type | API Key |\n|-----------------------|-----------|\n| Header parameter name | `X-Api-Key` |\n\n## Exemplo de requisicão autenticada\n\n```bash\n  curl --location --request GET 'https://api.malga.io/v1/' \\\n    --header 'X-Client-Id: <YOUR_CLIENT_ID>' \\\n    --header 'X-Api-Key: <YOUR_SECRET_KEY>'\n```\n"
servers:
- url: https://api.malga.io
  description: Production
security:
- X-Client-ID: []
  X-Api-Key: []
tags:
- name: 3DS2 Malga
paths:
  /v1/charges/3ds/setup:
    post:
      tags:
      - 3DS2 Malga
      summary: Criar um novo setup
      operationId: create_setup
      requestBody:
        description: Criar sessão no 3DS2 Malga
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SetupRequest'
            examples:
              SetupRequest:
                $ref: '#/components/examples/SetupRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SetupResponse'
              examples:
                SetupResponse:
                  $ref: '#/components/examples/SetupResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-codeSamples:
      - lang: Python
        source: "import requests\n\nclient_id = <YOUR CLIENT ID>\npublic_key = <YOUR CLIENT TOKEN>\n\nrequest = requests.post('https://api.malga.io/v1/charges/3ds/setup', headers={\n    \"X-Client-Id\": client_id,\n    \"X-Api-Key\": publick_key\n  }, json={\n  \"sourceType\": \"card\",\n  \"cardId\": \"4918cfd2-b14a-4db2-ade4-d1b8a6bd40e2\",\n})\nprint(request.json().get('id'))\n"
components:
  schemas:
    ErrorItem:
      properties:
        type:
          type: string
          enum:
          - api_error
          - bad_request
          - invalid_request_error
          - card_declined
        code:
          type: integer
          description: Código HTTP do erro (por exemplo, `422` em erros de regra de negócio).
        declinedCode:
          type: string
          description: Código de retorno da transação em caso de falha na autorização
        key:
          type: string
          description: 'Chave estável que identifica o erro de negócio (ex.: `bank_identifier_required`). Útil para tratar o erro programaticamente, independente da mensagem traduzida.'
        businessCode:
          type: string
          description: 'Chave estável de regra de negócio retornada em `422`. Permite tratar o erro programaticamente independente da mensagem traduzida. Exemplos em sessões: `pix_boleto_multiple_payments_not_allowed`, `pix_boleto_one_to_one_reactivation_blocked`, `platform_fee_exceeds_link_amount`, `session_disabled`, `multiple_payments_limit_reached`.

            '
        message:
          type: string
          description: Descrição breve do erro
        details:
          type: array
          description: Lista contendo objetos que detalham o erro de validação
    SetupRequest:
      type: object
      description: Dados para criar um setup
      oneOf:
      - $ref: '#/components/schemas/SourceTypeCardObject'
      - $ref: '#/components/schemas/SourceTypeTokenObject'
      example:
        sourceType: card
        cardId: 148d5db0-f1c3-439f-902d-f1f268086e1d
    ErrorResponse:
      properties:
        error:
          type: object
          allOf:
          - $ref: '#/components/schemas/ErrorItem'
    SetupResponse:
      properties:
        id:
          type: string
          format: uuid
          description: Identificador do setup
        token:
          type: string
          description: Token gerado no provedor 3DS, será utilizado na coleta de dados
        collectUrl:
          type: string
          format: url
          description: URL do provedor 3DS, será utilizado na coleta de dados
        providerType:
          type: string
          description: Informa qual provedor 3DS2 está sendo utilizado
        error:
          properties:
            type:
              type: string
              enum:
              - api_error
              - bad_request
              - invalid_request_error
              - card_declined
            declinedCode:
              type: string
              description: Código de retorno da transação em caso de falha na autorização
            message:
              type: string
              description: Descrição breve do erro
            details:
              type: array
              description: Lista contendo objetos que detalham o erro de validação
    SourceTypeCardObject:
      title: Cartão de crédito
      type: object
      description: Dados para cobrança por cartão de crédito salve
      properties:
        sourceType:
          type: string
          description: Tipo da origem da cobrança
          enum:
          - card
        cardId:
          type: string
          format: uuid
          description: Identificador do cartão quando source tipo card
      required:
      - sourceType
      - cardId
    SourceTypeTokenObject:
      title: Cartão tokenizado
      type: object
      description: Dados para cobrança única de token de cartão
      properties:
        sourceType:
          type: string
          description: Tipo da origem da cobrança, usar `token` para cobrança no token gerado
          enum:
          - token
        tokenId:
          type: string
          format: uuid
          description: Identificador do token quando source tipo token (opcional)
      required:
      - sourceType
      - tokenId
  examples:
    SetupResponse:
      value:
        id: 1b04367a-2386-4161-8c90-eac82267ee89
        token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiI0MzljZGU0NC05M2RkLTQ2ZWEtYWU0OC0zNTMwMzg3NGFjMmQiLCJpYXQiOjE3Mjc3MTU5NDksImlzcyI6IjVkZDgzYmYwMGU0MjNkMTQ5OGRjYmFjYSIsImV4cCI6MTcyNzcxOTU0OSwiT3JnVW5pdElkIjoiNjU0NDUzNzkzZDJmNTM1NWE3YjljN2IxIiwiUmVmZXJlbmNlSWQiOiJhNjNhZTI0NS0zNzJkLTQ1ODktODVlYS1iMDBmM2VmNjA0NGYifQ.o4IKYrNnFbr3xn-qSm_9qL-Sn-WvCpKOUMxZna7SiYE
        collectUrl: https://centinelapistag.cardinalcommerce.com/V1/Cruise/Collect
        providerType: CYBERSOURCE
    SetupRequest:
      summary: Exemplo de criação de sessão do 3DS2 Malga
      value:
        sourceType: card
        cardId: cc0b1e41-2936-45c5-947f-93995ffcdc00
  securitySchemes:
    X-Client-ID:
      type: apiKey
      in: header
      name: X-Client-Id
    X-Api-Key:
      type: apiKey
      in: header
      name: X-Api-Key
x-tagGroups:
- name: API Key
  tags:
  - Client-token
- name: Cartões
  tags:
  - Tokens
  - Cards
- name: Pagamentos
  tags:
  - Customers
  - Charges
  - Sessions
  - Sellers
  - Vendors
  - Split
  - 3DSecure2
  - Settings
- name: Notificação e eventos
  tags:
  - Webhooks
- name: Provedores
  tags:
  - Merchants
  - Providers
- name: Gestão de pagamentos
  tags:
  - Flows
- name: Exportar Dados
  tags:
  - Reports
- name: Apêndice
  tags:
  - Tabelas de tipos