openapi: 3.2.0
info:
  description: Card Issuing, Switching, and Transaction Processing groups together the activities surrounding creating card programs, issuing cards to customers, managing those cards, and processing the transactions those customers make.
  version: v1.3
  title: Cards Support API
servers:
- description: Sandbox
  url: https://sandbox-api.novopayment.com/api/v1.3
security:
- oAuth2ClientCredentials: []
tags:
- name: Support
paths:
  /cards/{cardId}/block:
    post:
      tags:
      - Support
      summary: Block Card
      description: By providing a card ID, block all transactions from approval. This operation can be reversed through the Unblock Card endpoint. Cards that are to be replaced must be blocked before a replacement can be requested.
      operationId: BlockCard
      parameters:
      - $ref: '#/components/parameters/cardId'
      requestBody:
        $ref: '#/components/requestBodies/RQBlockCard'
      responses:
        '200':
          $ref: '#/components/responses/RSBlockCard200'
        '400':
          $ref: '#/components/responses/RSBlockCard400'
        '401':
          $ref: '#/components/responses/RS401'
        '500':
          $ref: '#/components/responses/RS500'
  /cards/{cardId}/pin:
    post:
      tags:
      - Support
      summary: Card PIN Assignment
      description: 'For a newly issued card, the Card PIN Assignment is used to set the

        card’s four-digit PIN which will be used for cash out transactions or

        transaction confirmation. To update a PIN for cards which already have

        one, the Card PIN Update endpoint is used.'
      operationId: CardPINAssignment
      parameters:
      - $ref: '#/components/parameters/cardId'
      requestBody:
        $ref: '#/components/requestBodies/RQCardPinAssignment'
      responses:
        '200':
          $ref: '#/components/responses/RSCardPinAssignment200'
        '400':
          $ref: '#/components/responses/RSCardPinAssignment400'
        '401':
          $ref: '#/components/responses/RS401'
        '500':
          $ref: '#/components/responses/RS500'
    put:
      tags:
      - Support
      summary: Card PIN Update
      description: 'For debit and prepaid cards which already have a four-digit PIN assigned, the Card PIN Update is used to update the card’s PIN.


        To set a PIN for a newly issued card, the Card PIN Assignment endpoint is used.'
      operationId: CardPINUpdate
      parameters:
      - $ref: '#/components/parameters/cardId'
      requestBody:
        $ref: '#/components/requestBodies/RQCardPinUpdate'
      responses:
        '200':
          $ref: '#/components/responses/RSCardPinUpdate200'
        '400':
          $ref: '#/components/responses/RSCardPinUpdate400'
        '401':
          $ref: '#/components/responses/RS401'
        '500':
          $ref: '#/components/responses/RS500'
  /cards/{cardId}/qr:
    get:
      tags:
      - Support
      summary: Card QR Code
      description: 'You can request the generation of a QR code representing the details of

        a card for a cardholder to scan and retrieve card details.

        This is typically done to expedite the onboarding of a card onto your

        system (for example, to add card details for activating a card).

        The QR code does not have an expiration date.'
      operationId: CardQRCode
      parameters:
      - $ref: '#/components/parameters/cardId'
      responses:
        '200':
          $ref: '#/components/responses/RSCardQRImage200'
        '400':
          $ref: '#/components/responses/RS400'
        '401':
          $ref: '#/components/responses/RS401'
        '500':
          $ref: '#/components/responses/RS500'
  /cards/{cardId}/unblock:
    post:
      tags:
      - Support
      summary: Unblock Card
      description: 'By providing a card ID, remove a block previously placed though the

        Block Card endpoint.'
      operationId: UnblockCard
      parameters:
      - $ref: '#/components/parameters/cardId'
      requestBody:
        $ref: '#/components/requestBodies/RQUnblockCard'
      responses:
        '200':
          $ref: '#/components/responses/RSUnblockCard200'
        '400':
          $ref: '#/components/responses/RSUnblockCard400'
        '401':
          $ref: '#/components/responses/RS401'
        '500':
          $ref: '#/components/responses/RS500'
