swagger: '2.0'
info:
  version: ''
  title: HiPay Enterprise Tokenization API
  description: |
    We strongly recommend to use the JS SDK to tokenize a card, instead of the Tokenization API.

    The Tokenization (Secure Vault) API allows merchants to retrieve and update data associated with their customers' payment information stored in the HiPay Enterprise Secure Vault. Using Tokenization API, merchants eliminate the risk, liability and cost of storing sensitive data on their local servers and storage devices.

    The Tokenization API aims to be used **alongside the HiPay Enterprise Gateway API**. In particular, with the Request New Order (`POST /order`) service of the Gateway API. In fact, when you need to make payments with credit or debit cards using the Gateway API, you first need to tokenize card numbers thanks to the Tokenization API.

    This API integrates a BIN lookup tool. Every submitted card number is automatically searched in the BIN database to determine its issuing bank. When the BIN lookup succeeds, the response includes the card brand, the 2-letter country code where card was issued and when applicable the issuing bank name.

    Note: this documentation describes the Tokenization API parameters and response fields and allows you to test the platform in real time.

    ## Tokenization API base URLs

    | Environment | Base URL |
    | --- | --- |
    | Stage | https://stage-secure2-vault.hipay-tpp.com/rest/v2/token |
    | Production | https://secure2-vault.hipay-tpp.com/rest/v2/token |

    ## Authentication

    All requests to HiPay Enterprise API require you to authenticate using the HTTP *Basic Authentication* to convey your identity. Your API credentials can be found in your HiPay Enterprise back office in the Integration section. Most HTTP clients (including web-browsers) have built-in support for HTTP Basic Authentication. If not, the following header must be included in all HTTP requests.

    `Authorization: Basic base64("<API login>:<API password>")`
host: stage-secure2-vault.hipay-tpp.com
basePath: /rest/v2/token/
securityDefinitions:
  basicAuth:
    type: basic
tags:
  - name: tokenization
    description: Everything you need to tokenize payment cards
schemes:
  - https
consumes:
  - multipart/form-data
produces:
  - application/json
