cryptoinfraYour user is at an online checkout. They type in their crypto card number, press Pay, and a new box appears: "Enter the code to confirm this payment." That box is 3-D Secure. If your app is ready for it, the user finishes the payment in a few seconds. If it is not, the user is stuck, the payment fails, and they blame your card.
This guide explains what 3-D Secure is, why online shops use it, how the code reaches a crypto cardholder, and how to build the flow into your app so that nobody gets stuck at checkout.
#What 3-D Secure is
3-D Secure is an extra check that some online payments go through. Before the payment is approved, the shop asks the card program a simple question: "Is the real cardholder making this payment?"
Sometimes the program answers on its own, in the background, and the user sees nothing. Other times it asks for proof. That is the challenge: the shop shows a box, and the cardholder types a one-time code to confirm the payment.
The idea is simple. A thief may have a copy of the card number, the expiry date and the security code. They should not have the one-time code, because it only goes to the real cardholder.
#Why it matters for crypto cards
A crypto card is a normal card once a payment leaves it. The shop does not know the money came from stablecoins. It follows the same rules as for any other card, and many shops ask for 3-D Secure on larger orders, on first purchases, or when something looks unusual.
That means 3-D Secure is not a rare edge case. Sooner or later every active cardholder meets it. For a business that offers crypto cards, a smooth challenge flow is part of the product, just like loading the card or showing its balance.
#Where the code comes from
With a bank card, the code usually arrives by text message from the bank. A crypto card program works differently, and this is the part many teams get wrong.
On our platform, the code does not go to the user by text message or email. It comes to you, the business, through the API. You then show it to your user inside your own app. Here is the flow step by step:
- The cardholder starts a payment at an online shop.
- The shop asks for a 3-D Secure challenge.
- Our platform receives the one-time code for that card and holds it for a short time.
- Your server receives a signed
card.wallet_otpwebhook. It tells you a code is waiting. It does not contain the code. - Your app calls
GET /v1/cards/{id}/otpwith the user's id and gets the code back. - Your app shows the code to the user, who types it into the shop's box.
- The payment completes.
The same flow is used when a user adds the card to a phone wallet. The response has a kind field, so you can tell a checkout code from a phone-wallet code and show the right message.
#Why the code is built this way
Every rule in this flow exists to keep the code secret.
| Rule | Why it helps |
|---|---|
| The webhook carries no code | Webhooks are stored and retried. A code inside one could leak later. |
| The code is fetched on demand | It only moves when your app asks for it, over an authenticated call. |
| Each code can be read once | If a response leaks, nobody can fetch the same code again. |
| The code expires quickly | A stolen code is useless after a short time. |
| The code is bound to the card and its owner | Passing the user id proves the right person is asking. |
When no code is waiting, or it expired, or the card belongs to someone else, the endpoint gives the same simple "no code available" answer. It never says which reason applied. That keeps the endpoint from being used to guess card details.
#How to show the code in your app
The best flows feel like part of the checkout, not a puzzle. A few practical tips:
- Push, then pull. When the
card.wallet_otpwebhook arrives, send your user a push notification or show a banner: "A payment needs your confirmation." Fetch the code only when they open the screen. - Offer a manual button. Some users open your app before the webhook lands. A "Get my payment code" button on the card screen lets them fetch it themselves. The card details response also tells you whether a code is waiting.
- Show what it is for. Use
kindto say "Confirm your online payment" or "Add your card to your phone wallet." Users trust a code more when they know why they see it. - Show it once. The code is single-read, so display it clearly, with a copy button, and keep it on screen while the user is in the flow.
- Never store it. Do not write the code to your database, logs, analytics or error reports. Treat it like a password.
#Common mistakes
Telling users to wait for a text message. No text message comes. If your help pages say so, users wait for a code that never arrives. Update your copy to point them to your app.
Fetching the code in a background job. The code is single-read. If a job fetches it and throws it away, the user has nothing left to see. Fetch it only when the user is looking.
Logging the full API response. A debug log line with the response body puts a live code on disk. Strip the code field before anything is logged.
Skipping webhook verification. Always check the x-cryptoinfra-signature header over the raw body before you trust an event. The webhooks guide shows how to check it.
Forgetting the fee schedule. A 3-D Secure check can carry a small card fee. It is taken inside the transaction amount, not added on top. The live schedule is on the pricing page, so show users real numbers from there instead of guessing.
#A quick checklist before launch
- [ ] Your webhook endpoint accepts and verifies
card.wallet_otp. - [ ] Your app can call
GET /v1/cards/{id}/otpwith the user's id. - [ ] The screen explains whether the code is for a payment or a phone wallet.
- [ ] The code is never logged, cached or saved.
- [ ] Your help pages say the code appears in your app, not by text message.
- [ ] Support staff know how to freeze a card if a user reports a payment they did not make.
The full card API, with every field and event, is in the cards guide. If you are new to how the money flows behind a card, start with how crypto debit cards work.
#Ready to launch cards your users can trust?
3-D Secure is a small screen, but it decides whether a payment goes through. Build it once, build it right, and your cardholders will never think about it again. Sign up for a merchant account and start building your card program today.