openapi: 3.2.0
info:
  title: Tokenization Bulk Key Management API
  description: Merchant Services Tokenization APIs enable merchants to secure their cards on file by replacing the sensitive Primary Account Number (PAN) with a token. Currently supports network tokenization via Mastercard, Visa & Amex.
  version: 1.5.0
  contact:
    name: Tokenization API Support
    url: https://developer.payments.jpmorgan.com/contact
servers:
- url: https://api.merchant.jpmorgan.com/payments/v1/
  description: PRODUCTION - OAUTH
- url: https://api-test.merchant.jpmorgan.com/payments/v1/
  description: CLIENT TESTING - OAUTH
- url: https://api-mock.payments.jpmorgan.com/payments/v1
  description: MOCK
security:
- BearerAuth: []
tags:
- name: Bulk Key Management
  description: Bulk Key Management
paths:
  /bulk-tokens/encryption-key:
    post:
      summary: Create encryption key from a merchant
      operationId: v1BulkTokenKeyManagementPost
      tags:
      - Bulk Key Management
      description: Request to create the public key from a merchant to firm for bulk tokenization
      parameters:
      - name: merchantId
        in: header
        required: true
        schema:
          type: string
          minLength: 8
          maxLength: 12
        description: Identifier for the merchant account.
        examples:
          Success:
            value: '9912345678'
      - name: requestId
        in: header
        required: true
        schema:
          type: string
          format: uuid
        description: Merchant identifier for the request. The value must be unique.
        examples:
          Success:
            value: 10cc0270-7bed-11e9-a188-1763956dd7f6
      requestBody:
        description: Create Encryption Key
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/keyManagementRequest'
            examples:
              Success:
                value:
                  publicKeyText: '-----BEGIN PGP PUBLIC KEY BLOCK----- mI0EZDWyKwEEAPIwHMin2LzgTWj6JGGk6iXPFheSwxmMJQgnhEWNAnLUPNEGzFNh vH+1/J58wgAAUb1+/C/7QuMSZ1kYrH6J7lO5SIf9yMuB8f9BO7ZlXU4FR80ollbh 468dcxORBhQwqCOY7k6J7G9giFofSzcvxdKuKZw8ACpIjyWZDMda/nzFABEBAAG0 KUF1dG9nZW5lcmF0ZWQgS2V5IDx3NTk3NTg0QGNoY2FyMjI4YzI1bjE+iM4EEwEI ADgWIQRv1korTacF2a3w0YNhW9cYyCSY7QUCZDWyKwIbLwULCQgHAgYVCgkICwIE FgIDAQIeAQIXgAAKCRBhW9cYyCSY7UufA/4nOw2DJJcAftRqa62ViBBIJTmh69/X Vjpt6s4RzLGPvsZu6A3Z+pW1KWAk/j+As0bKf4cKIgkdZuMXFcmyN9KYnFRjcPRH Diplb+j+kH+zBv/sFDbfcOBWJ7BViwkXpJnke2O5gsLZU8m42izYK262szQbv828 E9BNpzV2cPX/Mg== =hix+ -----END PGP PUBLIC KEY BLOCK-----'
                  digitalDeviceFingerprintIdentifier: 6FD64A2B4DA705D9ADF0D183615BD718C82498ED
                  publicKeyExpirationTimestamp: '1680364800'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/messages'
              examples:
                Success:
                  value:
                    responseStatus: SUCCESS
                    responseCode: ACCEPTED
                    responseMessage: Successfully created encryption key
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/messages'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/adfsError'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/messages'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/tokenProvisionDuplicateResponse'
        '412':
          description: Precondition Failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/messages'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/messages'
        '503':
          description: Service Unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/messages'
        '504':
          description: Gateway Timeout
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/messages'
    get:
      summary: Provide public key to a merchant
      operationId: v1BulkTokenKeyManagementGet
      tags:
      - Bulk Key Management
      description: Request to provide the public key from firm to a merchant for bulk tokenization
      parameters:
      - name: merchantId
        in: header
        required: true
        schema:
          type: string
          minLength: 8
          maxLength: 12
        description: Identifier for the merchant account.
        examples:
          Success:
            value: '9912345678'
      - name: requestId
        in: header
        required: true
        schema:
          type: string
          format: uuid
        description: Merchant identifier for the request. The value must be unique.
        examples:
          Success:
            value: 10cc0270-7bed-11e9-a188-1763956dd7f6
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/keyManagementResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/messages'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/adfsError'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/messages'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/messages'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/messages'
        '503':
          description: Service Unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/messages'
        '504':
          description: Gateway Timeout
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/messages'
components:
  schemas:
    validationMessage:
      description: Object containing information about transaction validation.
      type: object
      required:
      - code
      - message
      properties:
        code:
          $ref: '#/components/schemas/code'
        message:
          $ref: '#/components/schemas/message'
        entity:
          description: Information about the entity that experienced an error.
          type: string
    adfsError:
      description: Object containing information about the active directory file system error.
      type: object
      required:
      - errorSource
      - errorCode
      - errorDescription
      properties:
        errorSource:
          description: The label of the component from where the error or warning is generated.
          type: string
          example: APG-EDGE
        errorCode:
          description: General status of all resources
          type: string
          example: EDG00012
        errorDescription:
          description: Long explanation of code returned by the computer system application that either indicates successful processing, or a given number that can be investigated by support staff for further resolution and troubleshooting.
          type: string
          example: the signature could not be verified
    messages:
      description: A list of errors and warnings.
      type: object
      required:
      - responseStatus
      - responseCode
      properties:
        responseStatus:
          $ref: '#/components/schemas/responseStatus'
        responseCode:
          $ref: '#/components/schemas/responseCode'
        responseMessage:
          $ref: '#/components/schemas/responseMessage'
        validationErrors:
          type: array
          minItems: 0
          description: This is used for specifying an attribute used on a model for collection object that will contain one or more attributes
          items:
            $ref: '#/components/schemas/validationMessage'
    url:
      description: Reference to a web resource.
      type: string
      minLength: 0
      maxLength: 512
      example: https://www.acmetest.test
    identifier:
      description: It is the resource identifier for a given merchant request, provided/generated by JPMC.
      type: string
      format: uuid
      maxLength: 40
    payload:
      description: Payload Object
      type: object
      properties:
        identifier:
          $ref: '#/components/schemas/identifier'
        requestIdentifier:
          $ref: '#/components/schemas/requestIdentifier'
        tokenReferenceIdentifier:
          $ref: '#/components/schemas/tokenReferenceIdentifier'
        cardMetaData:
          $ref: '#/components/schemas/cardMetaData'
    keyManagementResponse:
      description: Response object for Key management operation
      type: object
      properties:
        firmPublicKeyText:
          description: Provides textual information about a cipher key for exchanging data via an associated string or byte image. This is a public key generated by the firm and shared with merchant.
          type: string
          example: '-----BEGIN PGP PUBLIC KEY BLOCK----- XI0EZDWyKwEEAPIwHMin2LzgTWj6JGGk6iXPFheSwxmMJQgnhEWNAnLUPNEGzFNh vH+1/J58wgAAUb1+/C/7QuMSZ1kYrH6J7lO5SIf9yMuB8f9BO7ZlXU4FR80ollbh 468dcxORBhQwqCOY7k6J7G9giFofSzcvxdKuKZw8ACpIjyWZDMda/nzFABEBAAG0 KUF1dG9nZW5lcmF0ZWQgS2V5IDx3NTk3NTg0NYNoY2FyMjI4YzI1bjE+iM4EEwEI DDgWIQRv1korTacF2a3w0YNhW9cYyCSY7QUCZDWyKwIbLwULCQgHAgYVCgkICwIE YgIDAQIeAQIXgAAKCRBhW9cYyCSY7UufA/4nOw2DJJcAftRqa62ViBBIJTmh69/X Vjpt6s4RzLGPvsZu6A3Z+pW1KWAk/j+As0bKf4cKIgkdZuMXFcmyN9KYnFRjcPRH Diplb+j+kH+zBv/sFDbfcOBWJ7BViwkXpJnke2O5gsLZU8m42izYK262szQbv828 E9BNpzV2cPX/Mg== =hix+ -----END PGP PUBLIC KEY BLOCK-----'
    tokenReferenceIdentifier:
      description: Identifier given to a token at the time of provisioning. Can be used as a reference to the token number.
      type: string
      format: uuid
    cardMetaData:
      description: Information about the card related to a token.
      type: object
      properties:
        cardArtUrl:
          $ref: '#/components/schemas/url'
        backgroundCardGraphicsColor:
          description: Graphic color name of the card background.
          type: string
          maxLength: 32
          example: '#ffffff'
        foregroundCardGraphicsColor:
          description: Graphic color name of the card foreground.
          type: string
          maxLength: 32
          example: '#0033cc'
        labelCardGraphicsColor:
          description: Graphic color name of the card label.
          type: string
          maxLength: 32
          example: '#33cc33'
        cardDescription:
          description: Detail information of the card provided by card issuer.
          type: string
          maxLength: 256
        issuerInformation:
          $ref: '#/components/schemas/issuerInformation'
        cardShortDescription:
          description: Provides summary-level detail information of the card product provided by card issuer.
          type: string
          maxLength: 128
        cardTermsAndConditionsIdentifier:
          description: Unique identifier for the terms and conditions for a card specified by the card isuer. Merchant uses this identifier to track if terms have been updated and if a message is needed for the card holder to review new terms and conditions.
          type: string
          format: uuid
        cardTermsAndConditionsURL:
          $ref: '#/components/schemas/url'
        cardAssetData:
          $ref: '#/components/schemas/cardAssetData'
    responseCode:
      description: Short explanation of the response code.
      type: string
      readOnly: true
      minLength: 2
      maxLength: 50
      example: ACCEPTED
    cardAssetDataElement:
      description: Card assets which help to build virtual replication of actual physical card art.
      type: object
      properties:
        assetReferenceIdentifier:
          description: Unique identifier for card assets that helps to build virtual replication of actual physical card art.
          type: string
        assetType:
          description: Codifies the different nature, genres or categories of content assets that are published and/or presented by the Firm or third party.  Examples of content asset types include document, image, text, video.  Content asset is any written or audio visual content used by the Firm for various business purposes.
          type: string
          enum:
          - CARD_ART_FOREGROUND
          - CARD_ART_BACKGROUND
          - ICON_ISSUER
          - TERMS_AND_CONDITIONS
          - COMBINED_BACKGROUND
          - ICON_PAYMENT_NETWORK
          - ICON_COBRAND
        mimeType:
          description: Label used to identify a type of data. This is used by data users so that they can handle the data properly.
          type: string
          enum:
          - IMAGE/PNG
          - IMAGE/PDF
          - IMAGE/JPEG
          - IMAGE/SVG+XML TEXT/HTML
          - TEXT/PLAIN
          - TEXT/XML
          - APPLICATION/PDF
        assetContent:
          description: Provides a textual version of card information that helps to build virtual replication of actual physical card art.
          type: string
          format: base64
        pixelHeight:
          description: The height of an image used for calculating image size. This is used to build virtual replication of actual physical card art.
          type: integer
          maximum: 4096
          example: 10
        pixelWidth:
          description: The width of an image used for calculating image size. This is used to build virtual replication of actual physical card art.
          type: integer
          maximum: 4096
          example: 12
    code:
      description: Codifies a raised exception encountered by an internal or external system, sub-system, interface, job, module, system component with which the web service application interfaces.  In this instance it refers to the error raised when reporting job failed.
      type: string
    responseStatus:
      description: Request result status.
      type: string
      readOnly: true
      example: SUCCESS
      enum:
      - SUCCESS
      - ERROR
    issuerInformation:
      description: Information about the card issuer
      type: object
      properties:
        cardIssuer:
          description: Financial institution authorized to issue cards with the payment brand logo.
          type: string
          maxLength: 128
        issuerAddress:
          description: Provides unformatted postal address information for the card issuer.
          type: string
        cardIssuerEmailAddress:
          description: Email address of the card issuer.
          type: string
          maxLength: 64
        issuerWebsiteURL:
          $ref: '#/components/schemas/url'
        cardIssuerCustomerServiceTelephone:
          description: Card issuer customer care telephone number.
          type: string
          maxLength: 12
        issuerOnlineBankingURL:
          $ref: '#/components/schemas/url'
        issuerIconURL:
          description: Site or link for the card issuer's image or symbol. Used by merchants to build a better consumer experience.
          type: string
          maxLength: 512
        issuerPrivacyURLText:
          $ref: '#/components/schemas/url'
        issuerLogoURLText:
          $ref: '#/components/schemas/url'
        issuerApplicationOS:
          description: Operating system of the issuing bank's mobile application
          type: string
          maxLength: 16
        issuerAppName:
          description: Issuing bank mobile application name for displaying to user.
          type: string
          maxLength: 128
        issuerAppAddress:
          description: Package name for issuing bank mobile application.
          type: string
          maxLength: 1024
    cardAssetData:
      type: array
      minItems: 0
      description: Card assets which help to build virtual replication of actual physical card art.
      items:
        $ref: '#/components/schemas/cardAssetDataElement'
    message:
      description: Provides textual description of a problem that has occurred and is preventing the system from completing a task. Messages can be a confirmation, warning or notification, and can trigger the system to apply a customized default value or override to a field, record or file, halt or postpone processing, skip or reject the entry generating the problem. Messages can be displayed on-screen in the user interface or in reporting.
      type: string
      readOnly: true
    keyManagementRequest:
      description: Request object for Key management operation
      type: object
      properties:
        publicKeyText:
          description: Provides textual information about a cipher key for exchanging data via an associated string or byte image. This is a public key generated by the merchant and shared with Firm.
          type: string
        digitalDeviceFingerprintIdentifier:
          description: Identifies a unique occurrence of an electronic device (and the software) used by the customer to communicate with the Firm or a third party to receive, store, process or send digital information.
          type: string
        publicKeyExpirationTimestamp:
          description: Designates the hour (hh), minute (mm), seconds (ss) and date (if timestamp) or year (YYYY), month (MM), and day (DD) (if date) when a public key generated by the merchant and shared with Firm is terminated.
          type: string
    responseMessage:
      description: Long explanation of the response message.
      type: string
      readOnly: true
      example: Request Accepted
    requestIdentifier:
      description: Merchant identifier for the request. The value must be unique.
      type: string
      maxLength: 40
    tokenProvisionDuplicateResponse:
      description: Token Provision Duplicate Response
      type: object
      properties:
        responseCode:
          $ref: '#/components/schemas/responseCode'
        responseMessage:
          $ref: '#/components/schemas/responseMessage'
        payload:
          $ref: '#/components/schemas/payload'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
x-jpmc-securityDefinitions:
  JPMC-OAuth2:
    jpmc-claims:
      jpmc-roles:
      - ADMIN_MS_PAYMENTS_TOKEN
      - CONSUMER_MS_PAYMENTS_TOKEN
      - 108970_TOKEN_MERCH_ACCESS
      - 108970_TOKEN_INTERNAL_PCI
x-jpmc-security:
- JPMC-OAuth2:
    jpmc-claims:
      jpmc-roles:
      - ADMIN_MS_PAYMENTS_TOKEN
      - CONSUMER_MS_PAYMENTS_TOKEN
      - 108970_TOKEN_MERCH_ACCESS
      - 108970_TOKEN_INTERNAL_PCI