OTP Endpoints

API reference for OTP initiation and verification endpoints.

Initiate OTP

Initiates OTP verification with a Fayda Card Number (FCN). This endpoint sends an OTP to the mobile number associated with the provided FCN.

POST/api/fayda/otp/initiate

Request Headers

Header	Required	Description
Authorization / X-API-Key	Yes	Your API key. See Authentication.
Content-Type	Yes	Must be `application/json`.

Request Body

{
  "fcn": "1234567890123456"
}

Parameter	Type	Required	Description
fcn	String	Yes	The 16-digit Fayda Card Number of the user.

Successful Response (200 OK)

json

{
  "success": true,
  "transactionId": "cd8e1472-57f4-49a2-ace9-6ec24ad3ac52",
  "maskedMobile": "09xxxxxx24",
  "status": "SUCCESS",
  "message": "OTP sent",
  "statusCode": 200
}

Field	Type	Description
success	Boolean	Indicates if the OTP was successfully sent.
transactionId	String	A unique ID for this transaction. Required for the verify step.
maskedMobile	String	The masked mobile number to which the OTP was sent.

Error Responses

Common errors for this endpoint include:

INVALID_FCN - The FCN format is incorrect.
FCN_NOT_FOUND - The FCN does not exist in the Fayda system.
SMS_DELIVERY_FAILED - Could not send OTP to the user's phone.

See the full Error Reference for more details.

Verify OTP

Verifies the OTP entered by the user. If successful, it returns the user's verified identity data.

POST/api/fayda/otp/verify

Request Body

json

{
  "transactionId": "cd8e1472-57f4-49a2-ace9-6ec24ad3ac52",
  "otp": "123456",
  "fcn": "1234567890123456"
}

Parameter	Type	Required	Description
transactionId	String	Yes	The ID from the initiate OTP response.
otp	String	Yes	The 6-digit OTP entered by the user.
fcn	String	Yes	The user's 16-digit FCN.

Successful Response (200 OK)

json

{
  "success": true,
  "transactionId": "cd8e1472-57f4-49a2-ace9-6ec24ad3ac52",
  "user": {
    "uin": "8957253029940",
    "fullName": [
      { "language": "eng", "value": "John Doe" },
      { "language": "amh", "value": "ጆን ዶ" }
    ],
    "dateOfBirth": "1990/01/01",
    "gender": [
      { "language": "eng", "value": "Male" },
      { "language": "amh", "value": "ወንድ" }
    ],
    "phone": "0912345678",
    "region": "Addis Ababa",
    // ... other fields
  },
  "photo": "base64-encoded-image-data",
  "qrCode": "base64-encoded-qr-data"
}

User Data Structure

The structure of the user object follows the Fayda identity schema. Some fields may be multilingual.

Error Responses

Common errors for this endpoint include:

INVALID_OTP - The OTP is incorrect.
OTP_EXPIRED - The OTP has expired.
MAX_ATTEMPTS_REACHED - Too many incorrect OTP attempts.
TRANSACTION_NOT_FOUND - The transaction ID is invalid or has expired.