--- 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
TypeCodeDetails
invalidinvalidRequestMissing or invalid Parameters
errorsmsDeliveryFailedSMS delivery failed
schema: $ref: '#/definitions/ErrorResponse' 401: description: (UNAUTHORIZED) - Request was not processed
TypeCodeDetails
errorunAuthorizedUnauthorized access to this resource
schema: $ref: '#/definitions/ErrorResponse' 403: description: (FORBIDDEN) - Unauthorized to perform the requested operation on resource
TypeCodeDetailsMore Info
invalidaccessNotConfiguredThe request operation is not configured to access this resourceChannel/Country/Business provided in the request is not supported currently
schema: $ref: '#/definitions/ErrorResponse' 500: description: (INTERNAL SERVER ERROR) - API Server Error
TypeCodeDetails
errorbackendErrorFailed during a call to backend service
fatalserverUnavailableThe 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
TypeCodeDetails
invalidinvalidRequestMissing or invalid Parameters
errorOTP Token InvalidOTP Token Invalid
errorOTP Token ExpiredOTP Token Expired
schema: $ref: '#/definitions/ErrorResponse' 401: description: (UNAUTHORIZED) - Request was not processed
TypeCodeDetails
errorunAuthorizedUnauthorized access to this resource
schema: $ref: '#/definitions/ErrorResponse' 403: description: (FORBIDDEN) - Unauthorized to perform the requested operation on resource
TypeCodeDetailsMore Info
invalidaccessNotConfiguredThe request operation is not configured to access this resourceChannel/Country/Business provided in the request is not supported currently
schema: $ref: '#/definitions/ErrorResponse' 500: description: (INTERNAL SERVER ERROR) - API Server Error
TypeCodeDetails
errorbackendErrorFailed during a call to backend service
fatalserverUnavailableThe 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 ...