---
swagger: "2.0"
info:
  description: This APIs provide a unified login for each and every digital/consumer
    channel. They also provide a CCS DB storage mechanism to allow migration from
    Tandem systems
  version: 1.0.0
  title: XLG-SEC-P-ConsumerSecurity-Mobile
  x-ibm-name: xlg-sec-p-consumersecurity-Mobile
basePath: /api
schemes:
- https
produces:
- application/json
paths:
  /v2/x-global/security/login/validate:
    post:
      tags:
      - mx-retail-banking-prelogin-v2
      summary: API to perform prelogin process for credential
      description: This API is a prelogin for retail banking customer. It validates
        the customers prelogin information before creating or updating a registry
        for the user credential on CCS and proceeding with the login
      operationId: mx-retail-banking-prelogin-v2
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - name: businessCode
        in: header
        description: 3 character business code
        required: true
        type: string
        default: GCB
      - name: countryCode
        in: header
        description: 2 character ISO country code
        required: true
        type: string
        default: MX
      - name: channelId
        in: header
        description: channel ID used by the user, it is required for the first call
          in a new session.
        required: true
        type: string
      - name: Accept-Language
        in: header
        description: Language to be send to the backend systems. The supported values
          are es for spanish and en for english.
        required: true
        type: string
        default: es
      - name: Content-Type
        in: header
        description: Content-Types that are sent in the request
        required: true
        type: string
        default: application/json
      - name: 'uuid '
        in: header
        description: Random 128 bit UUID generated uniquely for every request from
          the Customer, which will represent transaction unique identifier and it
          is recommended to send.
        required: true
        type: string
      - name: sid
        in: header
        description: Session is generated and returned on the first API call as response
          header, which needs to be resent on succesive calls of same session
        required: true
        type: string
      - name: client_id
        in: header
        description: The client ID  you received during application registration in
          the developer portal
        required: true
        type: string
      - name: Authorization
        in: header
        description: Bearer token adquired from API Gateway OAUTH service.
        required: true
        type: string
      - in: body
        name: loginRequest
        description: Request body to authenticate Citibanamex retail banking customer.
        required: true
        schema:
          $ref: '#/definitions/preLoginRequest'
      responses:
        200:
          description: Authentication Successful
          headers:
            eventId:
              type: string
              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.
            eventIDExpTime:
              type: string
              description: Event ID expiration time encrypted with session key.
          schema:
            $ref: '#/definitions/preLoginResponse'
        500:
          description: <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'
  /v1/x-global/security/login:
    post:
      tags:
      - mx-retail-banking-login
      summary: API to authenticate and open session with backend systems
      description: This API opens session on PSG session, Functional Server, S015
        and Mobile Middleware session. To call this API, you need to go through Platform
        E2E Encryption APIs schema first in order to get a propper sid.
      operationId: mx-retail-banking-login
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - name: businessCode
        in: header
        description: 3 character business code
        required: true
        type: string
        default: GCB
      - name: countryCode
        in: header
        description: 2 character ISO country code
        required: true
        type: string
        default: MX
      - name: channelId
        in: header
        description: channel ID used by the user, it is required for the first call
          in a new session.
        required: true
        type: string
      - name: Accept-Language
        in: header
        description: Language to be send to the backend systems. The supported values
          are es for spanish and en for english.
        required: true
        type: string
        default: es
      - name: Content-Type
        in: header
        description: Content-Types that are sent in the request
        required: true
        type: string
        default: application/json
      - name: 'uuid '
        in: header
        description: Random 128 bit UUID generated uniquely for every request from
          the Customer, which will represent transaction unique identifier and it
          is recommended to send.
        required: true
        type: string
      - name: sid
        in: header
        description: Session is generated and returned on the first API call as response
          header, which needs to be resent on succesive calls of same session
        required: true
        type: string
      - name: client_id
        in: header
        description: The client ID  you received during application registration in
          the developer portal
        required: true
        type: string
      - name: Authorization
        in: header
        description: Bearer token adquired from API Gateway OAUTH service.
        required: true
        type: string
      - in: body
        name: loginRequest
        description: Request body to authenticate Citibanamex retail banking customer.
        required: true
        schema:
          $ref: '#/definitions/loginRequest'
      responses:
        200:
          description: Authentication Successful
          headers:
            eventId:
              type: string
              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.
            eventIDExpTime:
              type: string
              description: Event ID expiration time encrypted with session key.
            cookieValue:
              type: string
              description: Data of the backend (middleware) session.
          schema:
            $ref: '#/definitions/loginResponse'
        400:
          description: <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>cannotDecryptData</td><td>Cannot
            decrypt, please validate the encrypted value</td></tr></table>
          schema:
            $ref: '#/definitions/ErrorResponse'
        401:
          description: <table><tr><td>Type</td><td>Code</td><td>Details</td></tr><tr><td>error</td><td>unAuthorized</td><td>Authorization
            credentials are missing or invalid.</td></tr><tr><td>invalid</td><td>authenticationFailed</td><td>206-federated
            password authentication fails</td></tr><tr><td>bad_credentials</td><td>6666</td><td>Verify
            your customer number and / or password. If you have failed repeatedly
            it is likely that your service is blocked, unblock it in the main menu
            with your NetKey Banamex</td></tr><tr><td>general_error</td><td>8005</td><td>There
            was a communication error, please try again</td></tr><tr><td>bloqued_user</td><td>8006</td><td>Verify
            your customer number and / or password. If you have failed repeatedly
            it is likely that your service is blocked, unblock it in the main menu
            with your NetKey Banamex</td></tr><tr><td>usertype_error</td><td>8007</td><td>Verify
            your customer number and / or password. If you have failed repeatedly
            it is likely that your service is blocked, unblock it in the main menu
            with your NetKey Banamex</td></tr><td>duplicate_session</td><td>8008</td><td>Verify
            your customer number and / or password. If you have failed repeatedly
            it is likely that your service is blocked, unblock it in the main menu
            with your NetKey Banamex</td></tr></table>
          schema:
            $ref: '#/definitions/ErrorResponse'
        403:
          description: <table><tr><td>Type</td><td>Code</td><td>Details</td></tr><tr><td>error</td><td>accessNotConfigured</td><td>The
            request operation is not configured to access this resource.</td></tr></table>
          schema:
            $ref: '#/definitions/ErrorResponse'
        404:
          description: <table><tr><td>Type</td><td>Code</td><td>Details</td></tr><tr><td>error</td><td>userIdNotFound</td><td>Master
            userID not found</td></tr><tr><td>error</td><td>federatedProfileNotFound</td><td>751-Federated
            Profile does not exist</td></tr></table>
          schema:
            $ref: '#/definitions/ErrorResponse'
        500:
          description: <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><td>fatal</td><td>backendError</td><td>Failed
            during a call to backend service</td></tr></table>
          schema:
            $ref: '#/definitions/ErrorResponse'
  /v1/x-global/security/logout:
    delete:
      tags:
      - mx-retail-banking-logout
      summary: API to close current users session
      description: This API closes the user's session on PSG session, Functional Server,
        S015 and Mobile Middleware session. This is a post-login API, so in order
        to call it, you must have opened a session through mx-retail-banking-login
        API.
      operationId: mx-retail-banking-logout
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - name: businessCode
        in: header
        description: 3 character business code
        required: true
        type: string
        default: GCB
      - name: countryCode
        in: header
        description: 2 character ISO country code
        required: true
        type: string
        default: MX
      - name: channelId
        in: header
        description: channel ID used by the user, it is required for the first call
          in a new session.
        required: true
        type: string
      - name: 'uuid '
        in: header
        description: Random 128 bit UUID generated uniquely for every request from
          the Customer, which will represent transaction unique identifier and it
          is recommended to send.
        required: true
        type: string
      - name: sid
        in: header
        description: Session is generated and returned on the first API call as response
          header, which needs to be resent on succesive calls of same session
        required: true
        type: string
      - name: client_id
        in: header
        description: The client ID  you received during application registration in
          the developer portal
        required: true
        type: string
      - name: Authorization
        in: header
        description: Bearer token adquired from API Gateway OAUTH service.
        required: true
        type: string
      responses:
        200:
          description: Request successful.
        401:
          description: <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></table>
        403:
          description: <table><tr><td>Type</td><td>Code</td><td>Details</td></tr><tr><td>error</td><td>accessNotConfigured</td><td>The
            request operation is not configured to access this resource.</td></tr></table>
        500:
          description: <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><td>fatal</td><td>backendError</td><td>Failed
            during a call to backend service</td></tr></table>
          schema:
            $ref: '#/definitions/ErrorResponse'
  /v1/x-global/security/login/validate:
    post:
      tags:
      - mx-retail-banking-prelogin
      summary: API to perform prelogin process for credential
      description: This API is a prelogin for retail banking customer. It validates
        the customers prelogin information before creating or updating a registry
        for the user credential on CCS and proceeding with the login
      operationId: mx-retail-banking-prelogin
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - name: businessCode
        in: header
        description: 3 character business code
        required: true
        type: string
        default: GCB
      - name: countryCode
        in: header
        description: 2 character ISO country code
        required: true
        type: string
        default: MX
      - name: channelId
        in: header
        description: channel ID used by the user, it is required for the first call
          in a new session.
        required: true
        type: string
      - name: Accept-Language
        in: header
        description: Language to be send to the backend systems. The supported values
          are es for spanish and en for english.
        required: true
        type: string
        default: es
      - name: Content-Type
        in: header
        description: Content-Types that are sent in the request
        required: true
        type: string
        default: application/json
      - name: 'uuid '
        in: header
        description: Random 128 bit UUID generated uniquely for every request from
          the Customer, which will represent transaction unique identifier and it
          is recommended to send.
        required: true
        type: string
      - name: sid
        in: header
        description: Session is generated and returned on the first API call as response
          header, which needs to be resent on succesive calls of same session
        required: true
        type: string
      - name: client_id
        in: header
        description: The client ID  you received during application registration in
          the developer portal
        required: true
        type: string
      - name: Authorization
        in: header
        description: Bearer token adquired from API Gateway OAUTH service.
        required: true
        type: string
      - in: body
        name: loginRequest
        description: Request body to authenticate Citibanamex retail banking customer.
        required: true
        schema:
          $ref: '#/definitions/preLoginRequest'
      responses:
        200:
          description: Authentication Successful
          headers:
            eventId:
              type: string
              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.
            eventIDExpTime:
              type: string
              description: Event ID expiration time encrypted with session key.
          schema:
            $ref: '#/definitions/preLoginResponse'
        500:
          description: <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'
