---
swagger: "2.0"
info:
  version: 1.0.0-rev1
  title: E2E Key - CitiBanamexPay
  description: End to end encryption of sensitive data like passwords and one time
    pins is a security mandate in some countries. The /security resource allows you
    to exchange keys which are used for encryption and decryption. Key exchange methods
    differ depending on whether you already have a registered key or whether you need
    Citi to send you a key which can be used for encryption. You will receive eventID
    in the API response header, which should be used to encrypt the sensitive data.
    All encrypted data sent to Citi will give you an additional eventID in response
    header, this new eventID should be used for further encryptions.
  x-ibm-name: e2e-key---citibanamexpay
  name: ""
basePath: /api
schemes:
- https
x-ibm-configuration:
  enforced: true
  phase: realized
  testable: false
  externalDocs: []
  attachments: []
tags:
- name: E2E Key exchange
  description: ""
- name: E2E data encryption/decryption
  description: ""
definitions:
  StoreE2EKeyRequest:
    required:
    - encryptedKey
    - checkDigit
    type: object
    properties:
      encryptedKey:
        type: string
        description: The symmetric key encrypted with static RSA public key .This
          is a dynamic key for every session
        example: 93CDBEB681D937BAB1CED59789E02509A89BAD2407837D28CC32A80BFB7868BEEA202806CAD5B4E8F816F5507C3457CF752E3363B6F439F46855E9012715E6AA7DAF3AD02C681A12FB25C953092FC403B4E77B14E439BFF47C07CBB3AEFEAC28888997614BD925E5513B954CEFA3C945CE4B454638DBB69EC37A8B54E94A45A24A5F3AD9A5BEFB77A12EA1EEADCC3B023148929B5D8CBAC4325F311239CEB5B0F686549B008B6061529A26832B299209020FFB1B360AE6E01A7758ADBE843A63D3ABDA6862887010CBE35D8527B451D495883A278520D5E93787AA9105518DD9377F8F28F7C033F6EE6EFCE19648615C49ADE2F880DD113018B3FFD311FA55D646B1C79729D243D45A429C464DE2C43D
      checkDigit:
        type: string
        description: The check digit of the symmetric key used to compare with the
          check digit value of the decrypted AES key in server.
        example: 3A1AD9
      algorithm:
        type: string
        description: The algorithm for manipulating the symmetric key. Currently only
          AES algorithm is allowed. Default is AES algorithm.
        example: AES
  ErrorResponse:
    required:
    - type
    - code
    properties:
      type:
        type: string
        enum:
        - error
        - warn
        - invalid
        - fatal
        description: <br>invalid - Request did not confirm to the specification and
          was unprocessed & rejected. Please fix the value and try again</br>                         <br>warn
          - Request was partially processed.  E.g. some of the fields are missing
          in response to the system issues,  request was accepted successfully but
          will be processed asynchronously</br>                                                           <br>error
          - The request was accepted but could not be processed successfully</br>            <br>fatal
          - There was an internal system error while processing the request. These
          are technical errors and will be resolved by Citi, and the consumer should
          retry after some time. Business errors will not be categorized as fatal
          </br>
      code:
        type: string
        description: Error code which qualifies the error
      details:
        type: string
        description: Human readable explanation specific to the occurrence of the
          problem
      location:
        type: string
        description: The name of the field that resulted in the error
      moreInfo:
        type: string
        description: URI to human readable documentation of the error
securityDefinitions:
  ClientID:
    type: apiKey
    name: X-IBM-Client-Id
    in: header
    description: ClientID
  ClientID (Query):
    type: apiKey
    name: client_id
    in: query
    description: ClientID
