openapi: 3.0.0
info:
  title: Wallet / Cards API
  description: |
    API for managing virtual cards, digital gift cards and transactions

    # Changelog

    All notable changes to the API.

    ## 2026-06-06

    > **new**: Add support for batch create cards that can be activated. Intended
    > for use case where physical cards will be issued from the Wallet cards. The
    > cards created will all have status `created` and needs to be activated before
    > use
    >
    > - [POST /v1/accounts/{aid}/wallets/cards/batch](/wallets-api/cards/aid_cards_batch_post)
    > - [POST /v1/accounts/{aid}/wallets/cards/{card_id}/activate](/wallets-api/cards/aid_cards_cardid_activate_post)

    ## 2025-02-06

    > **new**: Add optional query parameter `includes` and extend card details with pin and token format
    > - [GET /v1/accounts/{aid}/wallets/cards/{card_id}](/wallets-api/cards/aid_cards_cardid_get)

    ## 2025-01-30

    > **new**: Add endpoint for rotating or generating pin for card
    > - [POST /v1/accounts/{aid}/wallets/cards/{card_id}/rotate-pin](/wallets-api/cards/aid_cards_cardid_rotate_pin_post)

    ## 2024-12-16

    > **new**: Add `amount_reserved` on card balance, add `status` to card properties
    >
    > - [GET /v1/accounts/{aid}/wallets/cards](/wallets-api/cards/aid_cards_get)
    > - [GET /v1/accounts/{aid}/wallets/cards/{card_id}](/wallets-api/cards/aid_cards_cardid_get)

    ## 2024-12-11

    > **new**: Add `amount_available` query param filter on getting cards
    >
    > - [GET /v1/accounts/{aid}/wallets/cards](/wallets-api/cards/aid_cards_get)

    ## 2024-12-05

    > **new**: Add `amount_funds`, `amount_drawdown`, `amount_pending` on card balance
    > 
    >
    > - [GET /v1/accounts/{aid}/wallets/cards](/wallets-api/cards/aid_cards_get)
    > - [GET /v1/accounts/{aid}/wallets/cards/{card_id}](/wallets-api/cards/aid_cards_cardid_get)

    ## 2024-11-28

    > **update**: Revert adding deletion properties to cards
    >
    > **new**: Add `originated_by` to card and transaction properties
    >
    > - [GET /v1/accounts/{aid}/wallets/cards](/wallets-api/cards/aid_cards_get)
    > - [GET /v1/accounts/{aid}/wallets/cards/{card_id}](/wallets-api/cards/aid_cards_cardid_get)
    > - [GET /v1/accounts/{aid}/wallets/cards/{card_id}/transactions](/wallets-api/transactions/aid_cards_cardid_transactions_tid_get)
    > - [POST /v1/accounts/{aid}/wallets/transactions](/wallets-api/transactions/aid_cards_transactions_post)
    > - [POST /v1/accounts/{aid}/wallets/transactions/{transaction_id}/capture](/wallets-api/transactions/aid_cards_cardid_transactions_capture_post)
    > - [POST /v1/accounts/{aid}/wallets/transactions/{transaction_id}/void](/wallets-api/transactions/aid_cards_cardid_transactions_void_post)

    ## 2024-11-27

    > **new**: Add endpoint for deleting a card
    > 
    > **new**: `include_deleted` query parameter for including deleted cards
    >
    > - [DELETE /v1/accounts/{aid}/wallets/cards/{card_id}](#tag/cards/operation/aid_cards_cardid_delete)
    > - [GET /v1/accounts/{aid}/wallets/cards](/wallets-api/cards/aid_cards_get)

    ## 2024-11-13

    > **new**: Add endpoint for getting cards on account
    >
    > **new**: Add support for defining type of card
    >
    > - [GET /v1/accounts/{aid}/wallets/cards](/wallets-api/cards/aid_cards_get)
    > - [POST /v1/accounts/{aid}/wallets/cards](/wallets-api/cards/aid_cards_post)

    ## 2024-11-01

    > **update**: Adjust minimum length of PIN when creating a new card from 6 to 4.
    >
    > - [POST /v1/accounts/{aid}/wallets/cards](/wallets-api/cards/aid_cards_post)

    ## 2024-06-10

    > **new**: Allow more currencies: `SEK`, `DKK`, `EUR`, and `USD`.
    >
    > - [POST /v1/accounts/{aid}/wallets/cards](/wallets-api/cards/aid_cards_post)
    > - [POST /v1/accounts/{aid}/wallets/transactions](/wallets-api/transactions/aid_cards_transactions_post)
    > - [GET /v1/accounts/{aid}/wallets/cards/{card_id}](/wallets-api/cards/aid_cards_cardid_get)
    > - [GET /v1/accounts/{aid}/wallets/customers/{customer_id}/cards/{card_id}](/wallets-api/customers/aid_customers_cid_card_cid_get)

    ## 2024-02-01

    > **new**: Add option to create card with `pin` and support for
    > including pin when getting card info and when creating new
    > transaction
    >
    > - [POST /v1/accounts/{aid}/wallets/cards](/wallets-api/cards/aid_cards_post)
    > - [POST /v1/accounts/{aid}/wallets/info](/wallets-api/cards/aid_cards_token_post)
    > - [POST /v1/accounts/{aid}/wallets/transactions](/wallets-api/transactions/aid_cards_transactions_post)

    ## 2023-07-07

    > **new**: Add optional `name` field to `Card`.
    >
    > - [POST /v1/accounts/{aid}/wallets/cards](/wallets-api/cards/aid_cards_post)
    > - [GET /v1/accounts/{aid}/wallets/cards/{card_id}](/wallets-api/cards/aid_cards_cardid_get)
    > - [GET /v1/accounts/{aid}/wallets/customers/{customer_id}/cards](/wallets-api/customers/aid_customers_cid_cards_get)
    > - [GET /v1/accounts/{aid}/wallets/customers/{customer_id}/cards/{card_id}](/wallets-api/customers/aid_customers_cid_card_cid_get)

    ## 2023-06-12

    > **new**: Get details on customer card using `customer_id` and `card_id`.
    >
    > - [GET /v1/accounts/{aid}/wallets/customers/{customer_id}/cards/{card_id}](/wallets-api/customers/aid_customers_cid_card_cid_get)

    ## 2023-06-01

    > **new** Support creating card with `active_from` to control when
    > the created card is activated and allows `drawdown` transactions to be
    > created
    >
    > - [POST /v1/accounts/{aid}/wallets/cards](/wallets-api/cards/aid_cards_post)

    > **new** Support creating fund transaction using `type` property.
    >
    > - [POST /v1/accounts/{aid}/wallets/transactions](/wallets-api/transactions/aid_cards_transactions_post)

    > **new** Support creating transaction using `card_id`.
    >
    > - [POST /v1/accounts/{aid}/wallets/transactions](/wallets-api/transactions/aid_cards_transactions_post)

    > **new**: Support listing cards by customer_id, allow customer with
    > access to `user:wallets` scope to list their cards with balance
    >
    > - [GET /v1/accounts/{aid}/wallets/customers/{cid}/cards](/wallets-api/customers/aid_customers_cid_cards_get)
  contact:
    name: API Integration Support
    email: integration@dintero.com
  version: 1.0.0
  license:
    name: UNLICENSED
    url: https://dintero.com
security:
  - JWT: []
paths:
  /accounts/{aid}/wallets/cards:
    post:
      operationId: aid_cards_post
      summary: aid_cards_post
      description: |
        Create a new card

        scopes:
        - admin:wallets
        - write:wallets
      tags:
        - cards
      x-scopes:
        - admin:wallets
        - write:wallets
      parameters:
        - $ref: '#/components/parameters/accountId'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              allOf:
                - $ref: '#/components/schemas/Card'
                - properties:
                    pin:
                      $ref: '#/components/schemas/PinGenerator'
                    card_token:
                      $ref: '#/components/schemas/TokenGenerator'
        description: card details
        required: true
      security:
        - JWT: []
      responses:
        '200':
          description: Card created
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/Card'
                  - properties:
                      pin:
                        $ref: '#/components/schemas/PinGenerator'
                      card_token:
                        $ref: '#/components/schemas/TokenGenerator'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/AccessForbidden'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/ServerError'
      x-mint:
        metadata:
          title: Create a card
          sidebarTitle: Create a card
    get:
      operationId: aid_cards_get
      summary: aid_cards_get
      description: |
        Get all cards for an account

        scopes:
        - admin:wallets
        - read:wallets
      tags:
        - cards
      x-scopes:
        - admin:wallets
        - read:wallets
      parameters:
        - $ref: '#/components/parameters/accountId'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/startingAfter'
        - name: search
          in: query
          description: |
            Will try to match the search to either `card_id`, `customer_id` or `amount`
          required: false
          schema:
            type: string
        - name: created_at.gte
          in: query
          description: Card created after (ISO 8601. We recommend using a localised ISO 8601 datetime like `2017-07-21T17:32:28Z`. If a timezone is not specified we assume UTC)
          required: false
          schema:
            type: string
            format: isodate
        - name: created_at.lte
          in: query
          description: Card created before a date (ISO 8601. We recommend using a localised ISO 8601 datetime like `2017-07-21T17:32:28Z`. If a timezone is not specified we assume UTC)
          required: false
          schema:
            type: string
            format: isodate
        - name: type
          in: query
          description: |
            Filter cards by type
          required: false
          schema:
            type: string
            enum:
              - gift_card
              - credit_note
        - name: status
          in: query
          description: |
            Filter cards by amount and expiry status
          required: false
          schema:
            type: string
            enum:
              - inactive
              - unused
              - partially_used
              - used
              - expired
        - name: expires_at.gte
          in: query
          description: Card expires after (ISO 8601. We recommend using a localised ISO 8601 datetime like `2017-07-21T17:32:28Z`. If a timezone is not specified we assume UTC)
          required: false
          schema:
            type: string
            format: isodate
        - name: expires_at.lte
          in: query
          description: Card expires before a date (ISO 8601. We recommend using a localised ISO 8601 datetime like `2017-07-21T17:32:28Z`. If a timezone is not specified we assume UTC)
          required: false
          schema:
            type: string
            format: isodate
        - name: amount_balance
          in: query
          description: Exact card balance
          required: false
          schema:
            type: integer
        - name: amount_balance.gte
          in: query
          description: Lower limit for filtering on card balance.
          required: false
          schema:
            type: integer
        - name: amount_balance.lte
          in: query
          description: Upper limit for filtering on card balance.
          required: false
          schema:
            type: integer
        - name: amount_available
          in: query
          description: Amount available on the card
          required: false
          schema:
            type: integer
        - name: amount_available.gte
          in: query
          description: Lower limit for filtering on available amount on card.
          required: false
          schema:
            type: integer
        - name: amount_available.lte
          in: query
          description: Upper limit for filtering on available amount on card.
          required: false
          schema:
            type: integer
        - name: currency
          in: query
          description: |
            The currency of the card. `?currency=NOK&currency=SEK`
          explode: true
          schema:
            type: array
            items:
              type: string
        - name: customer
          in: query
          description: |
            Filter cards by `customer_id`
          required: false
          schema:
            type: string
      security:
        - JWT: []
      responses:
        '200':
          description: Collection of cards
          content:
            application/json:
              schema:
                type: object
                required:
                  - cards
                properties:
                  cards:
                    type: array
                    items:
                      allOf:
                        - $ref: '#/components/schemas/Card'
                  starting_after:
                    type: string
                    description: |
                      The cursor to use in the next request to get the next page of results
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/AccessForbidden'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/ServerError'
      x-mint:
        metadata:
          title: Get cards
          sidebarTitle: Get cards
  /accounts/{aid}/wallets/cards/batch:
    post:
      operationId: aid_cards_batch_post
      summary: aid_cards_batch_post
      description: |
        Batch create cards. The cards created from the batch operation will
        all have zero balance and status `inactive`. They all need to be
        activated before use.

        scopes:
        - admin:wallets
        - write:wallets
      tags:
        - cards
      x-scopes:
        - admin:wallets
        - write:wallets
      parameters:
        - $ref: '#/components/parameters/accountId'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              allOf:
                - required:
                    - cards
                  properties:
                    cards:
                      type: array
                      maxItems: 1000
                      items:
                        type: object
                        required:
                          - card_id
                          - type
                        properties:
                          card_id:
                            type: string
                            description: |
                              The card id you have defined for the card.
                              (must not have trailing or leading spaces)
                            maxLength: 255
                          type:
                            type: string
                            description: |
                              The type of the card. The value is one of the following:
                              - `gift_card` - a gift card
                              - `credit_note` - a credit note
                            example: gift_card
                            enum:
                              - gift_card
                              - credit_note
                    options:
                      type: object
                      description: Options for the cards to create
                      properties:
                        pin:
                          type: object
                          required:
                            - format
                          properties:
                            format:
                              $ref: '#/components/schemas/PinFormat'
                        card_token:
                          type: object
                          required:
                            - format
                          properties:
                            format:
                              allOf:
                                - $ref: '#/components/schemas/Format'
                                - description: |
                                    specify the format for the token, default format
                                    is an UUID prefixed with `DINCARD`
        description: card details
        required: true
      security:
        - JWT: []
      responses:
        '200':
          $ref: '#/components/responses/CardsBatchResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/AccessForbidden'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/ServerError'
      x-mint:
        metadata:
          title: Batch create cards
          sidebarTitle: Batch create cards
  /accounts/{aid}/wallets/cards/{card_id}:
    get:
      operationId: aid_cards_cardid_get
      summary: aid_cards_cardid_get
      description: |
        Get all details about a card

        scopes:
        - admin:wallets
        - read:wallets
      parameters:
        - $ref: '#/components/parameters/accountId'
        - $ref: '#/components/parameters/cardId'
        - name: includes
          in: query
          description: |
            Comma separated list of additional fields to include in the response.
            Possible values are:
            - `token.format`: Include the format that was used to generate token.
            - `pin.format`: Include the format that was used to generate PIN.
          explode: true
          schema:
            type: array
            items:
              type: string
              enum:
                - token.format
                - pin.format
      tags:
        - cards
      x-scopes:
        - admin:wallets
        - read:wallets
      security:
        - JWT: []
      responses:
        '200':
          description: Card details
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/CardDetails'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/AccessForbidden'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
      x-mint:
        metadata:
          title: Retrieve card by card ID
          sidebarTitle: Retrieve card by card ID
  /accounts/{aid}/wallets/cards/{card_id}/activate:
    post:
      operationId: aid_cards_cardid_activate_post
      summary: aid_cards_cardid_activate_post
      description: |
        Activate a card with status `inactive`

        scopes:
        - admin:wallets
        - write:wallets
        - write:wallets:/activate
      parameters:
        - $ref: '#/components/parameters/accountId'
        - $ref: '#/components/parameters/cardId'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              allOf:
                - properties:
                    customer_id:
                      type: string
                      description: |
                        The customer id you have defined as the owner
                        of the card. (must not have trailing or leading spaces)
                      maxLength: 255
                    name:
                      type: string
                      description: Display name for the card
                - $ref: '#/components/schemas/Operation'
                - $ref: '#/components/schemas/Metadata'
                - $ref: '#/components/schemas/OriginatedBy'
                - $ref: '#/components/schemas/CardActivePeriod'
        required: true
      tags:
        - cards
      x-scopes:
        - admin:wallets
        - write:wallets
      security:
        - JWT: []
      responses:
        '200':
          description: Card details
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/CardDetails'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/AccessForbidden'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
      x-mint:
        metadata:
          title: Activate card
          sidebarTitle: Activate card
  /accounts/{aid}/wallets/cards/{card_id}/tokens:
    post:
      operationId: aid_cards_cardid_token_post
      summary: aid_cards_cardid_token_post
      description: |
        Create a temporary `token` (also referred as Card Code)
        for the card, an temporary alias that must be used when
        when creating a drawdown transaction

        The token can be stored in a barcode to allow use of virtuell card
        in purchase in POS or webstore

        scopes:
        - admin:wallets
        - write:wallets
      tags:
        - cards
      x-scopes:
        - admin:wallets
        - write:wallets
      parameters:
        - $ref: '#/components/parameters/accountId'
        - $ref: '#/components/parameters/cardId'
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/Metadata'
                - $ref: '#/components/schemas/BaseOperation'
                - $ref: '#/components/schemas/TokenGenerator'
        description: token details
        required: true
      security:
        - JWT: []
      responses:
        '200':
          description: Token created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Token'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/AccessForbidden'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
      x-mint:
        metadata:
          title: Create a token for the card
          sidebarTitle: Create a token for the card
  /accounts/{aid}/wallets/cards/{card_id}/transactions:
    get:
      operationId: aid_cards_cardid_transactions_tid_get
      summary: aid_cards_cardid_transactions_tid_get
      description: |
        Retrieve a list of Card's Transaction based on card id

        scopes:
        - admin:wallets
        - read:wallets
      parameters:
        - $ref: '#/components/parameters/accountId'
        - $ref: '#/components/parameters/cardId'
      tags:
        - transactions
      security:
        - JWT: []
      x-scopes:
        - admin:wallets
        - read:wallets
      responses:
        '200':
          description: Transcation list
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Transaction'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/AccessForbidden'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
      x-mint:
        metadata:
          title: List card transactions
          sidebarTitle: List card transactions
  /accounts/{aid}/wallets/cards/{card_id}/rotate-pin:
    post:
      operationId: aid_cards_cardid_rotate_pin_post
      summary: aid_cards_cardid_rotate_pin_post
      description: |
        Rotate or add new pin to card

        scopes:
        - admin:wallets
        - write:wallets
      parameters:
        - $ref: '#/components/parameters/accountId'
        - $ref: '#/components/parameters/cardId'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - pin
              properties:
                pin:
                  $ref: '#/components/schemas/PinGenerator'
      tags:
        - cards
      x-scopes:
        - admin:wallets
        - write:wallets
      security:
        - JWT: []
      responses:
        '200':
          $ref: '#/components/responses/RotatePinResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/AccessForbidden'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
      x-mint:
        metadata:
          title: Rotate Pin
          sidebarTitle: Rotate Pin
  /accounts/{aid}/wallets/customers/{customer_id}/cards:
    get:
      operationId: aid_customers_cid_cards_get
      summary: aid_customers_cid_cards_get
      description: |
        Get the cards active for a customer

        scopes:
        - admin:wallets
        - read:wallets
        - user:wallets
      tags:
        - customers
      x-scopes:
        - admin:wallets
        - read:wallets
        - user:wallets
      security:
        - JWT: []
      parameters:
        - $ref: '#/components/parameters/accountId'
        - $ref: '#/components/parameters/customerId'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/startingAfter'
      responses:
        '200':
          description: Card details
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CustomerCard'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/AccessForbidden'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
      x-mint:
        metadata:
          title: List customer cards
          sidebarTitle: List customer cards
  /accounts/{aid}/wallets/customers/{customer_id}/cards/{card_id}:
    get:
      operationId: aid_customers_cid_card_cid_get
      summary: aid_customers_cid_card_cid_get
      description: |
        Get all details about a customer card 

        scopes:
        - admin:wallets
        - read:wallets
        - user:wallets
      tags:
        - customers
      x-scopes:
        - admin:wallets
        - read:wallets
        - user:wallets
      security:
        - JWT: []
      parameters:
        - $ref: '#/components/parameters/accountId'
        - $ref: '#/components/parameters/customerId'
        - $ref: '#/components/parameters/cardId'
      responses:
        '200':
          description: Card details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerCardState'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/AccessForbidden'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
      x-mint:
        metadata:
          title: Get customer card details
          sidebarTitle: Get customer card details
  /accounts/{aid}/wallets/info:
    post:
      operationId: aid_cards_token_post
      summary: aid_cards_token_post
      description: |
        Get details about a card, including the current balance and available
        funds. No details will be returned for expired tokens

        scopes:
        - admin:wallets
        - write:wallets
        - write:wallets:/info
      tags:
        - cards
      x-scopes:
        - admin:wallets
        - write:wallets
        - write:wallets:/info
      parameters:
        - $ref: '#/components/parameters/accountId'
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/TokenCode'
        required: true
      security:
        - JWT: []
      responses:
        '200':
          description: Card info details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Card'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/AccessForbidden'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
      x-mint:
        metadata:
          title: Retrieve card by Token
          sidebarTitle: Retrieve card by Token
  /accounts/{aid}/wallets/transactions:
    post:
      operationId: aid_cards_transactions_post
      summary: aid_cards_transactions_post
      description: |
        Create a transaction against a Card using `token` or `card_id`.
        If the Transactions is created as pending, the value will
        be locked until it is either captured or voided. Transaction ID must
        be used when capturing or voiding a transaction.

        > Using **`card_id`** or creating a **`fund`** transaction requires
        > authorization scope `admin:wallets` or `write:wallets`

        scopes:
        - admin:wallets
        - write:wallets
        - write:wallets:/transactions
      tags:
        - transactions
      x-scopes:
        - admin:wallets
        - write:wallets
        - write:wallets:/transactions
      parameters:
        - $ref: '#/components/parameters/accountId'
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/CardByIdOrToken'
                - $ref: '#/components/schemas/TransactionInput'
                - properties:
                    type:
                      type: string
                      default: drawdown
                      enum:
                        - drawdown
                        - fund
                    pending:
                      type: boolean
                      default: false
                      description: |
                        If true, the transaction will be created as pending, i.e.
                        the value will be locked until it is either captured or
                        voided.

                        > Only supported when creating a `drawdown` transaction.
        description: transaction details
        required: true
      security:
        - JWT: []
      responses:
        '200':
          description: Transaction created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Transaction'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/AccessForbidden'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
      x-mint:
        metadata:
          title: Create transaction
          sidebarTitle: Create transaction
  /accounts/{aid}/wallets/transactions/{transaction_id}/capture:
    post:
      operationId: aid_cards_cardid_transactions_capture_post
      summary: aid_cards_cardid_transactions_capture_post
      description: |
        Capture a pending Transaction, thereby collection the amount
        withheld by the pending transaction.

        Option to specify an amount that should be captured. 
        Defaults to capture the full transaction.
        When the amount specified is less than the reserved/pending, 
        the remaining amount will still be reserved/pending and can be captured later.

        scopes:
        - admin:wallets
        - write:wallets
        - write:wallets:/transactions
      tags:
        - transactions
      x-scopes:
        - admin:wallets
        - write:wallets
        - write:wallets:/transactions
      parameters:
        - $ref: '#/components/parameters/accountId'
        - $ref: '#/components/parameters/transactionId'
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/Metadata'
                - $ref: '#/components/schemas/BaseOperation'
                - $ref: '#/components/schemas/OptionalAmount'
        description: capture details
        required: true
      security:
        - JWT: []
      responses:
        '200':
          description: Transaction created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Transaction'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/AccessForbidden'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
      x-mint:
        metadata:
          title: Capture pending transaction
          sidebarTitle: Capture pending transaction
  /accounts/{aid}/wallets/transactions/{transaction_id}/void:
    post:
      operationId: aid_cards_cardid_transactions_void_post
      summary: aid_cards_cardid_transactions_void_post
      description: |
        Void a pending Transaction by unlocking the amount
        withheld by the pending transaction

        scopes:
        - admin:wallets
        - write:wallets
        - write:wallets:/transactions
      tags:
        - transactions
      x-scopes:
        - admin:wallets
        - write:wallets
        - write:wallets:/transactions
      parameters:
        - $ref: '#/components/parameters/accountId'
        - $ref: '#/components/parameters/transactionId'
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/Metadata'
                - $ref: '#/components/schemas/BaseOperation'
        description: void details
        required: true
      security:
        - JWT: []
      responses:
        '200':
          description: Transaction voided
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Transaction'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/AccessForbidden'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
      x-mint:
        metadata:
          title: Void pending transaction
          sidebarTitle: Void pending transaction
x-tagGroups:
  - name: wallets
    tags:
      - cards
      - customers
      - transactions
servers:
  - url: https://api.dintero.com/v1
components:
  parameters:
    accountId:
      name: aid
      description: |
        An id that uniquely identifies the account.
      in: path
      required: true
      schema:
        type: string
        format: ^[PT]{1}\d{8}$
        minLength: 9
        maxLength: 9
    limit:
      name: limit
      in: query
      description: |
        A limit on the number of objects to be returned. Limit can range
        between 1 and 100 items, and the default is 10 items.
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 10
    startingAfter:
      name: starting_after
      in: query
      description: |
        cursor for use in pagination. starting_after is an object ID
        that defines your place in the list. For instance, if you make
        a list request and receive 100 objects, end the result contains
          `paging_token=pt1`, your subsequent call can include
        `starting_after=pt1` in order to fetch the next page of the list.
      required: false
      schema:
        type: string
    cardId:
      name: card_id
      description: |
        The card id you have defined for the card.
        (must not have trailing or leading spaces)
      in: path
      required: true
      schema:
        type: string
        maxLength: 255
    customerId:
      name: customer_id
      description: |
        The customer id you have defined for the customer.
        (must not have trailing or leading spaces)
      in: path
      required: true
      schema:
        type: string
        maxLength: 255
    transactionId:
      name: transaction_id
      description: |
        An id that uniqely idetifies a transaction
      in: path
      required: true
      schema:
        type: string
        format: uuid
  responses:
    BadRequest:
      description: Bad / Invalid request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    AccessForbidden:
      description: Access forbidden, invalid JWT token was used
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ServerError:
      description: Unexpected Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    CardsBatchResponse:
      description: Cards created
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/InactiveBatchCards'
    NotFound:
      description: Resource was not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    RotatePinResponse:
      description: Pin rotated
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RotatePin'
  securitySchemes:
    JWT:
      type: http
      description: |
        Bearer authentication (token authentication) should be used for accessing the API.

        Use [Get Token](/api-reference/authenticate/aid_auths_oauth_token_post) to get an access token for client credentials.
        Pass the token in the request header:

            Authorization: Bearer {access_token}

        where the **access_token** is JSON Web Tokens (JWT).
      scheme: bearer
      bearerFormat: JWT
  schemas:
    OriginatedBy:
      type: object
      properties:
        originated_by:
          type: string
          description: |
            The reference to where the entity was created.
            (must not have trailing or leading spaces)
          maxLength: 255
    PinFormat:
      description: PIN format used for generation
      type: object
      properties:
        length:
          description: |
            The length of the PIN (exclusive length of the prefix).
          type: integer
          default: 36
          minimum: 4
        prefix:
          type: string
          description: |
            Prefix the PIN, the length of the prefix will affect
            the total length of the PIN.
          example: 'DINCARD:'
          maxLength: 12
        symbols:
          type: boolean
          description: Allow characters like `@#$%` in the created PIN.
          default: true
        numbers:
          type: boolean
          description: Allow characters like `123456` in the created PIN.
          default: true
        characters:
          type: boolean
          description: Allow characters like `acbABC` in the created PIN.
        barcode:
          default: false
          description: |
            Include the PIN as a base64 encoded barcode image.
          type: boolean
    CardProperties:
      type: object
      required:
        - card_id
      allOf:
        - $ref: '#/components/schemas/OriginatedBy'
        - properties:
            card_id:
              type: string
              description: |
                The card id you have defined for the card.
                (must not have trailing or leading spaces)
              maxLength: 255
            customer_id:
              type: string
              description: |
                The customer id you have defined as the owner
                of the card. (must not have trailing or leading spaces)
              maxLength: 255
            name:
              type: string
              description: Display name for the card
            type:
              type: string
              description: |
                The type of the card. The value is one of the following:
                - `gift_card` - a gift card
                - `credit_note` - a credit note
                Defaults to `gift_card`
              example: gift_card
              enum:
                - gift_card
                - credit_note
            status:
              type: string
              description: |
                The status of the card. The value is one of the following:
                - `inactive` - Inactive card created by batch, needs to be activated
                - `unused` - the card is unused
                - `used` - the card has 0 balance
                - `partially_used` - the card has been used partially
                - `expired` - the card has expired

                Defaults to `unused`
              example: unused
              enum:
                - inactive
                - unused
                - used
                - partially_used
                - expired
            pin:
              type: object
              properties:
                format:
                  allOf:
                    - $ref: '#/components/schemas/PinFormat'
    ImmutableEntity:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: |
            An UUID that uniquely identifies the resource
          readOnly: true
        created_at:
          type: string
          format: date-time
          description: |
            The date-time when the resource was created
          readOnly: true
        created_by:
          type: string
          example: 1c92f7e1-2897-4d46-bdcc-c127a914fb4e
          description: |
            The ID of the user/client that created the resource
          readOnly: true
    Metadata:
      type: object
      properties:
        metadata:
          type: object
          description: |
            A key-value JSON object to store any additional
            information. The dintero_* namespace for keys
            is reserved
          example:
            order_id: xk39592f
    Operation:
      type: object
      allOf:
        - required:
            - amount
            - currency
          properties:
            amount:
              type: integer
              example: 50000
              minimum: 0
              description: |
                Monetary amount in smallest unit for the currency
            currency:
              type: string
              example: NOK
              enum:
                - NOK
                - SEK
                - DKK
                - EUR
                - USD
              description: |
                The three-character ISO-4217 currency.
                https://en.wikipedia.org/wiki/ISO_4217
    CardBalance:
      type: object
      properties:
        amount_balance:
          type: number
          readOnly: true
          example: 50000
          minimum: 0
          description: |
            The balance, including amount locked by pending transaction.
            Monetary amount in smallest unit for the currency
        amount_available:
          type: number
          readOnly: true
          example: 50000
          minimum: 0
          description: |
            The amount available for drawdown
            (exclusive amount locked by pending transactions).
            Monetary amount in smallest unit for the currency
        amount_funds:
          type: number
          readOnly: true
          example: 50000
          minimum: 0
          description: |
            The sum of all fund transactions.
            Monetary amount in smallest unit for the currency
        amount_drawdown:
          type: number
          readOnly: true
          example: 50000
          minimum: 0
          description: |
            The sum of all drawdown transactions.
            Monetary amount in smallest unit for the currency
        amount_pending:
          type: number
          readOnly: true
          example: 50000
          minimum: 0
          description: |
            The sum of all pending transactions.
            Monetary amount in smallest unit for the currency
        amount_reserved:
          type: number
          readOnly: true
          example: 50000
          minimum: 0
          description: |
            The sum of all reserved transactions.
            Monetary amount in smallest unit for the currency
    CardActivePeriod:
      type: object
      properties:
        active_from:
          type: string
          format: date-time
          description: |
            Optional time when the card is activated. No `drawdown` transaction
            will be allowed before if set. (`fund` transaction is allowed)
        expires_at:
          type: string
          format: date-time
          description: |
            Optional expiration time for the card. No transaction will be
            allowed on an expired card
    Card:
      type: object
      allOf:
        - $ref: '#/components/schemas/CardProperties'
        - $ref: '#/components/schemas/ImmutableEntity'
        - $ref: '#/components/schemas/Metadata'
        - $ref: '#/components/schemas/Operation'
        - $ref: '#/components/schemas/CardBalance'
        - $ref: '#/components/schemas/CardActivePeriod'
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - message
          properties:
            code:
              type: string
              description: The code used to identify the error/warning
            errors:
              type: array
              description: The nested error(s) encountered during validation
              items:
                type: object
            message:
              type: string
              description: The human readable description of the error/warning
    PinGenerator:
      type: object
      description: How the PIN should be generated.
      properties:
        format:
          $ref: '#/components/schemas/PinFormat'
        pin:
          type: object
          readOnly: true
          properties:
            value:
              type: string
              example: '012345'
              maxLength: 48
            barcode_128:
              type: string
              description: |
                Code 128 barcode representation of the PIN value. A base64 encoded
                image in format `data:[<mime type>][;charset=<charset>][;base64],<encoded data>`
              example: data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAADIA...
    Format:
      description: Specify the format to generate
      type: object
      properties:
        length:
          description: |
            The length of the token (exclusive length of the prefix)
          type: integer
          default: 36
          minimum: 6
        prefix:
          type: string
          description: |
            Prefix the token, the length of the prefix will affect
            the total length of the token
          example: 'DINCARD:'
          maxLength: 12
        symbols:
          type: boolean
          description: Allow characters like `@#$%` in the created token
          default: true
        numbers:
          type: boolean
          description: Allow characters like `123456` in the created token
          default: true
        characters:
          type: boolean
          description: Allow characters like `acbABC` in the created token
        barcode:
          default: false
          description: |
            Include token as base64 encoded barcode image
          type: boolean
    TokenGenerator:
      type: object
      description: Specify how token should be generated
      required:
        - expires_in
      properties:
        format:
          allOf:
            - $ref: '#/components/schemas/Format'
            - description: |
                specify the format for the token, default format
                is an UUID prefixed with `DINCARD`
        expires_after_transaction:
          type: boolean
          description: |
            The token can only be used to create one transaction, card lookup by
            token will be available until token expires by date
          default: true
        expires_in:
          description: |
            The lifetime in seconds for the card token.  For
            example, the value "3600" denotes that the token will
            expire in one hour from the time the response was generated.
          minimum: 1
          type: integer
        token:
          type: object
          readOnly: true
          properties:
            value:
              type: string
              example: DINCARD:6ccfec5d-3a53-47de-910a-97d6dda22e5f
              maxLength: 48
            barcode_128:
              type: string
              description: |
                Code 128 barcode representation of the token value. A base64 encoded
                image in format `data:[<mime type>][;charset=<charset>][;base64],<encoded data>`
              example: data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAADIA...
    InactiveBatchCards:
      type: object
      required:
        - cards
      properties:
        cards:
          type: array
          items:
            allOf:
              - $ref: '#/components/schemas/Card'
              - properties:
                  status:
                    type: string
                    enum:
                      - inactive
                  pin:
                    $ref: '#/components/schemas/PinGenerator'
                  card_token:
                    $ref: '#/components/schemas/TokenGenerator'
    TokenList:
      type: object
      properties:
        tokens:
          type: array
          items:
            type: object
            properties:
              expires_at:
                description: expiration time for the token
                type: string
                format: date-time
              masked_code:
                description: masked token code
                type: string
                example: DINCARD:********-****-****-91**-*******22e5f
              format:
                allOf:
                  - $ref: '#/components/schemas/Format'
    CardDetails:
      type: object
      allOf:
        - $ref: '#/components/schemas/Card'
        - $ref: '#/components/schemas/TokenList'
    BaseOperation:
      type: object
      required:
        - ref_id
      properties:
        ref_id:
          type: string
          description: |
            Unique ref ID provided by the client to support safely retrying
            requests without accidentally performing the same operation twice

            All card transaction must have a unique ref ID, but it is not
            required that the ref ID is globally unique.
    Token:
      type: object
      allOf:
        - $ref: '#/components/schemas/ImmutableEntity'
        - $ref: '#/components/schemas/Metadata'
        - $ref: '#/components/schemas/BaseOperation'
        - $ref: '#/components/schemas/TokenGenerator'
    TransactionInput:
      type: object
      allOf:
        - $ref: '#/components/schemas/ImmutableEntity'
        - $ref: '#/components/schemas/Metadata'
        - $ref: '#/components/schemas/BaseOperation'
        - $ref: '#/components/schemas/Operation'
        - $ref: '#/components/schemas/OriginatedBy'
    Transaction:
      type: object
      allOf:
        - $ref: '#/components/schemas/TransactionInput'
        - properties:
            type:
              type: string
              description: |
                The type of the Transaction:
                  - *fund*: the amount has been funded to the card
                  - *drawdown*: the amount has been drawn from the card
                  - *pending_capture*: the amount has been locked until it is either captured or voided
                  - *voided*: the amount locked by pending Transaction is unlocked
              enum:
                - drawdown
                - pending_capture
                - voided
                - fund
              readOnly: true
            parent_id:
              type: string
              format: uuid
              readOnly: true
              description: |
                The ID of the original Transaction for a void or
                capture transaction
    RotatePin:
      type: object
      required:
        - pin
      properties:
        pin:
          $ref: '#/components/schemas/PinGenerator'
    CustomerCard:
      type: object
      allOf:
        - $ref: '#/components/schemas/ImmutableEntity'
        - $ref: '#/components/schemas/Metadata'
        - $ref: '#/components/schemas/CardActivePeriod'
        - $ref: '#/components/schemas/CardProperties'
    CustomerCardState:
      type: object
      allOf:
        - $ref: '#/components/schemas/CustomerCard'
        - $ref: '#/components/schemas/TokenList'
        - $ref: '#/components/schemas/CardBalance'
        - properties:
            currency:
              type: string
              example: NOK
              enum:
                - NOK
                - SEK
                - DKK
                - EUR
                - USD
              description: |
                Three-character ISO-4217 currency.
                https://en.wikipedia.org/wiki/ISO_4217
    TokenCode:
      type: object
      required:
        - token
      properties:
        token:
          type: string
          description: |
            temporary token for a Card
        pin:
          type: string
          description: PIN for the Card
    CardByIdOrToken:
      type: object
      properties:
        token:
          type: string
          description: |
            **required** if `card_id` is not set (cannot be combined with `card_id`)
        card_id:
          type: string
          description: |
            **required** if `token` is not set (cannot be combined with `token`)
    OptionalAmount:
      type: object
      properties:
        amount:
          type: integer
          example: 50000
          minimum: 0
          description: |
            Monetary amount in smallest unit for the currency