Forgot Password (OTP)

This endpoint enables users to reset a forgotten password through a secure two-step process. In the first step, the user submits their registered username (nickname) to receive a One-Time Password (OTP) via email. In the second step, the user submits the OTP along with the desired new password to complete the reset.

Endpoint

POST /v3/forgotPasswordOTP

Authentication

Bearer token required. Obtain via:

POST https://api.banking.netevia.dev/api/auth/v2

Include in header: Authorization: Bearer {token}
Token lifetime: 10 minutes. Refresh via POST /api/auth/refresh.

When to use

Use this endpoint when a user cannot log in because they have forgotten their password. The two-step flow ensures that only the registered account owner — who has access to the email associated with the nickname — can complete the reset. Call the endpoint first with only nickName to trigger OTP delivery, then call it again with nickName, code, password, and passwordConfirm to finalize the reset.

Request Body

This endpoint accepts one of two request shapes depending on the step in the flow.

Step 1 — Request OTP (forgotPasswordRequest)

{
  "nickName": "[email protected]"
}

Step 2 — Set New Password (restorePasswordRequest)

{
  "nickName": "[email protected]",
  "code": "847291",
  "password": "NewSecureP@ssw0rd!",
  "passwordConfirm": "NewSecureP@ssw0rd!"
}

Response

200 OK

Step 1 — OTP sent response example:

{
  "restoreState": "OtpSent",
  "errors": null,
  "success": "OTP has been sent to the registered email address."
}

Step 2 — Password reset response example:

{
  "restoreState": "PasswordRestored",
  "errors": null,
  "success": "Password has been successfully reset."
}

Error response example:

{
  "restoreState": "Failed",
  "errors": [
    "Invalid OTP code.",
    "OTP has expired."
  ],
  "success": null
}

Error Codes

Common Mistakes

• Submitting code, password, and passwordConfirm in the Step 1 request — Step 1 only requires nickName; additional fields will be ignored or may cause a validation error.
• Sending password and passwordConfirm with different values — both fields must match exactly or the reset will be rejected.
• Reusing an OTP after it has already been consumed or after it has expired — request a fresh OTP by calling Step 1 again.
• Using the wrong nickName in Step 2 — the nickName must match exactly what was used in Step 1 when the OTP was issued.

Related Endpoints

• POST /api/auth/v2 — Obtain a Bearer token by authenticating with username, password, and partnerId
• POST /api/auth/refresh — Refresh an existing Bearer token before it expires

Example

Step 1 — Request OTP:

curl -X POST https://api.banking.netevia.dev/v3/forgotPasswordOTP \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "nickName": "[email protected]"
  }'

Step 2 — Set New Password:

curl -X POST https://api.banking.netevia.dev/v3/forgotPasswordOTP \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "nickName": "[email protected]",
    "code": "847291",
    "password": "NewSecureP@ssw0rd!",
    "passwordConfirm": "NewSecureP@ssw0rd!"
  }'