{"templateId":"markdown","versions":[{"version":"v0-beta","label":"Beta (v0)","link":"/products/native-api/docs/how-it-works/interpreting-eligibility","default":true,"active":true,"folderId":"e4cb5a06"}],"sharedDataIds":{"sidebar":"sidebar-products/native-api/@v0-beta/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Interpreting Eligibility Requirements","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":"interpreting-eligibility-requirements","__idx":0},"children":["Interpreting Eligibility Requirements"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The eligibility check evaluates whether a specific transaction can proceed for a given identity and transaction context."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When additional information is required, the response includes a list of ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["requirements"]},". These requirements indicate what your platform needs to collect next in order to satisfy compliance and continue the transaction."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Each requirement represents a category of information, not always a single field."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"eligibility-response-overview","__idx":1},"children":["Eligibility Response Overview"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The eligibility response indicates whether a transaction can proceed and whether additional information is required."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["It includes two key signals:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["paymentReady"]}," – whether the transaction can proceed immediately"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["requirements"]}," – which categories of information are required, if any"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A common and valid outcome is:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["paymentReady = true"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["requirements = empty"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This means the transaction can proceed without collecting additional information."]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Note:"]},{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},"An identity must still exist before a ramp can be created.",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paymentReady = true"]}," does not imply that an identity has already been created."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"when-requirements-are-empty","__idx":2},"children":["When Requirements Are Empty"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["An empty requirements list is expected in the following cases."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["KYC-free or low-risk transactions"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For some transaction contexts, no identity verification is required.",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},"Eligibility will return paymentReady = true with no requirements."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If the user does not yet have an identity, the partner must still create or establish one before proceeding with ramp creation."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Returning users with existing verification"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If a returning user has already completed the necessary verification for the current transaction context, eligibility will also return paymentReady = true with no requirements."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Previously submitted identity information is reused and no further user action is required."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If the transaction context changes (for example, a higher transaction amount, a different payment method, or a new jurisdiction), eligibility may return additional requirements and paymentReady may become false until those requirements are satisfied."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"requirements-dictionary","__idx":3},"children":["Requirements Dictionary"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The table below explains what each eligibility requirement means and what your platform is expected to collect."]},{"$$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":"Requirement"},"children":["Requirement"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"What this means"},"children":["What this means"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"What you need to collect"},"children":["What you need to collect"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["NAME"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The customer's legal name is required"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Given name and surname"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["DOB"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The customer's date of birth is required"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Date of birth"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["ADDRESS"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The customer's residential address is required"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Residential address"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["DOCUMENT"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Identity documents are required"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Passport or government ID details, document metadata"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["SELFIE"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A selfie or liveness check is required"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Live selfie capture or selfie image ",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"em","attributes":{},"children":["Note: Selfie and liveness are currently supported via Sumsub token sharing, or through Banxa-hosted flows where applicable."]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["OCCUPATION"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Occupation information is required"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Occupation industry and occupation (job title) from a predefined list"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["SOURCE_FUNDS"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Source of funds or wealth must be declared"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Select from a predefined list, e.g. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Salary"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["PURPOSE_OF_TX"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Transaction purpose is required"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Reason for transaction (e.g. investment, remittance)"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["TIN"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A tax identifier is required"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["SSN, TIN, or other jurisdictional tax identifier"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["POA"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Proof of address is required"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Utility bill, bank statement, address evidence"]}]}]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"how-to-handle-requirements-in-your-integration","__idx":4},"children":["How to Handle Requirements in Your Integration"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Recommended approach:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Check eligibility once sufficient transaction context is available."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["If no requirements are returned:",{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Ensure an identity exists"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Continue to ramp creation."]}]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["If requirements are returned:",{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Collect the required information in your UX."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Submit the information using the appropriate identity mechanisms."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Re-check eligibility before proceeding."]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Multiple requirements may be returned at the same time. Where possible, collect them together to minimise user friction."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"progressive-compliance","__idx":5},"children":["Progressive Compliance"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Eligibility requirements are evaluated dynamically."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["As transaction parameters change — such as transaction size, payment method, or jurisdiction — additional requirements may be returned."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This enables progressive onboarding:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Low-risk transactions proceed with minimal information"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Returning users benefit from previously completed verification"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Higher-risk transactions trigger additional checks only when required"]}]}]},"headings":[{"value":"Interpreting Eligibility Requirements","id":"interpreting-eligibility-requirements","depth":1},{"value":"Eligibility Response Overview","id":"eligibility-response-overview","depth":3},{"value":"When Requirements Are Empty","id":"when-requirements-are-empty","depth":3},{"value":"Requirements Dictionary","id":"requirements-dictionary","depth":2},{"value":"How to Handle Requirements in Your Integration","id":"how-to-handle-requirements-in-your-integration","depth":2},{"value":"Progressive Compliance","id":"progressive-compliance","depth":2}],"frontmatter":{"title":"Interpreting Eligibility","description":"How to read eligibility responses and act on requirements in a Banxa Native integration.","seo":{"title":"Interpreting Eligibility Requirements"}},"lastModified":"2026-05-19T23:30:38.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/products/native-api/docs/how-it-works/interpreting-eligibility","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}