Angola
Brasil
Kenya
Moçambique
Nigeria
Portugal
South Africa
United Kingdom
United States
International
The short answer: three fields decide how each code behaves: length (4 to 8 digits, 6 by default), expires_in (1 to 60 minutes, 5 by default) and max_attempts (1 to 10 wrong attempts, 5 by default). Send none of them and the defaults apply, which suit most cases. Change them when the use calls for it.
The three fields
| Field | What it controls | Values | Default |
| length | How many digits the code has | 4 to 8 | 6 |
| expires_in | The minutes the code stays valid | 1 to 60 | 5 |
| max_attempts | Wrong attempts before the code fails | 1 to 10 | 5 |
Length: the guesser's arithmetic
With 6 digits there are a million possible codes. With 5 attempts, someone typing numbers at random gets it right, on average, 5 times in every million codes. With 4 digits there are only ten thousand codes, and the same 5 attempts give 5 in every ten thousand: a hundred times easier. That is why 6 is the default: easy to type, hard to guess. Use 8 when the transaction is worth a lot; use 4 only when the risk is low and speed matters most.
Validity and attempts for each case
| Case | length | expires_in | max_attempts |
| Confirming the number at sign-up | 6 | 5 to 10 | 3 to 5 |
| Second login step | 6 | 5 | 3 to 5 |
| Payment or transfer | 6 to 8 | 5 | 3 |
| Doorstep delivery | 6 | up to 60, close to arrival | 3 to 5 |
These suggestions follow the good practice on the Verification SMS page: 6 digits, 5 to 10 minutes validity and 3 to 5 attempts. Validity of hours or days does not exist in this API, and that is a good thing: a code is for now, not for tomorrow.
| Attempts do not come back with a resend. POST /v1/sms/otp/{id}/resend sends a new code and the validity starts again, but wrong attempts already used stay used. With max_attempts at 3 and two failed, the resent code has a single attempt. To start from scratch, request a new code with POST /v1/sms/otp. |
| Put the validity in the text with {minutes}, which we replace with the expires_in value: the customer knows to be quick. See how to write the verification SMS. |
|
Want to choose the length, validity and attempts of each code? See Verification SMS. See Verification SMS |
RECOMMENDED PRODUCT Web hosting with cPanel Domain and SSL included, daily backups and the panel you already know. from ₦9.900,00/mo (3-year plan, with coupon) See plans |