definitions:
  preLoginRequest:
    type: object
    properties:
      encryptedUserId:
        type: string
        description: Customer Number or Customer Card Number (Credit or Debit). This
          parameter is encrypted by the frontends using <a href="https://apis-ccp.citibank.nam.nsroot.net:20000/swagger-ui/#!/securityTokenService-jwt">Platform
          End-to-End encryption APIs</a>. The encoding used here must be HEX.
      vascoDeviceId:
        type: string
        example: f96dd4b2dc083008f786950fee311df1
        description: <u>MBK Specific</u>. Identifier generated by Vasco SDK.
    description: Prelogin Request.
  preLoginResponse:
    type: object
    properties:
      ccsId:
        type: string
        description: Customer CCS ID.
      encryptedLoginId:
        type: string
        description: Citibanamex Customer Number. This parameter is encrypted by the
          frontends using <a href="https://apis-ccp.citibank.nam.nsroot.net:20000/swagger-ui/#!/securityTokenService-jwt">Platform
          End-to-End encryption APIs</a>. The encoding used here must be HEX.
      maskedCustomerName:
        type: string
        example: A***** H******** R******
        description: Masked name of the customer.
      nextLoginActionCode:
        type: integer
        format: int32
        example: 1
        description: Depending of the Electronic Bank Status and the Black List Status,
          the client can be redirected to a different login.
      nextLoginActionDescription:
        type: string
        example: '0: The client have to make an onboarding'
        description: Description for next login action.
      registrationStatus:
        type: string
        example: "0"
        description: Customer registration status regarding Banca Movil regulation.
      registrationStatusDescription:
        type: string
        example: The client is not registered in Banca Movil
        description: Status description of the registration in Banca Movil.
      mobileBankingDeviceStatus:
        type: string
        example: "0"
        description: Identifier to validate if the client is using the same device
          registered in Banca Movil.
      mobileBankingDeviceStatusDescription:
        type: string
        example: The device Id does not exist
        description: Status Description of the device in Banca Movil
    description: Prelogin Response.
  loginRequest:
    type: object
    required:
    - customerCredentials
    properties:
      customerCredentials:
        $ref: '#/definitions/customerCredentials'
      vascoDeviceId:
        type: string
        example: f96dd4b2dc083008f786950fee311df1
        description: <u>MBK Specific</u>. Identifier generated by Vasco SDK.
      applicationDeviceId:
        type: string
        example: 8f786950fee311df1f96dd4b2dc08300
        description: Identifier of the device, this is neccesary when a the channel
          requires to do a login through Biologin.
      instanceId:
        type: string
        example: /v1/abc/xyz
        description: <u>MBK Specific</u>. Endpoint to generate a session in the current
          Middleware instance of Mobile arquitecture. This value is generated by the
          front end.
      mobileAML:
        $ref: '#/definitions/mobileAML'
    description: Login Request.
  customerCredentials:
    type: object
    required:
    - credentialType
    - encryptedCredentialvascoDeviceId
    - userId
    properties:
      userId:
        type: string
        example: "140946519"
        description: Customer login ID. Currently only customer number its being supported.
      userIdType:
        type: string
        description: Type of the loginId parameter used to authenticate. Default value
          is set in case this parameter does not come in the request.
        default: CUSTOMER_NUM
      encryptedCredential:
        type: string
        description: Customers credential (PIN) used for authentication. This is encrypted
          by the frontends using <a href="https://apis-ccp.citibank.nam.nsroot.net:20000/swagger-ui/#!/securityTokenService-jwt">Platform
          End-to-End encryption APIs</a>. The encoding used here must be HEX.
      credentialType:
        type: integer
        description: Type of credential which the customer has entered. Default value
          is set in case this parameter doesnt come in the request. The values can
          be the following:<br><br><table><tr><td><u>Value</u></td><td><u>Details</u></td></tr><tr><td>1</td><td>BancaNet
          numeric PIN.</td></tr><tr><td>2</td><td>BancaNet alphanumeric PIN.</td></tr><tr><td>3</td><td>BancaNet
          Biotoken.</td></tr></table>
    description: Object containing retail banking customers credentials.
  mobileAML:
    properties:
      ipAddress:
        type: string
        example: 10.102.54.64
        description: 'Internet Protocol address: a number which is given to a computer
          when it is connected to the internet (client IP address)'
      rsaVersion:
        type: string
        example: 3.4.1.1
        description: Version of the RSA that generates the data in the client (Browsers
          or Mobile Apps).
      queryTime:
        type: string
        format: date
        example: "2019-09-22T04:14:00+1:00"
        description: Time at which the request is launched, this data comes from the
          time of the smartPhone.
      rsaDeviceId:
        type: string
        example: "-1"
        description: Device identifier, if the RSA SDK in the mobile app can not recover
          it, it returns -1. It is based upon the RSA security.
      simID:
        type: string
        example: "425010770666253"
        description: Identifier of the SIM card of the device, if the RSA SDK in mobile
          app can not recover it, it returns -1.
      phoneNumber:
        type: string
        example: "-1"
        description: Phone number of the device, if the SDK can not recover it, it
          returns -1.
      rsaApplicationKey:
        type: string
        example: 10F29219081905EC2BEBFF5AD779EE48
        description: Key that identifies the RSA SDK.
      mobileCompromisedIndicator:
        type: integer
        format: int32
        example: 1
        description: 'It indicates if the smartphone is altered (Root or Jailbreak).
          The values for this parameter can be the following: 0- disabled,1- enabled.<br><br><table><tr><td><u>Value</u></td><td><u>Details</u></td></tr><tr><td>0</td><td>Disabled</td></tr><tr><td>1</td><td>Enabled</td></tr></table>'
      mobileEmulatorIndicator:
        type: integer
        format: int32
        example: 1
        description: 'It indicates if the RSA SDK is running in simulator or in a
          physical device.The values for this parameter can be the following: 0- disabled,1-
          enabled.<br><br><table><tr><td><u>Value</u></td><td><u>Details</u></td></tr><tr><td>0</td><td>Disabled</td></tr><tr><td>1</td><td>Enabled</td></tr></table>'
    description: This object contains the data needed to execute Mexico AML functionalities
      for <u>MX Mobile frontend</u>. This an optional object, it is required only
      when the frontend is a MX Mobile App and it has integrated on its layer an AML
      engine like CMAMT or something alike.
  loginResponse:
    type: object
    properties:
      customerName:
        type: string
        example: ARTURO HERNANDEZ RAMIREZ
        description: Customers full name.
      lastChannelId:
        type: string
        example: MOVIL
        description: Last channel ID in which the customer logged in. This parameter
          comes from the backend.
      lastLoginDate:
        type: string
        example: "2019-09-22T04:14:00+1:00"
        description: Last login access date.
      tokenStatus:
        type: string
        example: sdasdsa321ne2iuoi28d
        description: Customer token status. This token refers to the customer netkey
          device, which it can be a hardtoken or a softoken. The values can be the
          following:<br><br><table><tr><td><u>Value</u></td><td><u>Description</u></td></tr><tr><td>6</td><td>BASIC.
          The customer can not execute high risk transactions.</td></tr><tr><td>56</td><td>PRO.
          The customer can execute high risk transactions using its hardtoken as MFA
          method.</td></tr><tr><td>64</td><td>SOFTTOKEN_PRE_ASSIGNED. The customer
          can not execute high risk transactions but can reactivate its softoken.</td></tr><tr><td>66</td><td>SOFTTOKEN_ACTIVATED.
          The customer can execute high risk transactions using its softoken as a
          MFA method.</td></tr><tr><td>63</td><td>SOFTTOKEN_DEACTIVATED. The customer
          can not execute high risk transactions but can reactivate its sofoken.</td></tr></table><br>
      tokenStatusDescription:
        type: string
        example: BASIC
        description: Description of tokens status value of the customer.
      customerType:
        type: integer
        example: 1551
        description: This is a Mexico legacy parameter. The first two digits of the
          value represents the customers service type (i.e. 15 stands for <i>Electronic
          Banking Service</i>), and the last two digits represents the customers type
          of person. To sumarize, the values can be the following:<br><br><table><tr><td><u>Value</u></td><td><u>Description</u></td></tr><tr><td>1506</td><td>Moral
          person.</td></tr><tr><td>1521</td><td>Physical person with enterprise activity.</td></tr><tr><td>1551</td><td>Physical
          person.</td></tr></table><br>
      customerTypeDescription:
        type: string
        example: Individual
        description: Description of customer types value.
      credentialStatus:
        type: string
        example: NEW
        description: This parameter represents the status of the credential which
          was used to authenticate. Depending on the value, the frontend application
          needs to enforce the action to follow. The values can be the following:<br><br><table><tr><td><u>Value</u></td><td><u>Description</u></td></tr><tr><td>NONE</td><td>The
          current Password is ok.</td></tr><tr><td>NEW</td><td>Login with Temporal
          PIN. PIN and Password do not exist. Both have to be created.</td></tr><tr><td>RPIN</td><td>Login
          with Temporal PIN. PIN and Password is expired. Both have to be created.</td></tr><tr><td>ACPWD</td><td>Login
          with PIN. Password is expired. It has to be created.</td></tr><tr><td>CHPWD</td><td>Login
          with Password. Password is expired after an unlock. It has to be created.</td></tr></table><br>
      credentialStatusDescription:
        type: string
        example: ""
        description: Description if credentialStatus value.
      termsAndConditionsAcceptedFlag:
        type: boolean
        example: true
        description: Flag which indicates if the customer has already accepted Citibanamex
          electronic <i>Terms & Conditions</i>.
      registrationStatus:
        type: string
        example: "0"
        description: Customer registration status regarding Banca Movil regulation.
      registrationStatusDescription:
        type: string
        example: The client is not registered in Banca Movil
        description: Status description of the registration in Banca Movil.
      mobileBankingDeviceStatus:
        type: string
        example: "0"
        description: Identifier to validate if the client is using the same device
          registered in Banca Movil.
      mobileBankingDeviceStatusDescription:
        type: string
        example: The device Id does not exist
        description: Status Description of the device in Banca Movil
    description: Response parameters of retail banking login for Mexico customers.
  ErrorResponse:
    required:
    - code
    - details
    - type
    properties:
      type:
        type: string
        description: Invalid - Request did not confirm to the specification and was
          unprocessed and rejected. Please fix the value and try again
        enum:
        - error
        - warn
        - invalid
        - fatal
      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
x-ibm-configuration:
  enforced: true
  testable: true
  phase: realized
securityDefinitions:
  OAuth2 Application Flow:
    type: oauth2
    description: ""
    flow: application
    scopes:
      /api/v1: ""
    tokenUrl: https://api.banamex.com/mx-gcgapi/api/v1/oauth/token
  Client ID:
    type: apiKey
    description: ""
    in: header
    name: X-IBM-Client-Id
security:
- Client ID: []
x-ibm-endpoints:
- endpointUrl: https://api.banamex.com/mx-gcgapi
  type:
  - production
  - development
...