openapi: 3.2.0
info:
  title: Tokenization Token Lifecycle 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: Token Lifecycle Management
  description: Manage or request token state information.
paths:
  /tokens/{token-reference-id}/lifecycle-states:
    patch:
      summary: Token lifecycle management request
      operationId: v1UpdateTokenStateByTokenReferenceId
      tags:
      - Token Lifecycle Management
      description: Manages the token lifecycle state.
      parameters:
      - name: merchantId
        in: header
        required: true
        schema:
          type: string
          minLength: 8
          maxLength: 12
        description: Identifier for the merchant account.
        examples:
          Lifecycle SUSPEND request:
            value: '991234567890'
          Lifecycle RESUME request:
            value: '991234567891'
          Lifecycle DELETE request:
            value: '991234567892'
      - name: requestId
        in: header
        required: true
        schema:
          type: string
          format: uuid
        description: Merchant identifier for the request. The value must be unique.
        examples:
          Lifecycle SUSPEND request:
            value: 10cc0270-7bed-11e9-a188-1763956dd7f6
          Lifecycle RESUME request:
            value: 11cc0270-7bed-11e9-a188-1763956dd7f6
          Lifecycle DELETE request:
            value: 12cc0270-7bed-11e9-a188-1763956dd7f6
      - name: token-reference-id
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: Reference identifier for a specific token.
        examples:
          Lifecycle SUSPEND request:
            value: fb0dabc0-da2c-46b6-b3a3-8fc6d3190e88
          Lifecycle RESUME request:
            value: fb0dabc0-da2c-46b6-b3a3-8fc6d3190e98
          Lifecycle DELETE request:
            value: fb0dabc0-da2c-46b6-b3a3-8fc6d3190e68
      requestBody:
        description: Token Lifecycle Management
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/tokenLifecycleRequest'
            examples:
              Lifecycle SUSPEND request:
                value:
                  paymentInstrument:
                    lifecycleManagementAction:
                      stateChangeReason: SUSPEND
                      stateChangeReasonText: Consumer suspended subscription
              Lifecycle RESUME request:
                value:
                  paymentInstrument:
                    lifecycleManagementAction:
                      stateChangeReason: RESUME
                      stateChangeReasonText: Consumer resumed subscription
              Lifecycle DELETE request:
                value:
                  paymentInstrument:
                    lifecycleManagementAction:
                      stateChangeReason: DELETE
                      stateChangeReasonText: Consumer cancelled subscription
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/tokenLifecycleResponse'
              examples:
                Lifecycle SUSPEND request:
                  value:
                    identifier: d389b100-37b1-4239-96f3-7340a75045c6
                    timestamp: '2021-09-15T19:52:48.801Z'
                    cardTokenStatus: SUSPENDED
                    stateChangeReason: SUSPEND
                    tokenReferenceIdentifier: fb0dabc0-da2c-46b6-b3a3-8fc6d3190e88
                    requestIdentifier: 10cc0270-7bed-11e9-a188-1763956dd7f6
                    responseStatus: SUCCESS
                    responseCode: ACCEPTED
                    responseMessage: The request is well received.
                Lifecycle RESUME request:
                  value:
                    identifier: d389b100-37b1-4239-96f3-7340a75045c6
                    timestamp: '2021-09-15T19:52:48.801Z'
                    cardTokenStatus: ACTIVE
                    stateChangeReason: RESUME
                    tokenReferenceIdentifier: fb0dabc0-da2c-46b6-b3a3-8fc6d3190e98
                    requestIdentifier: 11cc0270-7bed-11e9-a188-1763956dd7f6
                    responseStatus: SUCCESS
                    responseCode: ACCEPTED
                    responseMessage: The request is well received.
                Lifecycle DELETE request:
                  value:
                    identifier: d389b100-37b1-4239-96f3-7340a75045c6
                    timestamp: '2021-09-15T19:52:48.801Z'
                    cardTokenStatus: DELETED
                    stateChangeReason: DELETE
                    tokenReferenceIdentifier: fb0dabc0-da2c-46b6-b3a3-8fc6d3190e68
                    requestIdentifier: 12cc0270-7bed-11e9-a188-1763956dd7f6
                    responseStatus: SUCCESS
                    responseCode: ACCEPTED
                    responseMessage: The request is well received.
        '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'
        '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: Request token states
      operationId: v1GetTokenStateByTokenReferenceId
      tags:
      - Token Lifecycle Management
      description: Request token lifecycle state information.
      parameters:
      - name: tokenRequestorId
        in: header
        schema:
          type: string
        description: Identifies a unique occurrence of the pairing of the token requestor with the token domain.
        examples:
          Success:
            value: '10012345678'
          Error:
            value: '10012345688'
      - name: merchantId
        in: header
        required: true
        schema:
          type: string
          example: '991234567890'
          minLength: 8
          maxLength: 12
        description: Identifier for the merchant account.
        examples:
          Success:
            value: '991234567890'
          Error:
            value: '991234567891'
      - 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
          Error:
            value: 20cc0270-7bed-11e9-a188-1763956dd7f6
      - name: token-reference-id
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: Reference identifier for a specific token.
        examples:
          Success:
            value: fb0dabc0-da2c-46b6-b3a3-8fc6d3190e88
          Error:
            value: fb0dabc0-da2c-46b6-b3a3-8fc6d3190e98
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/tokenInformationResponse'
              examples:
                Success:
                  value:
                    identifier: fb0dabc0-da2c-46b6-b3a3-8fc6d3190e98
                    timestamp: '2021-09-15T19:52:48.801Z'
                    paymentInstrument:
                      tokenReferenceIdentifier: fb0dabc0-da2c-46b6-b3a3-8fc6d3190e88
                      cardTokenStatus: ACTIVE
                      stateChangeReason: RESUME
                      stateChangeTimestamp: '2021-09-15T19:52:48.801Z'
                    requestIdentifier: 10cc0270-7bed-11e9-a188-1763956dd7f6
                    responseStatus: SUCCESS
                    responseCode: ACCEPTED
                    responseMessage: The request is well received.
        '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:
    tokenLifecycleRequest:
      description: Manage the lifecycle of a token on file.
      type: object
      properties:
        merchant:
          $ref: '#/components/schemas/tokenLifecycleMercant'
        paymentInstrument:
          $ref: '#/components/schemas/tokenLifecyclePaymentInstrument'
    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
    tokenLifecyclePaymentInstrument:
      description: Manage the lifecycle of a token on file
      type: object
      properties:
        lifecycleManagementAction:
          $ref: '#/components/schemas/lifecycleManagementAction'
    tokenInfoMerchant:
      description: Current information and status of a token
      type: object
      properties:
        tokenRequestorIdentifier:
          $ref: '#/components/schemas/tokenRequestorIdentifier'
    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'
    tokenLifecycleMercant:
      description: Manage the lifecycle of a token on file
      type: object
      required:
      - tokenRequestorIdentifier
      properties:
        merchantDoingBusinessAs:
          $ref: '#/components/schemas/merchantDoingBusinessAs'
        tokenRequestorIdentifier:
          $ref: '#/components/schemas/tokenRequestorIdentifier'
    identifier:
      description: It is the resource identifier for a given merchant request, provided/generated by JPMC.
      type: string
      format: uuid
      maxLength: 40
    lifecycleManagementAction:
      description: Manage the lifecycle of a token on file
      type: object
      properties:
        stateChangeReason:
          $ref: '#/components/schemas/stateChangeReason'
        stateChangeReasonText:
          description: Description of the rationale for changing the token status.
          type: string
          maxLength: 64
    merchantDoingBusinessAs:
      description: Alternate name for the merchant if it exists (trading name).
      type: string
      example: Acme New York, Llc
    tokenInformationResponse:
      description: Current information and status of a token.
      type: object
      properties:
        identifier:
          $ref: '#/components/schemas/identifier'
        timestamp:
          $ref: '#/components/schemas/timestamp'
        merchant:
          $ref: '#/components/schemas/tokenInfoMerchant'
        paymentInstrument:
          $ref: '#/components/schemas/tokenInfoPaymentInstrument'
        requestIdentifier:
          $ref: '#/components/schemas/requestIdentifier'
        responseStatus:
          $ref: '#/components/schemas/responseStatus'
        responseCode:
          $ref: '#/components/schemas/responseCode'
        responseMessage:
          $ref: '#/components/schemas/responseMessage'
    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
    tokenRequestorIdentifier:
      description: Identifier for the merchant given by payment networks or token provider.
      type: string
      pattern: ^\d{11}$
      example: '10012345678'
    responseCode:
      description: Short explanation of the response code.
      type: string
      readOnly: true
      minLength: 2
      maxLength: 50
      example: ACCEPTED
    timestamp:
      description: Designates the date, hour, minute and second when response was provided for a request. Using ISO 8601 date-time format.
      type: string
      format: date-time
    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
    tokenLifecycleResponse:
      description: Response to a lifecycle request.
      type: object
      required:
      - identifier
      - tokenReferenceIdentifier
      properties:
        identifier:
          $ref: '#/components/schemas/identifier'
        timestamp:
          $ref: '#/components/schemas/timestamp'
        cardTokenStatus:
          $ref: '#/components/schemas/cardTokenStatus'
        previousCardTokenStatus:
          $ref: '#/components/schemas/cardTokenStatus'
        stateChangeReasonCode:
          $ref: '#/components/schemas/stateChangeReasonCode'
        stateChangeReason:
          $ref: '#/components/schemas/stateChangeReason'
        tokenReferenceIdentifier:
          $ref: '#/components/schemas/tokenReferenceIdentifier'
        requestIdentifier:
          $ref: '#/components/schemas/requestIdentifier'
        responseStatus:
          $ref: '#/components/schemas/responseStatus'
        responseCode:
          $ref: '#/components/schemas/responseCode'
        responseMessage:
          $ref: '#/components/schemas/responseMessage'
    responseStatus:
      description: Request result status.
      type: string
      readOnly: true
      example: SUCCESS
      enum:
      - SUCCESS
      - ERROR
    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
    cardTokenStatus:
      description: Current state of the token.
      type: string
      enum:
      - ACTIVE
      - DELETED
      - INACTIVE
      - SUSPENDED
    tokenInfoPaymentInstrument:
      description: Current information and status of a token
      type: object
      required:
      - tokenReferenceIdentifier
      properties:
        tokenReferenceIdentifier:
          $ref: '#/components/schemas/tokenReferenceIdentifier'
        cardTokenStatus:
          $ref: '#/components/schemas/cardTokenStatus'
        previousCardTokenStatus:
          $ref: '#/components/schemas/cardTokenStatus'
        stateChangeReason:
          $ref: '#/components/schemas/stateChangeReason'
        stateChangeReasonText:
          description: Description of the rationale for changing the token status.
          type: string
          maxLength: 64
        stateChangeTimestamp:
          description: Date and time when change was recorded
          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
    stateChangeReason:
      description: Lifecycle action requested by merchant for a token.
      type: string
      enum:
      - SUSPEND
      - DELETE
      - RESUME
    stateChangeReasonCode:
      description: Codifies the reason code for Token account level change.
      type: string
      enum:
      - ACTIVATED_BY_CUSTOMER_SERVICE
      - ACTIVATED_BY_COBADGED_TOKEN
      - ACTIVATED_BY_ISSUER
      - ACTIVATED_BY_ISSUER_APP
      - ACTIVATED_BY_USER_REQUEST
      - SUSPENDED_BY_ISSUER
      - SUSPENDED_BY_TR_DUE_TO_FRAUD
      - SUSPENDED_BY_USER_REQUEST
      - SUSPENDED_BY_CUSTOMER_SERVICE
      - SUSPENDED_BY_TR
      - RESUMED_BY_ISSUER
      - RESUMED_BY_USER_REQUEST
      - RESUMED_BY_CUSTOMER_SERVICE
      - RESUMED_BY_TR
      - RPAN_UPDATE
      - DELETED_FOR_SECURITY
      - DELETED_BY_CUSTOMER_SERVICE
      - DELETED_BY_ISSUER
      - DELETED_DUE_TO_FRAUD
      - DELETED_BY_USER_REQUEST
      - DELETED_DUE_TO_TOKEN_PROBLEM
      - DELETED_BY_TIME_LIMIT
      - DELETED_BY_TR
      - DELETED__BY_TR_DUE_TO_FRAUD
      - DELETED_DUE_TO_ERROR
      - STATE_CHANGED_ON_DEVICE
      - UNKNOWN_REASON_CODE
  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