Confirming payments, withdrawals and transfers with an SMS code: one code per operation

The short answer: before approving a payment, a withdrawal or a transfer, send a code to the customer's phone and only carry out the transaction once the code matches. The golden rule is one code per transaction, with a short validity and a text that says what the code is for. That way, a code requested for one thing cannot approve another.

Tying the code to the transaction

1	Prepare the transaction in your system (amount, destination, account) and save it as “awaiting confirmation”. No money moves yet.

2	Send the code with POST /v1/sms/otp, a short expires_in and a text that names the transaction. Use something unique to that transaction as the Idempotency-Key, so a double click does not send two codes.

3	Save the code's id with the transaction. When checking, make sure the id belongs to this transaction and not to another one from the same customer.

4	Check it with /verify and carry out the transaction only with valid: true. Save verified_at as a record of when it was confirmed.

5	If the customer gives up, cancel the code with POST /v1/sms/otp/{id}/cancel and the transaction in your system. The SMS already sent is not refunded.

Example texts

All of them fit in one SMS. Replace [COMPANY] and [AMOUNT] with your own details; {code} and {minutes} are filled in by us.

Transaction	Text
Payment	[COMPANY]: code {code} to confirm your payment of [AMOUNT]. Do not share it.
Withdrawal	[COMPANY]: code {code} to confirm your withdrawal. Valid for {minutes} min.
Transfer	[COMPANY]: code {code} to confirm your transfer. Our staff will never ask for it.
New payee	[COMPANY]: code {code} to add a payee. If this was not you, ignore it.

If you write the texts in Portuguese, watch the accents: one letter such as ã or ç switches the message to Unicode, where a part holds 70 characters. Short texts like these still fit in one part; the full count is in how many credits an SMS uses.

Rules we suggest for money

Field	Suggestion
expires_in	5 minutes, the default. The page suggests 5 to 10 minutes.
max_attempts	3. After that, the customer asks for a new code.
length	6 digits, or more for high-value transactions (up to 8).

The text must say what the code is for. It is the best defence against someone who talks the customer into reading out a code “to collect a prize” when it is really approving a transfer. See code-sharing scams.

With a Sender ID, the code arrives under your company name. For payments this matters: customers recognise the sender and grow wary of messages that look unusual.

Want to confirm payments and transfers with an SMS code? See Verification SMS.

See Verification SMS

Categories

Categories