---
swagger: "2.0"
info:
description: This APIs provide the functionality for giving an extra authentication
to the customers, using a challenge validation, this services are available only
after a login process done and a netKey or softToken assigned
version: 1.0.0
title: XLG-SEC-P-TransactionAuthenticationServices
x-ibm-name: xlg-sec-p-transactionauthenticationservices
basePath: /api
schemes:
- https
produces:
- application/json
paths:
/v1/x-global/security/challenge/retrieve:
get:
tags:
- get-challenge
summary: API called when the user requires a challenge
operationId: mx-retail-banking-credentialsvalidation
consumes:
- application/json
produces:
- application/json
parameters:
- 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
- name: Accept
in: header
required: true
type: string
description: Content-Types that are acceptable for the response
- 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: 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: false
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: countryCode
in: header
description: 2 character ISO country code
required: true
type: string
default: MX
- name: businessCode
in: header
description: 3 character business code
required: true
type: string
default: GCB
- 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: 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
responses:
200:
description: Authentication Successful
schema:
$ref: '#/definitions/GetChallengeResponse'
400:
description: | Type | Code | Details |
| invalid | invalidRequest | Missing
or invalid Parameters |
schema:
$ref: '#/definitions/ErrorResponse'
401:
description: | Type | Code | Details |
| error | unAuthorized | Authorization
credentials are missing or invalid. |
schema:
$ref: '#/definitions/ErrorResponse'
403:
description: | Type | Code | Details |
| error | accessNotConfigured | The
request operation is not configured to access this resource. |
schema:
$ref: '#/definitions/ErrorResponse'
404:
description: | Type | Code | Details |
| invalid | Application
not found | The element searching was not found |
schema:
$ref: '#/definitions/ErrorResponse'
422:
description: | Type | Code | Details |
| error | businessValidationFailed | Business
validation error occured on one or more parameter |
schema:
$ref: '#/definitions/ErrorResponse'
500:
description: | Type | Code | Details |
| fatal | serverUnavailable | The
request failed due to an internal error/server unavailability |
schema:
$ref: '#/definitions/ErrorResponse'
/v1/x-global/security/challenge/validate:
post:
tags:
- validate-challenge
summary: API to validate a challenge
description: This API is called when the channel needs to validate a challenge.
operationId: mx-challenge-validation
consumes:
- application/json
produces:
- application/json
parameters:
- 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
- name: Accept
in: header
required: true
type: string
description: Content-Types that are acceptable for the response
- 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: 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: false
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: countryCode
in: header
description: 2 character ISO country code
required: true
type: string
default: MX
- name: businessCode
in: header
description: 3 character business code
required: true
type: string
default: GCB
- 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: 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
- in: body
name: ValidateChallengeRequest
description: Request body to authenticate Citibanamex retail banking customer.
required: true
schema:
$ref: '#/definitions/ValidateChallengeRequest'
responses:
200:
schema:
$ref: '#/definitions/ValidateChallengeResponse'
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.
400:
description: | Type | Code | Details |
| invalid | invalidRequest | Missing
or invalid Parameters |
| error | cannotDecryptData | Cannot
decrypt, please validate the encrypted value |
schema:
$ref: '#/definitions/ErrorResponse'
401:
description: | Type | Code | Details |
| error | unAuthorized | Authorization
credentials are missing or invalid. |
| invalid | authenticationFailed | 206-federated
password authentication fails |
schema:
$ref: '#/definitions/ErrorResponse'
403:
description: | Type | Code | Details |
| error | accessNotConfigured | The
request operation is not configured to access this resource. |
schema:
$ref: '#/definitions/ErrorResponse'
404:
description: | Type | Code | Details |
| invalid | Application
not found | The element searching was not found |
schema:
$ref: '#/definitions/ErrorResponse'
422:
description: | Type | Code | Details |
| error | businessValidationFailed | Business
validation error occured on one or more parameter |
schema:
$ref: '#/definitions/ErrorResponse'
500:
description: | Type | Code | Details |
| fatal | serverUnavailable | The
request failed due to an internal error/server unavailability |
fatal | backendError | Failed
during a call to backend service |
schema:
$ref: '#/definitions/ErrorResponse'
definitions:
GetChallengeResponse:
type: object
properties:
challengeQuestion:
type: string
example: "87295410"
description: Challenge received success given by the SPA service.
required:
- challengeQuestion
description: Success body response after requesting a Challenge
ValidateChallengeRequest:
type: object
properties:
challengeQuestion:
type: string
example: "87295410"
description: Challenge previously received (must be same as the given from
get challenge service), composed by 8 digit numbers.
oneTimePasswordToken:
type: string
example: "17364892"
description: Challenge token generated by the hardToken or softToken assigned
to the client.
required:
- challengeQuestion
- oneTimePasswordToken
description: Request parameters are require for getting a correct and successful
authentication of the client by a challengen validation
ValidateChallengeResponse:
type: object
properties:
responseMessage:
type: string
example: 'SEG: BIENVENIDO A LA RED BANAMEX.'
description: Message produced after a success Challenge generation
description: Success body response after requesting a Challenge
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
ClientID:
type: apiKey
description: ""
in: header
name: X-IBM-Client-Id
security:
- OAuth2 Application Flow:
- /api/v1
ClientID: []
x-ibm-endpoints:
- endpointUrl: https://api.banamex.com/mx-gcgapi
type:
- production
- development
...