openapi: 3.0.0
info:
  title: Hipay Payment Gateway balance tokenization API
  description: '## Version 1.6.1 - June 11, 2025


    The Gateway API allows you to get paid and manage orders and transactions.


    Please note: this documentation describes the Gateway API parameters and response fields and allows you to test the platform in real time.


    This page is to be used alongside the **[HiPay Enterprise Platform Overview documentation](https://developer.hipay.com/api-explorer/api-online-payments)**, which gives you more information and details on the HiPay Enterprise workflow. You may use both documents in parallel when integrating HiPay Enterprise.

    # Web service information

    ## Gateway API base URLs

    | Environment | Base URL |

    | --- | --- |

    | Stage | [https://stage-api-gateway.hipay.com](https://stage-api-gateway.hipay.com) |

    | Production |  [https://api-gateway.hipay.com](https://api-gateway.hipay.com) |

    ## Authentication

    All requests to the HiPay Enterprise API require identification through *HTTP Basic Authentication*. Your API credentials can be found in the Integration section of your HiPay Enterprise back office. 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>'')`

    '
  version: 1.6.1
servers:
- url: https://stage-api-gateway.hipay.com
  description: Stage
- url: https://api-gateway.hipay.com
  description: Production
tags:
- name: tokenization
  description: Everything you need to tokenize payment cards
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: []
components:
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
    ApiKeyAuth:
      type: apiKey
      name: X-API-KEY
      in: header
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
externalDocs:
  description: Find out more about HiPay
  url: https://developer.hipay.com/