paths:
  /create:
    post:
      tags:
        - tokenization
      summary: Performs credit or debit card tokenization
      description: |
        Performs credit or debit card tokenization. Once the card is tokenized, you can use the generated token to make payments thanks to the HiPay Enterprise Gateway API.
      operationId: createToken
      produces:
        - application/json
      parameters:
        - name: card_number
          in: formData
          description: The card number.
          required: true
          x-is-map: false
          type: string
          default: '4000000000000002'
        - name: card_expiry_month
          description: The card expiry month.
          in: formData
          required: true
          x-is-map: false
          type: integer
          default: 12
        - name: card_expiry_year
          description: The card expiry year.
          in: formData
          required: true
          x-is-map: false
          type: integer
          default: 2025
        - name: card_holder
          description: The cardholder name as it appears on the card.
          in: formData
          required: true
          x-is-map: false
          type: string
          default: Cathy Doe
        - name: cvc
          description: The 3 or 4 digit security code (called CVV2 or CID depending on the card brand) that appears on the credit card.
          in: formData
          required: false
          x-is-map: false
          type: string
          default: '514'
          pattern: |
            (\d{3})|(\d{4})
        - name: multi_use
          description: |
            Indicates the tokenization module whether the payment card token should be generated either for a single-use or a multi-use.
            Possible values:
            - `0`: Generates a single-use token
            - `1`: Generates a multi-use token

            While a single-use token is typically generated for a short time and for processing a single transaction, multi-use tokens are generally generated.
          in: formData
          required: false
          x-is-map: false
          type: integer
          default: 0
          enum:
            - 0
            - 1
        - name: generate_request_id
          description: Indicates if a request ID should be generated.
          in: formData
          required: false
          x-is-map: false
          type: integer
          default: 0
          enum:
            - 0
            - 1
      responses:
        '201':
          description: Token successfully created.
          schema:
            $ref: "#/definitions/Token"
        '400':
          description: The request was rejected due to a validation error.
          schema:
            type: object
            required:
              - code
              - message
              - description
            properties:
              code:
                type: integer
              message:
                type: string
              description:
                type: string
        '401':
          description: An authentication error occurred/invalid credentials.
          schema:
            type: object
            required:
              - code
              - message
              - description
            properties:
              code:
                type: integer
              message:
                type: string
              description:
                type: string
        '403':
          description: Access to this resource is fordidden.
          schema:
            type: object
            required:
              - code
              - message
              - description
            properties:
              code:
                type: integer
              message:
                type: string
              description:
                type: string
      security:
        - basicAuth: []
  '/{token}':
    get:
      tags:
        - tokenization
      summary: Gets the details of a credit card that you have previously tokenized
      description: Gets the details of a credit card that you have previously tokenized.
      operationId: lookupToken
      produces:
        - application/json
      parameters:
        - name: token
          description: The token to look for.
          in: path
          required: true
          x-is-map: false
          type: string
          default: 85a934ff3621385cd1ee8fe4c29c15da9c0a9eede1ed5f3511329844d9bf1388
        - name: request_id
          description: The request ID linked to the card token.
          in: query
          required: true
          x-is-map: false
          type: string
          default: '0'
      responses:
        '200':
          description: Token successfully retrieved.
          schema:
            $ref: "#/definitions/Token"
        '400':
          description: The request was rejected due to a validation error.
          schema:
            type: object
            required:
              - code
              - message
              - description
            properties:
              code:
                type: integer
              message:
                type: string
              description:
                type: string
        '401':
          description: An authentication error occurred/invalid credentials.
          schema:
            type: object
            required:
              - code
              - message
              - description
            properties:
              code:
                type: integer
              message:
                type: string
              description:
                type: string
        '403':
          description: Access to this resource is fordidden.
          schema:
            type: object
            required:
              - code
              - message
              - description
            properties:
              code:
                type: integer
              message:
                type: string
              description:
                type: string
        '404':
          description: Token was not found.
          schema:
            type: object
            required:
              - code
              - message
              - description
            properties:
              code:
                type: integer
              message:
                type: string
              description:
                type: string
      security:
        - basicAuth: []
  /:
    delete:
      tags:
        - tokenization
      summary: Delete a previously created token
      description: Delete a previously created token
      operationId: deleteToken
      parameters:
        - name: card_token
          in: formData
          type: string
          description: The token to be deleted.
          required: true
          x-is-map: false
      responses:
        '204':
          description: Token successfully deleted.
        '400':
          description: Invalid card token
          schema:
            type: object
            required:
              - code
              - message
              - description
            properties:
              code:
                type: integer
                example: 400
              message:
                type: string
                example: Invalid cardToken
              description:
                type: object
                example: {'code': 400, 'message': 'Invalid cardToken'}
        '401':
          description: Incorrect Credentials _ Username and / or password is incorrect
          schema:
            type: object
            required:
              - code
              - message
              - description
            properties:
              code:
                type: integer
                example: 1000001
              message:
                type: string
                example: Incorrect Credentials _ Username and / or password is incorrect
              description:
                type: object
                example: {'code': 1000001, 'message': 'Incorrect Credentials _ Username and / or password is incorrect'}
        '403':
          description: Forbidden
          schema:
            type: object
            required:
              - code
              - message
            properties:
              code:
                type: integer
                example: 403
              message:
                type: string
                example: Forbidden
        '404':
          description: Card token not found
          schema:
            type: object
            required:
              - code
              - message
              - description
            properties:
              code:
                type: integer
                example: 404
              message:
                type: string
                example: Card token not found
              description:
                type: object
                example: {'code': 404, 'message': 'Card token not found'}
      security:
        - basicAuth: []
  /update:
    post:
      tags:
        - tokenization
      summary: Updates the details of a previsouly tokenized credit or debit card
      description: Updates the details of a previsouly tokenized credit or debit card.
      operationId: updateToken
      produces:
        - application/json
      parameters:
        - name: card_token
          in: formData
          description: The token to be updated.
          required: true
          x-is-map: false
          type: string
          default: 85a934ff3621385cd1ee8fe4c29c15da9c0a9eede1ed5f3511329844d9bf1388
        - name: request_id
          in: formData
          description: The request ID linked to the card token.
          required: true
          x-is-map: false
          type: string
          default: '0'
        - name: card_expiry_month
          description: The card expiry month.
          in: formData
          required: true
          x-is-map: false
          type: integer
          default: 12
        - name: card_expiry_year
          description: The card expiry year.
          in: formData
          required: true
          x-is-map: false
          type: integer
          default: 2025
        - name: card_holder
          description: The cardholder name as it appears on the card.
          in: formData
          required: true
          x-is-map: false
          type: string
          default: Cathy Doe
        - name: cvc
          description: The 3 or 4 digit security code (called CVV2 or CID depending on the card brand) that appears on the credit card.
          in: formData
          required: false
          x-is-map: false
          type: string
          default: '514'
          pattern: |
            (\d{3})|(\d{4})
      responses:
        '200':
          description: Token successfully updated.
          schema:
            type: object
            required:
              - token
              - request_id
              - card_holder
              - card_expiry_month
              - card_expiry_year
            properties:
              token:
                type: string
                example: "85a934ff3621385cd1ee8fe4c29c15da9c0a9eede1ed5f3511329844d9bf1388"
              request_id:
                type: string
                example: "0"
              card_holder:
                type: string
                example: "Cathy Doe"
              card_expiry_month:
                type: string
                example: "02"
              card_expiry_year:
                type: string
                example: "2025"
        '400':
          description: The request was rejected due to a validation error.
          schema:
            type: object
            required:
              - code
              - message
              - description
            properties:
              code:
                type: integer
              message:
                type: string
              description:
                type: string
        '401':
          description: An authentication error occurred/invalid credentials.
          schema:
            type: object
            required:
              - code
              - message
              - description
            properties:
              code:
                type: integer
              message:
                type: string
              description:
                type: string
        '403':
          description: Access to this resource is fordidden.
          schema:
            type: object
            required:
              - code
              - message
              - description
            properties:
              code:
                type: integer
              message:
                type: string
              description:
                type: string
        '404':
          description: Token was not found.
          schema:
            type: object
            required:
              - code
              - message
              - description
            properties:
              code:
                type: integer
              message:
                type: string
              description:
                type: string
      security:
        - basicAuth: []
