openapi: 3.2.0
info:
  title: Tokenization Bulk Operation 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 Operation
  description: Bulk Token Operation.
paths:
  /bulk-tokens:
    post:
      summary: Process Bulk Tokens
      operationId: v1BulkTokenPost
      tags:
      - Bulk Operation
      description: Request bulk upload of token request
      parameters:
      - name: merchantId
        in: header
        required: true
        schema:
          type: string
          minLength: 8
          maxLength: 12
        description: Identifier for the merchant account.
        examples:
          Successful Bulk Tokenization:
            value: '991234567890'
      - name: requestId
        in: header
        required: true
        schema:
          type: string
          format: uuid
        description: Merchant identifier for the request. The value must be unique.
        examples:
          Successful Bulk Tokenization:
            value: 20cc0270-7bed-11e9-a188-1763956dd7f6
      - name: isEncrypted
        in: header
        schema:
          type: boolean
          example: true
        description: Indicates the message body of a transmitted message containing the actual data for a specific purpose is encrypted.
        examples:
          Successful Bulk Tokenization:
            value: true
      requestBody:
        description: Process Bulk Tokens
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                fileRecordCount:
                  description: Enumerates the quantity of records in a data object that is processed or transmitted.
                  type: integer
                  format: int32
                  example: 10
                merchantFileIdentifier:
                  description: A unique number assigned to a data file containing one or more records that is processed or transmitted. In this context, this is the unique identifier of the file provided by merchant.
                  type: string
                  example: '123'
                fileName:
                  description: The label given to a data file containing zero or more records that is processed or transmitted.
                  type: string
                  example: sample-123.txt
                fileCreationDate:
                  description: Designates the year, month and day on which the file was created.
                  type: string
                  example: 09/08/2022
                fileData:
                  description: Merchant provided data in base64 encoded format for token update.
                  type: string
          application/json:
            schema:
              $ref: '#/components/schemas/tokenBulkRequest'
            examples:
              Successful Bulk Tokenization:
                value:
                  fileRecordCount: 10
                  merchantFileIdentifier: '123'
                  fileName: sample-123.txt
                  fileCreationDate: 09/08/2022
                  fileData: 0,123456789012,20220124,D,PAN2NWT
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/tokenBulkPostResponse'
              examples:
                Successful Bulk Tokenization:
                  value:
                    fileInformation:
                      batchFileIdentifier: 379f0966-71a1-4db5-b1b3-0e87cb864ff0
                      fileName: sample-123.txt
                      merchantFileIdentifier: '123'
                      fileRecordCount: 10
                      fileReceivedTimestamp: 09/08/2022
                    messages:
                      responseStatus: SUCCESS
                      responseCode: ACCEPTED
                      responseMessage: 'Upload Successful Batch Id: 5e339850-4a5f-482e-9afb-79870d4056cf'
                    requestIdentifier: 379f0966-71a1-4db5-b1b3-0e87cb864ff0
        '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'
  /bulk-tokens/{merchant-file-identifier}:
    get:
      summary: Retrieve the status of a bulk file
      operationId: v1BulkTokenByIdGet
      tags:
      - Bulk Operation
      description: Request bulk upload of token request
      parameters:
      - name: merchantId
        in: header
        required: true
        schema:
          type: string
          minLength: 8
          maxLength: 12
        description: Identifier for the merchant account.
        examples:
          Success:
            value: '991234567890'
          Error:
            value: '991234567891'
      - name: merchant-file-identifier
        in: path
        required: true
        schema:
          type: string
        description: This is used for specifying individual parameters under API endpoint methods.
        examples:
          Success:
            value: '123'
          Error:
            value: '999'
      - 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: 30cc0270-7bed-11e9-a188-1763956dd7f6
          Error:
            value: 40cc0270-7bed-11e9-a188-1763956dd7f6
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/messages'
              examples:
                Successful Bulk Tokenization:
                  value:
                    responseStatus: SUCCESS
                    responseCode: ACCEPTED
                    responseMessage: 'Upload Successful Batch Id: 5e339850-4a5f-482e-9afb-79870d4056cf'
        '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'
              examples:
                Error:
                  value:
                    responseStatus: ERROR
                    responseCode: NOT_FOUND
                    responseMessage: Transaction was not found
        '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'
  /bulk-tokens/{merchant-file-identifier}/download:
    get:
      summary: Retrieve details of a bulk file
      operationId: v1BulkTokenDownloadGet
      tags:
      - Bulk Operation
      description: Request bulk upload of token request
      parameters:
      - name: merchantId
        in: header
        required: true
        schema:
          type: string
          minLength: 8
          maxLength: 12
        description: Identifier for the merchant account.
        examples:
          Success:
            value: '991234567890'
          Error:
            value: '991234567891'
      - name: merchant-file-identifier
        in: path
        required: true
        schema:
          type: string
        description: This is used for specifying individual parameters under API endpoint methods.
        examples:
          Success:
            value: '123'
          Error:
            value: '999'
      - 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: 50cc0270-7bed-11e9-a188-1763956dd7f6
          Error:
            value: 60cc0270-7bed-11e9-a188-1763956dd7f6
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/downloadResponse'
              examples:
                Successful Bulk Tokenization:
                  value:
                    batchFileIdentifier: 379f0966-71a1-4db5-b1b3-0e87cb864ff0
                    errorCount: 0
                    processedCount: 10
                    merchantFileIdentifier: '123'
        '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'
              examples:
                Error:
                  value:
                    responseStatus: ERROR
                    responseCode: NOT_FOUND
                    responseMessage: Transaction was not found
        '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:
    downloadResponse:
      description: Response for download
      type: object
      properties:
        batchFileIdentifier:
          description: A unique number assigned to a data file containing one or more records that is processed or transmitted.
          type: string
        errorCount:
          description: Enumerates the quantity of records in a data object that is processed or transmitted. In this context, this is the number of records did not process correctly.
          type: integer
          format: int64
        processedCount:
          description: Enumerates the quantity of records in a data object that is processed or transmitted. In this context, this is the number of records processed correctly.
          type: integer
          format: int64
        processCompleteTimestamp:
          description: Designates the hour, minute, and second in a specific day when a task such as record or file processing ends.
          type: string
        merchantFileIdentifier:
          description: A unique number assigned to a data file containing one or more records that is processed or transmitted. In this context, this is the unique identifier of the file provided by merchant.
          type: string
        message:
          $ref: '#/components/schemas/message'
    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
    tokenBulkRequest:
      description: This is used for specifying an attribute used on a model for object that will contain one or more attributes
      type: object
      properties:
        fileRecordCount:
          description: Enumerates the quantity of records in a data object that is processed or transmitted.
          type: integer
          format: int32
          example: 10
        merchantFileIdentifier:
          description: A unique number assigned to a data file containing one or more records that is processed or transmitted. In this context, this is the unique identifier of the file provided by merchant.
          type: string
          example: '123'
        fileName:
          description: The label given to a data file containing zero or more records that is processed or transmitted.
          type: string
          example: sample-123.txt
        fileCreationDate:
          description: Designates the year, month and day on which the file was created.
          type: string
          example: 09/08/2022
        fileData:
          description: Merchant provided data in base64 encoded format for token update.
          type: string
    fileInformation:
      description: Batch file informtion containg tokens from merchant
      type: object
      properties:
        batchFileIdentifier:
          description: A unique number assigned to a data file containing one or more records that is processed or transmitted.
          type: string
        fileName:
          description: The label given to a data file containing zero or more records that is processed or transmitted.
          type: string
        merchantFileIdentifier:
          description: A unique number assigned to a data file containing one or more records that is processed or transmitted.  In this context, this is the unique identifier of the file provided by merchant.
          type: string
        fileRecordCount:
          description: Enumerates the quantity of records in a data object that is processed or transmitted.
          type: integer
          format: int32
        fileReceivedTimestamp:
          description: Designates the hour, minute, and second in a specific day when the file was received by the processing system.
          type: string
    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'
    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
    tokenBulkPostResponse:
      description: Batch file information containing tokens from merchant
      type: object
      properties:
        fileInformation:
          $ref: '#/components/schemas/fileInformation'
        messages:
          $ref: '#/components/schemas/messages'
        requestIdentifier:
          $ref: '#/components/schemas/requestIdentifier'
    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
    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