{"templateId":"markdown","versions":[{"version":"v0-beta","label":"Beta (v0)","link":"/products/native-api/docs/how-it-works/otp-verification","default":true,"active":true,"folderId":"e4cb5a06"}],"sharedDataIds":{"sidebar":"sidebar-products/native-api/@v0-beta/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"OTP Email Verification","description":"Official Banxa API documentation – on-ramp and off-ramp transfers with identity verification and compliance.","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"otp-email-verification","__idx":0},"children":["OTP Email Verification"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Banxa Native supports headless OTP: your app collects the customer's email address, triggers the verification flow server-side, and handles the code entry UI natively. No Banxa-hosted screens, no redirects."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If your app has a login mechanism, the OTP requirement can be disabled entirely — contact your Banxa integration manager. If your app does not have a login mechanism, headless OTP is required before you can process a transaction."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"when-to-use-otp-verification","__idx":1},"children":["When to use OTP verification"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["OTP is used to verify a customer's email address as part of identity establishment. It is relevant when:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Your app does not have its own login or authentication mechanism and you need Banxa to verify the customer's email access"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A customer's identity was created without an email address (sparse identity) and you want to collect and verify email via OTP — if you only need to add an email without verification, use the identity patch endpoint instead"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If OTP is not enabled on your account, the endpoints return ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["403 OtpFeatureNotEnabled"]},"."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"endpoints","__idx":2},"children":["Endpoints"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Both endpoints use HMAC authentication. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/native-api/docs/getting-started/authentication"},"children":["Authentication"]}," for signing details."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Action"},"children":["Action"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Endpoint"},"children":["Endpoint"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Send OTP code"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /eapi/v1/verifications/otp"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Verify OTP code"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /eapi/v1/verifications/otp/verify"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"the-verification-flow","__idx":3},"children":["The verification flow"]},{"$$mdtype":"Tag","name":"Diagram","attributes":{"data-language":"mermaid","diagramType":"mermaid","diagramSource":"sequenceDiagram\n participant App\n participant YourBackend as Your backend\n participant Banxa\n\n App->>YourBackend: Customer submits email\n YourBackend->>Banxa: POST /eapi/v1/verifications/otp\n Banxa-->>YourBackend: 200 { message: \"OTP sent successfully\" }\n Banxa->>App: Email with OTP code (via customer's inbox)\n App->>App: Customer enters OTP code\n App->>YourBackend: Code submitted\n YourBackend->>Banxa: POST /eapi/v1/verifications/otp/verify\n Banxa-->>YourBackend: 200 { message: \"Success\" }\n YourBackend-->>App: Email verified — proceed\n","diagramHtml":"","diagramHtmlDark":""},"children":["sequenceDiagram\n participant App\n participant YourBackend as Your backend\n participant Banxa\n\n App->>YourBackend: Customer submits email\n YourBackend->>Banxa: POST /eapi/v1/verifications/otp\n Banxa-->>YourBackend: 200 { message: \"OTP sent successfully\" }\n Banxa->>App: Email with OTP code (via customer's inbox)\n App->>App: Customer enters OTP code\n App->>YourBackend: Code submitted\n YourBackend->>Banxa: POST /eapi/v1/verifications/otp/verify\n Banxa-->>YourBackend: 200 { message: \"Success\" }\n YourBackend-->>App: Email verified — proceed\n"]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-1--send-the-otp-code","__idx":4},"children":["Step 1 — Send the OTP code"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /eapi/v1/verifications/otp"]}]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n \"identityReference\": \"customer-12345\",\n \"email\": \"user@example.com\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["identityReference"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Your stable identifier for this customer"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["email"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The email address to verify"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Success response (200):"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n \"message\": \"OTP sent successfully\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Banxa sends a short-lived 4-digit code to the provided email address. Your app should prompt the customer to check their inbox and enter the code promptly."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Rate limit:"]}," 3 requests per minute per customer."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-2--verify-the-otp-code","__idx":5},"children":["Step 2 — Verify the OTP code"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /eapi/v1/verifications/otp/verify"]}]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n \"identityReference\": \"customer-12345\",\n \"email\": \"user@example.com\",\n \"code\": \"1234\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["identityReference"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Same value used in the send request"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["email"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Same email address used in the send request"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["code"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["4-character code from the email"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Success response (200):"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n \"message\": \"Success\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["On success, the email address is recorded as verified on the customer's identity. You can proceed with eligibility checks and ramp creation."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Rate limit:"]}," 4 verification attempts per minute per customer."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"sparse-identity-and-email-collection","__idx":6},"children":["Sparse identity and email collection"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["OTP can be used to collect and verify a customer's email address after identity creation. An identity created without an email address is valid — the OTP send call writes the email onto the identity record on successful verification."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This pattern is useful when your onboarding flow collects email separately from identity creation:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Create identity via ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /eapi/v0/identities/basic"]}," — omit the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["email"]}," field"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["When ready to verify the customer's email, call ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /eapi/v1/verifications/otp"]}," with the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["identityReference"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["email"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The email is written onto the identity record on successful verification"]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"email-merging","__idx":7},"children":["Email merging"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If the email address supplied in the OTP flow already exists on a different Banxa identity record, Banxa merges the two records. The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["identityReference"]}," from the newer identity is moved onto the existing account; the newer identity and its associated ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["externalCustomerId"]}," are removed."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Practical effect:"]}," after a merge, the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["identityReference"]}," you supplied continues to work, but it now refers to the older account. Any KYC state from the older account is carried over."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["What to watch for:"]}," if a customer uses an email address that belongs to an existing Banxa account (e.g. they previously transacted via a different partner), the merge will silently absorb their new identity into the existing one. The customer's KYC history is preserved, but be aware that the older account's state governs their compliance tier."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"error-handling","__idx":8},"children":["Error handling"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"wrong-otp-code","__idx":9},"children":["Wrong OTP code"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["422"]}," response indicates the code is incorrect:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n \"message\": \"Code does not match, please try again\",\n \"code\": 180,\n \"traceId\": \"2f92b534-55a0-4340-9e2a-2575913ff792\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["An incorrect code cannot be corrected — the OTP flow must restart from the beginning. Call ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /eapi/v1/verifications/otp"]}," again to issue a new code before prompting the customer to re-enter."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"rate-limit-exceeded","__idx":10},"children":["Rate limit exceeded"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["429"]}," response is returned when the per-minute limit is reached:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n \"message\": \"Too many OTP requests. Please try again later.\",\n \"code\": 429,\n \"traceId\": \"9fafad58-f1eb-44db-a77e-329610b1b755\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Limit"},"children":["Limit"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Threshold"},"children":["Threshold"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["OTP send"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["3 per minute per customer"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["OTP verify"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["4 per minute per customer"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Present a clear wait-state to the customer rather than retrying silently."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"feature-not-enabled","__idx":11},"children":["Feature not enabled"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["403"]}," response means OTP is not enabled on your merchant account. Contact your Banxa integration manager."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"invalid-identity-reference","__idx":12},"children":["Invalid identity reference"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["422"]}," response with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"The selected identity reference is invalid.\""]}," means the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["identityReference"]}," does not exist in Banxa's system. Ensure identity creation has completed successfully before triggering OTP."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"interaction-with-banxa-hosted-checkout","__idx":13},"children":["Interaction with Banxa Hosted Checkout"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If your integration also uses Banxa Hosted Checkout, headless OTP suppresses the email verification screen that Banxa Hosted Checkout would otherwise show to the customer."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"summary","__idx":14},"children":["Summary"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Step"},"children":["Step"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Endpoint"},"children":["Endpoint"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Rate limit"},"children":["Rate limit"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["1. Send OTP"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /eapi/v1/verifications/otp"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["3/min"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["2. Verify code"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /eapi/v1/verifications/otp/verify"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["4/min"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["On wrong code: restart from step 1. On rate limit: wait and retry. On success: email is verified on the identity record and the customer can proceed."]}]},"headings":[{"value":"OTP Email Verification","id":"otp-email-verification","depth":1},{"value":"When to use OTP verification","id":"when-to-use-otp-verification","depth":2},{"value":"Endpoints","id":"endpoints","depth":2},{"value":"The verification flow","id":"the-verification-flow","depth":2},{"value":"Step 1 — Send the OTP code","id":"step-1--send-the-otp-code","depth":2},{"value":"Step 2 — Verify the OTP code","id":"step-2--verify-the-otp-code","depth":2},{"value":"Sparse identity and email collection","id":"sparse-identity-and-email-collection","depth":2},{"value":"Email merging","id":"email-merging","depth":2},{"value":"Error handling","id":"error-handling","depth":2},{"value":"Wrong OTP code","id":"wrong-otp-code","depth":3},{"value":"Rate limit exceeded","id":"rate-limit-exceeded","depth":3},{"value":"Feature not enabled","id":"feature-not-enabled","depth":3},{"value":"Invalid identity reference","id":"invalid-identity-reference","depth":3},{"value":"Interaction with Banxa Hosted Checkout","id":"interaction-with-banxa-hosted-checkout","depth":2},{"value":"Summary","id":"summary","depth":2}],"frontmatter":{"title":"OTP Email Verification","description":"How to use headless OTP to verify a customer's email address within your app, without triggering a Banxa-hosted verification screen.","seo":{"title":"OTP Email Verification"}},"lastModified":"2026-05-26T06:13:49.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/products/native-api/docs/how-it-works/otp-verification","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}