components:
  responses:
    RSCardPinUpdate200:
      description: OK
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RSCardPinUpdate200'
          examples:
            Default:
              value:
                code: 200.01.000
                message: Process Ok
                datetime: '2020-01-03T16:05:56.517Z'
    RSCardQRImage200:
      description: Ok
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RSCardQRImage200'
          examples:
            Default:
              value:
                code: 200.00.000
                message: Process Ok
                datetime: '2020-01-03T16:05:56.517Z'
                data:
                  image: iVBORw0KGgoAAAANSUhEUgAAAgAAAAFVCAIA
    RSCardPinUpdate400:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RSCardReplacement400'
          examples:
            Header Params Required:
              $ref: '#/components/examples/HeaderParamsRequired'
            Invalid Tenant Id:
              $ref: '#/components/examples/InvalidTenantId'
            Card Is Blocked:
              $ref: '#/components/examples/CardIsBlocked'
            Invalid Pin Format:
              $ref: '#/components/examples/InvalidPinFormat'
            Original Pin No Match:
              $ref: '#/components/examples/OriginalPinNoMatch'
            New Pin Must Be Different To Original:
              $ref: '#/components/examples/NewPinMustBeDifferentToOriginal'
            Pin Already Used:
              $ref: '#/components/examples/PinAlreadyUsed'
            Card Has No Pin:
              $ref: '#/components/examples/CardHasNoPin'
            Encryption Error:
              $ref: '#/components/examples/EncryptionError'
            Invalid Encrypted Data:
              $ref: '#/components/examples/InvalidEncryptedData'
            Invalid Parameters:
              $ref: '#/components/examples/InvalidParameters'
    RS401:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RS401'
          examples:
            Invalid Access Token:
              $ref: '#/components/examples/InvalidAccessToken'
            Access Token Not Approved:
              $ref: '#/components/examples/AccessTokenNotApproved'
            Invalid Signature:
              $ref: '#/components/examples/InvalidSignature'
            Access Token Expired:
              $ref: '#/components/examples/AccessTokenExpired'
    RS400:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RS400'
          examples:
            Header Params Required:
              $ref: '#/components/examples/HeaderParamsRequired'
            Invalid Tenant Id:
              $ref: '#/components/examples/InvalidTenantId'
            Card Is Blocked:
              $ref: '#/components/examples/CardIsBlocked'
            Insufficient Funds:
              $ref: '#/components/examples/InsufficientFunds'
            We Were Unable To Process Your Request:
              $ref: '#/components/examples/WeWereUnableToProcessYourRequest'
            Invalid Transaction Code:
              $ref: '#/components/examples/InvalidTransactionCode'
            Exceeds The Limit Amount:
              $ref: '#/components/examples/ExceedsTheLimitAmount'
            The Card Is Not Active:
              $ref: '#/components/examples/TheCardIsNotActive'
            Tax Cannot Be Higher Than The Amount:
              $ref: '#/components/examples/TaxCannotBeHigherThanTheAmount'
            Maximum Number Of Transactions Reached:
              $ref: '#/components/examples/MaximumNumberOfTransactionsReached'
            CardIsExpired:
              $ref: '#/components/examples/CardIsExpired'
            Invalid Parameters:
              $ref: '#/components/examples/InvalidParameters'
            Exceeds Withdrawal Frequency Limit:
              $ref: '#/components/examples/ExceedsWithdrawalFrequencyLimit'
            Invalid CardId:
              $ref: '#/components/examples/InvalidCardId'
    RSUnblockCard400:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RSUnblockCard400'
          examples:
            Header Params Required:
              $ref: '#/components/examples/HeaderParamsRequired'
            Invalid Tenant Id:
              $ref: '#/components/examples/InvalidTenantId'
            Invalid Parameters:
              $ref: '#/components/examples/InvalidParameters'
            Card is permanently blocked:
              $ref: '#/components/examples/CardIsPermanentlyBlocked'
    RSUnblockCard200:
      description: OK
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RSUnblockCard200'
          examples:
            Default:
              value:
                code: 200.01.000
                message: Process Ok
                datetime: '2020-01-03T16:05:56.517Z'
    RSCardPinAssignment400:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RSCardPinAssignment400'
          examples:
            Header Params Required:
              $ref: '#/components/examples/HeaderParamsRequired'
            Invalid Tenant Id:
              $ref: '#/components/examples/InvalidTenantId'
            Card Is Blocked:
              $ref: '#/components/examples/CardIsBlocked'
            Invalid Pin Format:
              $ref: '#/components/examples/InvalidPinFormat'
            Encryption Error:
              $ref: '#/components/examples/EncryptionError'
            Invalid Encrypted Data:
              $ref: '#/components/examples/InvalidEncryptedData'
            Invalid Parameters:
              $ref: '#/components/examples/InvalidParameters'
            Card Has Already Been Assigned A Pin:
              $ref: '#/components/examples/CardHasAlreadyBeenAssignedAPin'
    RS500:
      description: Internal Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RS500'
          examples:
            Internal Server Error:
              $ref: '#/components/examples/InternalServerError'
    RSBlockCard400:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RSBlockCard400'
          examples:
            Header Params Required:
              $ref: '#/components/examples/HeaderParamsRequired'
            Invalid Tenant Id:
              $ref: '#/components/examples/InvalidTenantId'
            Card is permanently blocked:
              $ref: '#/components/examples/CardIsPermanentlyBlocked'
            Invalid Parameters:
              $ref: '#/components/examples/InvalidParameters'
            Exceeds Withdrawal Frequency Limit:
              $ref: '#/components/examples/ExceedsWithdrawalFrequencyLimit'
            Invalid CardId:
              $ref: '#/components/examples/InvalidCardId'
            Invalid Block Code:
              $ref: '#/components/examples/InvalidBlockCode'
            Card Is Blocked:
              $ref: '#/components/examples/CardIsBlocked'
            Invalid Card Id:
              $ref: '#/components/examples/InvalidCardId'
    RSCardPinAssignment200:
      description: OK
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RSCardPinAssignment200'
          examples:
            Default:
              value:
                code: 200.01.000
                message: Process Ok
                datetime: '2020-01-03T16:05:56.517Z'
    RSBlockCard200:
      description: OK
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RSBlockCard200'
          examples:
            Default:
              value:
                code: 200.01.000
                message: Process Ok
                datetime: '2020-01-03T16:05:56.517Z'
  examples:
    EncryptionError:
      value:
        code: 400.01.994
        message: Encryption error
        datetime: 2020-01-03 16:05:56.517000+00:00
    InvalidCardId:
      value:
        code: 400.01.009
        message: Invalid Card ID
        datetime: 2020-01-03 16:05:56.517000+00:00
    TaxCannotBeHigherThanTheAmount:
      value:
        code: 400.01.371
        message: Tax cannot be higher than the amount
        datetime: 2020-01-03 16:05:56.517000+00:00
    InvalidTenantId:
      value:
        code: 400.01.004
        message: Invalid tenant ID
        datetime: 2020-01-03 16:05:56.517000+00:00
    InvalidAccessToken:
      value:
        code: 401.01.990
        message: Invalid Access Token
        datetime: 2020-01-03 16:05:56.517000+00:00
    ExceedsWithdrawalFrequencyLimit:
      value:
        code: 400.01.522
        message: Exceeds withdrawal frequency limit
        datetime: 2020-01-03 16:05:56.517000+00:00
    InsufficientFunds:
      value:
        code: 400.01.044
        message: Insufficient funds
        datetime: 2020-01-03 16:05:56.517000+00:00
    CardHasAlreadyBeenAssignedAPin:
      value:
        code: 400.01.450
        message: Card has already been assigned a pin*
        datetime: 2020-01-03 16:05:56.517000+00:00
    InvalidSignature:
      value:
        code: 401.01.992
        message: Invalid signature
        datetime: 2020-01-03 16:05:56.517000+00:00
    CardIsExpired:
      value:
        code: 400.01.407
        message: Card is expired
        datetime: 2020-01-03 16:05:56.517000+00:00
    TheCardIsNotActive:
      value:
        code: 400.01.367
        message: The card is not active
        datetime: 2020-01-03 16:05:56.517000+00:00
    CardIsBlocked:
      value:
        code: 400.01.008
        message: Card is blocked
        datetime: 2020-01-03 16:05:56.517000+00:00
    NewPinMustBeDifferentToOriginal:
      value:
        code: 400.01.078
        message: New PIN must be different to original
        datetime: 2020-01-03T16:05:56.517Z4
    InvalidEncryptedData:
      value:
        code: 400.01.320
        message: Invalid Encrypted Data
        datetime: 2020-01-03 16:05:56.517000+00:00
    InvalidParameters:
      value:
        code: 400.01.396
        message: Invalid parameters
        data:
        - message: 'Field email: must not be blank'
        - message: 'Field email: must not be null'
        - message: 'Field to: must not be blank'
        - message: 'Field to: must not be null'
        - message: 'Field subject: must not be blank'
        - message: 'Field subject: must not be null'
        datetime: 2020-01-03 16:05:56.517000+00:00
    PinAlreadyUsed:
      value:
        code: 400.01.079
        message: PIN already used
        datetime: 2020-01-03T16:05:56.517Z4
    OriginalPinNoMatch:
      value:
        code: 400.01.013
        message: Original PIN no match
        datetime: 2020-01-03T16:05:56.517Z4
    InvalidBlockCode:
      value:
        code: 400.01.014
        message: Invalid block code
        datetime: 2020-01-03 16:05:56.517000+00:00
    InvalidPinFormat:
      value:
        code: 400.01.012
        message: Invalid PIN format
        datetime: 2020-01-03 16:05:56.517000+00:00
    InvalidTransactionCode:
      value:
        code: 400.01.338
        message: Invalid transaction code
        datetime: 2020-01-03 16:05:56.517000+00:00
    CardIsPermanentlyBlocked:
      value:
        code: 400.01.409
        message: The card is permanently blocked
        datetime: 2020-01-03 16:05:56.517000+00:00
    WeWereUnableToProcessYourRequest:
      value:
        code: 400.01.32
        message: We were unable to process your request
        datetime: 2020-01-03T16:05:56.517Z4
    CardHasNoPin:
      value:
        code: 400.01.363
        message: Card has no pin
        datetime: 2020-01-03T16:05:56.517Z4
    InternalServerError:
      value:
        code: 500.01.999
        message: Internal Server Error
        datetime: 2020-01-03 16:05:56.517000+00:00
    MaximumNumberOfTransactionsReached:
      value:
        code: 400.01.051
        message: Maximum number of transactions reached
        datetime: 2020-01-03 16:05:56.517000+00:00
    HeaderParamsRequired:
      value:
        code: 400.01.001
        message: Header Params Required
        datetime: 2020-01-03 16:05:56.517000+00:00
    ExceedsTheLimitAmount:
      value:
        code: 400.01.354
        message: Exceeds the limit amount
        datetime: 2020-01-03 16:05:56.517000+00:00
    AccessTokenExpired:
      value:
        code: 401.01.993
        message: Access token expired
        datetime: 2020-01-03 16:05:56.517000+00:00
    AccessTokenNotApproved:
      value:
        code: 401.01.991
        message: Access Token not approved
        datetime: 2020-01-03 16:05:56.517000+00:00
  schemas:
    RQCardPinUpdate:
      type: object
      required:
      - pin
      - newPin
      properties:
        pin:
          type: string
          description: Four-digit pin of the encrypted card using AES256 algorithm
          example: 052olf8m99453jCPWTOL3Q==
          maxLength: 24
        newPin:
          type: string
          description: Four-digit pin of the encrypted card using AES256 algorithm
          example: 052olf8m99453jCPWTOL3Q==
          maxLength: 24
    RSCardReplacement400:
      type: object
      required:
      - code
      - message
      - datetime
      properties:
        code:
          type: string
          example: 400.01.005
          description: Operation response code
          minLength: 10
          maxLength: 10
        message:
          type: string
          description: Response code description
          example: Client already registered in this program
          maxLength: 140
        datetime:
          type: string
          example: 2020-01-03 16:05:56.517000+00:00
          description: Operation Timestamp
          format: date-time
    RSUnblockCard200:
      type: object
      required:
      - code
      - message
      - datetime
      properties:
        code:
          type: string
          example: 200.01.000
          description: Operation response code
          maxLength: 10
        message:
          type: string
          example: Process Ok
          description: Response code description
          maxLength: 140
        datetime:
          type: string
          example: 2020-01-03 16:05:56.517000+00:00
          description: Operation Timestamp
          format: date-time
    RSCardPinAssignment200:
      type: object
      required:
      - code
      - message
      - datetime
      properties:
        code:
          type: string
          example: 200.01.000
          description: Operation response code
          maxLength: 10
        message:
          type: string
          example: Process Ok
          description: Response code description
          maxLength: 140
        datetime:
          type: string
          example: 2020-01-03 16:05:56.517000+00:00
          description: Operation Timestamp
          format: date-time
    RSUnblockCard400:
      type: object
      required:
      - code
      - message
      - datetime
      properties:
        code:
          type: string
          example: 400.01.004
          description: Operation response code
          minLength: 10
          maxLength: 10
        message:
          type: string
          description: Response code description
          example: Invalid tenant ID
          maxLength: 140
        datetime:
          type: string
          example: 2020-01-03 16:05:56.517000+00:00
          description: Operation Timestamp
          format: date-time
    RSCardPinAssignment400:
      type: object
      required:
      - code
      - message
      - datetime
      properties:
        code:
          type: string
          example: 400.01.004
          description: Operation response code
          minLength: 10
          maxLength: 10
        message:
          type: string
          description: Response code description
          example: Invalid tenant ID
          maxLength: 140
        datetime:
          type: string
          example: 2020-01-03 16:05:56.517000+00:00
          description: Operation Timestamp
          format: date-time
    RS500:
      type: object
      required:
      - code
      - message
      - datetime
      properties:
        code:
          type: string
          example: 500.01.999
          description: Operation response code
          minLength: 10
          maxLength: 10
        message:
          type: string
          example: Internal Server Error
          description: Response code description
          maxLength: 140
        datetime:
          type: string
          example: 2020-01-03 16:05:56.517000+00:00
          minLength: 24
          maxLength: 24
    RS401:
      type: object
      required:
      - code
      - message
      - datetime
      properties:
        code:
          type: string
          example: 401.01.990
          description: Operation response code
          minLength: 10
          maxLength: 10
        message:
          type: string
          example: Invalid Access Token
          description: Response code description
          maxLength: 140
        datetime:
          type: string
          example: 2020-01-03 16:05:56.517000+00:00
          minLength: 24
          maxLength: 24
    RSCardPinUpdate200:
      type: object
      required:
      - code
      - message
      - datetime
      properties:
        code:
          type: string
          example: 200.01.000
          description: Operation response code
          maxLength: 10
        message:
          type: string
          example: Process Ok
          description: Response code description
          maxLength: 140
        datetime:
          type: string
          example: 2020-01-03 16:05:56.517000+00:00
          description: Operation Timestamp
          format: date-time
    RSBlockCard400:
      type: object
      required:
      - code
      - message
      - datetime
      properties:
        code:
          type: string
          example: 400.01.004
          description: Operation response code
          minLength: 10
          maxLength: 10
        message:
          type: string
          description: Response code description
          example: Invalid tenant ID
          maxLength: 140
        datetime:
          type: string
          example: 2020-01-03 16:05:56.517000+00:00
          description: Operation Timestamp
          format: date-time
    ObjCardQRCodeData:
      type: object
      required:
      - image
      properties:
        image:
          type: string
          description: 'Image type Object that contains the QR Code image.

            '
          example: iVBORw0KGgoAAAANSUhEUgAAAgAAAAFVCAIA…
    RS400:
      type: object
      required:
      - code
      - message
      - datetime
      properties:
        code:
          type: string
          minLength: 10
          maxLength: 10
          description: Operation response code
        message:
          type: string
          maxLength: 140
          description: Response code description
        datetime:
          type: string
          format: date-time
          minLength: 24
          maxLength: 24
          description: "Operation Time Stamp in ISO 8601 format.\ndate-time – the date-time notation as defined by\n[RFC 3339, section 5.6](https://tools.ietf.org/html/rfc3339#section-5.6),\nfor example: 2024-07-21T17:32:28Z         \n"
    RQBlockCard:
      type: object
      required:
      - blockType
      - observations
      properties:
        blockType:
          type: string
          description: 'Blocking code in ISO8583 format

            Sample:

            - 41: Lost card

            - 43: Stolen card

            - PB: Preventive

            - 17: Cancelled card


            Allowed values: 41, 43, PB, 17

            '
          example: 41
          enum:
          - '41'
          - '43'
          - '17'
          - PB
          maxLength: 2
        observations:
          type: string
          description: 'Describes the reason for blocking the card


            **Allowed characters**: alphanumeric

            '
          example: Lost card
          maxLength: 255
    RSCardQRImage200:
      type: object
      properties:
        code:
          type: string
          maxLength: 10
          description: Operation response code
          example: 200.01.000
        message:
          type: string
          maxLength: 140
          description: Response code description
          example: Process Ok
        datetime:
          type: string
          format: date-time
          minLength: 24
          maxLength: 24
          description: 'Operation Time Stamp in ISO 8601 format.

            date-time – the date-time notation as defined by

            [RFC 3339, section 5.6](https://tools.ietf.org/html/rfc3339#section-5.6),

            for example: 2017-07-21T17:32:28Z

            '
          example: 2020-01-03 16:05:56.517000+00:00
        data:
          type: object
          $ref: '#/components/schemas/ObjCardQRCodeData'
    RQCardPinAssignment:
      type: object
      required:
      - pin
      properties:
        pin:
          type: string
          description: Four-digit pin of the encrypted card using AES256 algorithm
          example: 052olf8m99453jCPWTOL3Q==
          maxLength: 24
    RSBlockCard200:
      type: object
      required:
      - code
      - message
      - datetime
      properties:
        code:
          type: string
          example: 200.01.000
          description: Operation response code
          maxLength: 10
        message:
          type: string
          example: Process Ok
          description: Response code description
          maxLength: 140
        datetime:
          type: string
          example: 2020-01-03 16:05:56.517000+00:00
          description: Operation Timestamp
          format: date-time
    RQUnblockCard:
      type: object
      required:
      - observations
      properties:
        observations:
          type: string
          description: 'Description of the reason to unblock the card


            **Allowed characters:** alphanumeric

            '
          example: Card found
          maxLength: 255
  requestBodies:
    RQCardPinAssignment:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RQCardPinAssignment'
      required: true
    RQBlockCard:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RQBlockCard'
      required: true
    RQUnblockCard:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RQUnblockCard'
      required: true
    RQCardPinUpdate:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RQCardPinUpdate'
      required: true
  parameters:
    cardId:
      name: cardId
      in: path
      description: Unique card identification (uuid format)
      required: true
      example: 502c2656-7110-4994-a820-f593e468c6b4
      schema:
        type: string
        maxLength: 36
        minLength: 36
  securitySchemes:
    oAuth2ClientCredentials:
      type: oauth2
      description: 'See [Oauth2 API](https://developer.novopayment.com/api/authentication-method-and-encryption/oauth2-api)

        '
      flows:
        clientCredentials:
          tokenUrl: https://sandbox-api.novopayment.com/oauth2/token
          scopes: {}