Paths
/v2/x-global/security/login/validate
API to perform prelogin process for credential
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
3 character business code
{
"default": "GCB"
}2 character ISO country code
{
"default": "MX"
}channel ID used by the user, it is required for the first call in a new session.
Language to be send to the backend systems. The supported values are es for spanish and en for english.
{
"default": "es"
}Content-Types that are sent in the request
{
"default": "application\/json"
}Random 128 bit UUID generated uniquely for every request from the Customer, which will represent transaction unique identifier and it is recommended to send.
Session is generated and returned on the first API call as response header, which needs to be resent on succesive calls of same session
The client ID you received during application registration in the developer portal
Bearer token adquired from API Gateway OAUTH service.
Request body to authenticate Citibanamex retail banking customer.
Authentication Successful
| Type | Code | Details |
| fatal | serverUnavailable | The request failed due to an internal error/server unavailability |
/v1/x-global/security/login
API to authenticate and open session with backend systems
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.
3 character business code
{
"default": "GCB"
}2 character ISO country code
{
"default": "MX"
}channel ID used by the user, it is required for the first call in a new session.
Language to be send to the backend systems. The supported values are es for spanish and en for english.
{
"default": "es"
}Content-Types that are sent in the request
{
"default": "application\/json"
}Random 128 bit UUID generated uniquely for every request from the Customer, which will represent transaction unique identifier and it is recommended to send.
Session is generated and returned on the first API call as response header, which needs to be resent on succesive calls of same session
The client ID you received during application registration in the developer portal
Bearer token adquired from API Gateway OAUTH service.
Request body to authenticate Citibanamex retail banking customer.
Authentication Successful
| Type | Code | Details |
| invalid | invalidRequest | Missing or invalid Parameters |
| error | cannotDecryptData | Cannot decrypt, please validate the encrypted value |
| Type | Code | Details |
| error | unAuthorized | Authorization credentials are missing or invalid. |
| invalid | authenticationFailed | 206-federated password authentication fails |
| bad_credentials | 6666 | 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 |
| general_error | 8005 | There was a communication error, please try again |
| bloqued_user | 8006 | 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 |
| usertype_error | 8007 | 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 | duplicate_session | 8008 | 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 |
| Type | Code | Details |
| error | accessNotConfigured | The request operation is not configured to access this resource. |
| Type | Code | Details |
| error | userIdNotFound | Master userID not found |
| error | federatedProfileNotFound | 751-Federated Profile does not exist |
| Type | Code | Details |
| fatal | serverUnavailable | The request failed due to an internal error/server unavailability | fatal | backendError | Failed during a call to backend service |
/v1/x-global/security/logout
API to close current users session
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.
3 character business code
{
"default": "GCB"
}2 character ISO country code
{
"default": "MX"
}channel ID used by the user, it is required for the first call in a new session.
Random 128 bit UUID generated uniquely for every request from the Customer, which will represent transaction unique identifier and it is recommended to send.
Session is generated and returned on the first API call as response header, which needs to be resent on succesive calls of same session
The client ID you received during application registration in the developer portal
Bearer token adquired from API Gateway OAUTH service.
Request successful.
| Type | Code | Details |
| invalid | invalidRequest | Missing or invalid parameters. |
| Type | Code | Details |
| error | accessNotConfigured | The request operation is not configured to access this resource. |
| Type | Code | Details |
| fatal | serverUnavailable | The request failed due to an internal error/server unavailability | fatal | backendError | Failed during a call to backend service |
/v1/x-global/security/login/validate
API to perform prelogin process for credential
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
3 character business code
{
"default": "GCB"
}2 character ISO country code
{
"default": "MX"
}channel ID used by the user, it is required for the first call in a new session.
Language to be send to the backend systems. The supported values are es for spanish and en for english.
{
"default": "es"
}Content-Types that are sent in the request
{
"default": "application\/json"
}Random 128 bit UUID generated uniquely for every request from the Customer, which will represent transaction unique identifier and it is recommended to send.
Session is generated and returned on the first API call as response header, which needs to be resent on succesive calls of same session
The client ID you received during application registration in the developer portal
Bearer token adquired from API Gateway OAUTH service.
Request body to authenticate Citibanamex retail banking customer.
Authentication Successful
| Type | Code | Details |
| fatal | serverUnavailable | The request failed due to an internal error/server unavailability |
Definitions
Prelogin Request.
{
"type": "object",
"properties": {
"encryptedUserId": {
"type": "string",
"description": "Customer Number or Customer Card Number (Credit or Debit). This parameter is encrypted by the frontends using Platform End-to-End encryption APIs. The encoding used here must be HEX."
},
"vascoDeviceId": {
"type": "string",
"example": "f96dd4b2dc083008f786950fee311df1",
"description": "MBK Specific. Identifier generated by Vasco SDK."
}
}
}
Prelogin Response.
{
"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 Platform End-to-End encryption APIs. 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"
}
}
}
Login Request.
{
"type": "object",
"required": [
"customerCredentials"
],
"properties": {
"customerCredentials": {
"$ref": "#/definitions/customerCredentials"
},
"vascoDeviceId": {
"type": "string",
"example": "f96dd4b2dc083008f786950fee311df1",
"description": "MBK Specific. 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": "MBK Specific. 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"
}
}
}
Object containing retail banking customers credentials.
{
"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 Platform End-to-End encryption APIs. 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:
Value Details 1 BancaNet numeric PIN. 2 BancaNet alphanumeric PIN. 3 BancaNet Biotoken.
"
}
}
}
This object contains the data needed to execute Mexico AML functionalities for MX Mobile frontend. 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.
{
"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.
Value Details 0 Disabled 1 Enabled
"
},
"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.
Value Details 0 Disabled 1 Enabled
"
}
}
}
Response parameters of retail banking login for Mexico customers.
{
"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:
Value Description 6 BASIC. The customer can not execute high risk transactions. 56 PRO. The customer can execute high risk transactions using its hardtoken as MFA method. 64 SOFTTOKEN_PRE_ASSIGNED. The customer can not execute high risk transactions but can reactivate its softoken. 66 SOFTTOKEN_ACTIVATED. The customer can execute high risk transactions using its softoken as a MFA method. 63 SOFTTOKEN_DEACTIVATED. The customer can not execute high risk transactions but can reactivate its sofoken.
"
},
"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 Electronic Banking Service), and the last two digits represents the customers type of person. To sumarize, the values can be the following:
Value Description 1506 Moral person. 1521 Physical person with enterprise activity. 1551 Physical person.
"
},
"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:
Value Description NONE The current Password is ok. NEW Login with Temporal PIN. PIN and Password do not exist. Both have to be created. RPIN Login with Temporal PIN. PIN and Password is expired. Both have to be created. ACPWD Login with PIN. Password is expired. It has to be created. CHPWD Login with Password. Password is expired after an unlock. It has to be created.
"
},
"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 Terms & Conditions."
},
"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"
}
}
}
{
"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"
}
}
}