paths:
  /v1/security/e2eKey:
    post:
      description: This API is used by Native applications for setting the session
        level key. The Key is generated on the device and transferred to this API.
        This key is encrypted with the Public key embedded inside the application.
        This API returns the encrypted eventID and expiration time in the header.
        <br> <br> Follow the below steps to encrypt the key.<br>1.Generate IV – convert
        to HEX 32 CHAR (This is so that server can encrypt the ServerRandom with this)<br>2.Generate
        256 bit AES key and convert to HEX<br>3.Generate check digit – CD<br>4.Encrypt
        AES key with RSA public key as – RSA(AES)<br>5.Frame the payload as – CD,
        IV(RSA[AES])
      tags:
      - E2E Key exchange
      summary: Used by Mobile App(Native) to Save the session level key for native
        applications.
      parameters:
      - default: 29738e5a-fbbf-4b55-981d-d2f3d2a60605
        description: The client ID  you received during application registration in
          the developer portal
        name: client_id
        type: string
        required: true
        in: header
      - default: Y2wwIEhvzLEVhkiGkF3hAAYhePuCT39lSyTz41+4JIXoxevJOQSwVanbHgDAeah+Xwqr5DO3b1f+YQIZ0ZCjitOMz3fmtXOO9QTwxUDoxMNTGYWuQVnq1ElO1qStxFGg0nHEgwPhfykc3g4cF/HmGksD73Naefo+xl6OPTDRCsQTz3/GS4sT5QA7U/QSDlGSWaRlyr5BBg9+YppAh+jQmKn2R3xd3Huhngp0M4kRx7zX28CziSBymBhjqnaXXFDuCu3pSFMl5bL+Peo9awnjx6tSDyohqDZj4tWDUfp4r3o=
        description: The most recent Authorization token
        name: Authorization
        type: string
        required: true
        in: header
      - default: en-US
        description: HTTP Accept-Language header
        name: Accept-Language
        type: string
        required: false
        in: header
      - default: application/json
        description: Content-Types that are acceptable for the response. Currently
          we support application/json
        name: Accept
        type: string
        required: true
        in: header
      - default: a7d1e304-83a9-4413-af97-62615e57eae66807840
        description: A 128 bit universally unique identifier (UUID) that you generate
          for every request and is used for tracking. It is recommended to use the
          output from Java UUID class or an equivalent.
        name: uuid
        type: string
        required: true
        in: header
      - default: application/json
        description: application/json
        name: Content-Type
        type: string
        required: true
        in: header
      - schema:
          type: object
          $ref: '#/definitions/StoreE2EKeyRequest'
        description: Request object with encrypted symmetric key to store. For now,
          we are allowing only AES as the algorithm of the symmetric key.
        name: storeE2EKeyRequest
        required: true
        in: body
      responses:
        200:
          description: Successfully stored Symmetric key and returned the encrypted
            event ID and expiration time in header.
          headers:
            eventID:
              description: This is a unique event id generated and encrypted with
                session key, which can be used to send in the next encrypted payload
                to validate.
              type: integer
              format: int64
            eventIDExpTime:
              description: Event ID expiration time encrypted with session key
              type: string
        400:
          description: (BAD REQUEST) - Request was not processed <table><tr><td>Type</td><td>Code</td><td>Details</td></tr><tr><td>invalid</td><td>invalidRequest</td><td>Missing
            or invalid Parameters</td></tr><tr><td>error</td><td>chkDigitNotMatch</td><td>Check
            digits do not match</td><tr><td>error</td><td>cannotDecryptKey</td><td>Key
            not properly encrypted. please recheck</td></tr><tr><td>invalid</td><td>certficateExpired</td><td>Certificate
            got expired. Please upgrade the application.</td></tr><tr><td>invalid</td><td>invalidMobileChannel</td><td>Invalid
            mobile channel.</td></tr><tr><td>error</td><td>e2eDisabled</td><td>E2E
            is disabled.</td></tr></table>
          schema:
            $ref: '#/definitions/ErrorResponse'
        403:
          description: (FORBIDDEN) - Unauthorized to perform the requested operation
            on resource <table><tr><td>Type</td><td>Code</td><td>Details</td><td>More
            Info</td></tr><tr><td>invalid</td><td>accessNotConfigured</td><td>The
            request operation is not configured to access this resource</td><td>Channel/Country/Business
            provided in the request is not supported currently</td></tr></table>
          schema:
            $ref: '#/definitions/ErrorResponse'
        500:
          description: (INTERNAL SERVER ERROR) - API Server Error <table><tr><td>Type</td><td>Code</td><td>Details</td></tr><tr><td>fatal</td><td>serverUnavailable</td><td>The
            request failed due to an internal error/server unavailability</td></tr></table>
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
      - ClientID (Query): []
      - ClientID: []
security:
- ClientID (Query): []
- ClientID: []
x-ibm-endpoints:
- endpointUrl: https://api.banamex.com/mx-gcgapi
  type:
  - production
  - development
...