definitions:
  Token:
    type: object
    required:
      - token
      - request_id
      - card_hash
      - card_id
      - brand
      - pan
      - card_holder
      - card_expiry_month
      - card_expiry_year
      - issuer
      - country
    properties:
      token:
        type: string
        example: "85a934ff3621385cd1ee8fe4c29c15da9c0a9eede1ed5f3511329844d9bf1388"
      request_id:
        description: The request ID linked to the token.
        type: string
        example: "0"
      card_hash:
        description: Card token in SHA1. Deprecated
        type: string
        example: "ce5f096fa6bc05989c170e7c96f94432660491bd"
      card_id:
        description: Unique card identifier.
        type: string
        example: "96ada09f-a844-4956-9593-cb758630dac2"
      brand:
        description: Card brand. (e.g., Visa, MasterCard, American Express, JCB, Discover, Diners Club, Solo, Laser, Maestro).
        type: string
        example: "VISA"
      pan:
        description: Card number (up to 19 characters). Note that, due to the PCI DSS security standards, our system has to mask credit card numbers in any output (e.g., 549619******4769).
        type: string
        example: "400000xxxxxx0002"
      card_holder:
        description: Cardholder name.
        type: string
        example: "Cathy Doe"
      card_expiry_month:
        description: Card expiry month (2 digits).
        type: string
        example: "12"
      card_expiry_year:
        description: Card expiry year (4 digits).
        type: string
        example: "2025"
      issuer:
        description: Card issuing bank name. Do not rely on this value to remain static over time. Bank names may change over time due to acquisitions and mergers.
        type: string
        example: "BNP PARIBAS"
      country:
        description: Bank country code where card was issued. This two-letter country code complies with ISO 3166-1 (alpha 2).
        type: string
        example: "US"
      domestic_network:
        description: Card domestic network (if applicable, e.g. “cb”).
        type: string
        example: "cb"
      card_type:
        description: Type of the card. (e.g.; Debit card, Credit card, Charge card, ATM card ...)
        type: string
        example: "CREDIT"
      card_category:
        description: Category of the card. (e.g., Classic, Business, Electron, Gold ...)
        type: string
        example: "PURCHASING"
      forbidden_issuer_country:
        description: Indicates whether the card country is authorized.
        type: boolean
        example: false