---
swagger: "2.0"
info:
description: Generates and validate OTP through CitiMFA
version: "1.0"
title: XLG-SEC-P-BanamexOtpAuthentication
x-ibm-name: api-77b82
basePath: /api
tags:
- name: OTP
description: OTP Operations
schemes:
- https
paths:
/v1/x-global/security/tele-marketing/otp/generate:
post:
tags:
- OTP Telemarketing
summary: Generate and send Telemarketing OTP to Customer's phone number via
SMS to complete or authorize a transaction.
description: This API allows to generate the one time password and delivers
to the customer in order to do a confirmation in Telemarketing flow. One time
password is 11 digits of length that are delivered to the customer, 3 of those
are returned in the response to client application.
consumes:
- application/json
produces:
- application/json
parameters:
- name: uuid
in: header
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.
required: true
type: string
default: a7d1e304-83a9-4413-af97-62615e57eae66807840
- name: Content-Type
in: header
description: Content-Types that are acceptable for the response. Currently
we support application/json
required: true
type: string
default: application/json
- name: Accept-Language
in: header
description: HTTP Accept-Language header
required: true
type: string
default: en-US
- 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
required: true
type: string
default: IVR
- name: client_id
in: header
description: The client ID you received during application registration in
the developer portal
required: true
type: string
default: iX4xW5lG0gD6cX3uI5qN3pF6yK5nY2kB0eY5tB3xQ4rD4fD2xO
- name: Authorization
in: header
description: Authorization code generated in previous OAuth invocation
required: true
type: string
default: iX4xW5lG0gD6cX3uI5qN3pF6yK5nY2kB0eY5tB3xQ4rD4fD2xO
- in: body
name: TelemarketingOTPRequest
description: 'OTP request with required details to generate and send OTP to
customer, custom messsage special characters allowed: ? ! # $ % & * + -
/ ^ _ { } @ [ ] ~ ( ), characters that needs to send in unicode format:
< > ¿ ¡ ñ á é í ó ú ü, minimum message lenght: 1 character, maximum length
per delivered message is 140 characters'
required: true
schema:
$ref: '#/definitions/TelemarketingOTPRequest'
responses:
200:
description: OTP sent successfully
schema:
$ref: '#/definitions/TelemarketingOTPResponse'
400:
description: (BAD REQUEST) - Request was not processed
Type | Code | Details |
invalid | invalidRequest | Missing
or invalid Parameters |
error | smsDeliveryFailed | SMS
delivery failed |
schema:
$ref: '#/definitions/ErrorResponse'
401:
description: (UNAUTHORIZED) - Request was not processed Type | Code | Details |
error | unAuthorized | Unauthorized
access to this resource |
schema:
$ref: '#/definitions/ErrorResponse'
403:
description: (FORBIDDEN) - Unauthorized to perform the requested operation
on resource Type | Code | Details | More
Info |
invalid | accessNotConfigured | The
request operation is not configured to access this resource | Channel/Country/Business
provided in the request is not supported currently |
schema:
$ref: '#/definitions/ErrorResponse'
500:
description: (INTERNAL SERVER ERROR) - API Server Error Type | Code | Details |
error | backendError | Failed
during a call to backend service |
|
fatal | serverUnavailable | The
request failed due to an internal error/server unavailability |
schema:
$ref: '#/definitions/ErrorResponse'
/v1/x-global/security/tele-marketing/otp/validate:
post:
tags:
- OTP Telemarketing
summary: This API validates telemarketing OTP token submitted by Customer.
description: Validate 11 digit One Time Password, validating 3 digits stored
in session and 8 digits remaining against CitiMFA validation service. A successful
validation of the OTP means the customers have completed or authorize a transaction
in behalf of them.
consumes:
- application/json
produces:
- application/json
parameters:
- name: uuid
in: header
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.
required: true
type: string
default: a7d1e304-83a9-4413-af97-62615e57eae66807840
- 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: Content-Type
in: header
description: Content-Types that are acceptable for the response. Currently
we support application/json
required: true
type: string
default: application/json
- name: Accept-Language
in: header
description: HTTP Accept-Language header
required: true
type: string
default: en-US
- 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
required: true
type: string
default: IVR
- name: client_id
in: header
description: The client ID you received during application registration in
the developer portal
required: true
type: string
default: iX4xW5lG0gD6cX3uI5qN3pF6yK5nY2kB0eY5tB3xQ4rD4fD2xO
- name: Authorization
in: header
description: Authorization code generated in previous OAuth invocation
required: true
type: string
default: iX4xW5lG0gD6cX3uI5qN3pF6yK5nY2kB0eY5tB3xQ4rD4fD2xO
- in: body
name: ValidateOTPRequest
description: Otp request with the required details to validate otp token.
required: true
schema:
$ref: '#/definitions/ValidateTelemarketingOTPRequest'
responses:
200:
description: OTP Successfully validated
400:
description: (BAD REQUEST) - Request was not processed Type | Code | Details |
invalid | invalidRequest | Missing
or invalid Parameters |
error | OTP Token Invalid | OTP
Token Invalid |
error | OTP Token Expired | OTP
Token Expired |
schema:
$ref: '#/definitions/ErrorResponse'
401:
description: (UNAUTHORIZED) - Request was not processed Type | Code | Details |
error | unAuthorized | Unauthorized
access to this resource |
schema:
$ref: '#/definitions/ErrorResponse'
403:
description: (FORBIDDEN) - Unauthorized to perform the requested operation
on resource Type | Code | Details | More
Info |
invalid | accessNotConfigured | The
request operation is not configured to access this resource | Channel/Country/Business
provided in the request is not supported currently |
schema:
$ref: '#/definitions/ErrorResponse'
500:
description: (INTERNAL SERVER ERROR) - API Server Error Type | Code | Details |
error | backendError | Failed
during a call to backend service |
fatal | serverUnavailable | The
request failed due to an internal error/server unavailability |
schema:
$ref: '#/definitions/ErrorResponse'
definitions:
TelemarketingOTPRequest:
type: object
required:
- customerId
- messagePrefix
- phoneNumber
properties:
customerId:
type: string
example: test_1234
description: Login User ID
phoneNumber:
type: string
example: "1111214678"
description: The phone number of the user for which OTP needs to be delivered
messagePrefix:
type: string
example: Citi Identification Code Service
description: The string representing Prefix message
messageSuffix:
type: string
example: Reply HELP for help STOP to cancel
description: The string representing Postfix message
ValidateTelemarketingOTPRequest:
type: object
required:
- customerId
- oneTimePasswordToken
properties:
customerId:
type: string
example: test_1234
description: Login User ID
oneTimePasswordToken:
type: string
example: A1B2C3D4E5F
description: Alphanumeric One time password.
minLength: 11
maxLength: 11
TelemarketingOTPResponse:
type: object
properties:
oneTimePasswordToken:
type: string
example: ABC
description: Prefix OTP is part of delivered customer token which needs to
be kept at app side along with SID for validation, remaining digits are
generated and send by CitiMFA.
maxLength: 3
ErrorResponse:
required:
- code
- details
- location
- moreInfo
- timestamp
- 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
timestamp:
type: string
description: Timestamp 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:
- OAuth2 Application Flow:
- /api/v1
Client ID: []
x-ibm-endpoints:
- endpointUrl: https://api.banamex.com/mx-gcgapi
type:
- production
- development
...