{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["img"]},"type":"markdown"},"seo":{"title":"Merchant experience flows","siteUrl":"https://docs.taluspay.com","llmstxt":{"hide":false,"title":"TalusPay API documentation","description":"Onboard merchants, follow their application and payment setup, and receive merchant events with the TalusPay API.","details":{"content":"Start with the integration checklist and merchant onboarding guide.\nUse sandbox credentials with https://api.taluspay-sandbox.com while building;\nproduction uses https://api.taluspay.com and live credentials.\nAPI requests use HTTP Basic authentication with your account ID and secret key.\nEach endpoint lists the authentication it accepts. Keep secret keys on your server.\nThe payments API for taking payments, refunds and charges is in progress and is not published yet.\n"},"sections":[{"title":"Get started","includeFiles":["index.md","checklist.md","onboarding.md"]},{"title":"Build and test your integration","includeFiles":["flows.md","tutorials.md","webhooks.md","testing.md"]},{"title":"API reference","includeFiles":["openapi.yaml"]}]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"merchant-experience-flows","__idx":0},"children":["Merchant experience flows"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use these flows to design the screens around TalusPay's hosted onboarding. Your app owns the entry point and status"," ","screen; TalusPay hosts the application, signing and requests for additional KYC information."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The messages and button labels below are suggested UI copy. Status values and actions come from the"," ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/openapi"},"children":["API reference"]}," and ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/tutorials#how-kyc-works"},"children":["KYC guide"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"start-onboarding","__idx":1},"children":["Start onboarding"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Sign the merchant in to your app before opening their onboarding URL. Create the merchant and link on your server,"," ","using account credentials. Keep the returned URL private: it signs the merchant in to hosted onboarding."]},{"$$mdtype":"Tag","name":"Diagram","attributes":{"data-language":"mermaid","diagramType":"mermaid","diagramSource":"sequenceDiagram\n autonumber\n actor Merchant\n participant App as Your app and server\n participant API as TalusPay API\n participant Hosted as Hosted onboarding\n\n Note over App,API: Register a merchant webhook before onboarding\n Merchant->>App: Select Start application\n App->>API: POST /v1/merchants\n API-->>App: Merchant with id\n App->>API: POST /v1/onboarding_links\n API-->>App: url and expires_at\n App-->>Merchant: Open the returned url\n Merchant->>Hosted: Complete application and sign\n Note over Merchant,Hosted: Additional owners sign before KYC starts\n Hosted-->>App: Redirect to return_url, if provided\n App->>API: GET /v1/merchants/{merchant_id}\n API-->>App: Current application and payment statuses\n App-->>Merchant: Show progress and the next available action\n Note over App,API: Webhooks update progress independently of the redirect\n","diagramHtml":"Hosted onboardingTalusPay APIYour app and serverHosted onboardingTalusPay APIYour app and serverRegister a merchant webhook before onboardingAdditional owners sign before KYC startsWebhooks update progress independently of the redirectMerchantSelect Start application1POST /v1/merchants2Merchant with id3POST /v1/onboarding_links4url and expires_at5Open the returned url6Complete application and sign7Redirect to return_url, if provided8GET /v1/merchants/{merchant_id}9Current application and payment statuses10Show progress and the next available action11Merchant","diagramHtmlDark":"Hosted onboardingTalusPay APIYour app and serverHosted onboardingTalusPay APIYour app and serverRegister a merchant webhook before onboardingAdditional owners sign before KYC startsWebhooks update progress independently of the redirectMerchantSelect Start application1POST /v1/merchants2Merchant with id3POST /v1/onboarding_links4url and expires_at5Open the returned url6Complete application and sign7Redirect to return_url, if provided8GET /v1/merchants/{merchant_id}9Current application and payment statuses10Show progress and the next available action11Merchant"},"children":["sequenceDiagram\n autonumber\n actor Merchant\n participant App as Your app and server\n participant API as TalusPay API\n participant Hosted as Hosted onboarding\n\n Note over App,API: Register a merchant webhook before onboarding\n Merchant->>App: Select Start application\n App->>API: POST /v1/merchants\n API-->>App: Merchant with id\n App->>API: POST /v1/onboarding_links\n API-->>App: url and expires_at\n App-->>Merchant: Open the returned url\n Merchant->>Hosted: Complete application and sign\n Note over Merchant,Hosted: Additional owners sign before KYC starts\n Hosted-->>App: Redirect to return_url, if provided\n App->>API: GET /v1/merchants/{merchant_id}\n API-->>App: Current application and payment statuses\n App-->>Merchant: Show progress and the next available action\n Note over App,API: Webhooks update progress independently of the redirect\n"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["After returning:"]}," fetch the merchant on your server and show its current status. The redirect alone doesn't prove"," ","that signing, KYC or payment setup finished. ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/onboarding"},"children":["Implement this flow"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"resume-an-unfinished-application","__idx":2},"children":["Resume an unfinished application"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Offer ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Continue application"]}," for ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["IN_PROGRESS"]},", or ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Sign application"]}," for ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["READY_TO_SIGN"]},". Keep the same merchant ID"," ","when resuming so the merchant picks up where they left off."]},{"$$mdtype":"Tag","name":"Image","attributes":{"srcSet":"/assets/resume-onboarding-v2-light.d6914b21951c363db3239e2eeb55a1a92d217a5fa338445df9f41c9267c205de.33f780a6.png light, /assets/resume-onboarding-v2-dark.8f932bc1f0bb7b0d2bdd440c907b305b34faa1a3a45c11f0f60cec865cd73ce3.33f780a6.png dark","alt":"Resume flow: fetch the current merchant, offer Continue or Sign while editable, reuse the latest unexpired link or create a new one for the same merchant, then redirect to hosted onboarding. For signed applications, show current progress.","framed":false,"withLightbox":false,"width":"100%"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Check the application:"]}," use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /v1/merchants/{merchant_id}"]}," and its ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["lead_onboarding_status"]},". ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["IN_PROGRESS"]}," and"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["READY_TO_SIGN"]}," allow the merchant to continue; once the main owner signs (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["COMPLETED"]},"), show signing or review"," ","progress instead. See the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#show-progress-with-a-clear-next-action"},"children":["status guide"]}," for other states."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Choose the link:"]}," reuse a saved URL only when your server knows it is the latest link and its ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["expires_at"]}," is in the"," ","future. If it is missing, expired or possibly replaced, call ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /v1/onboarding_links"]}," with the same ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["merchant_id"]}," ","and use the returned ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["url"]},". Creating a new link invalidates all older links for that merchant."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Handle failures:"]}," if the status read or link request fails, stay on the status screen and offer ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Try again"]},"."," ","Prevent repeated clicks while requesting a link. If a link is rejected, refresh the merchant's status before offering"," ","another one."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"show-progress-with-a-clear-next-action","__idx":3},"children":["Show progress with a clear next action"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Show a readable status, a short explanation, and a button only when the merchant has something to do. Keep application"," ","review and payment setup separate: an approved application is not proof that payments are ready."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"application-and-review","__idx":4},"children":["Application and review"]},{"$$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":"API state"},"children":["API state"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Suggested heading and message"},"children":["Suggested heading and message"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Action"},"children":["Action"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["lead_onboarding_status"]}," is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["IN_PROGRESS"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Your application is in progress."]}," Complete your business and owner details, or continue where you left off."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Continue application"]}," → hosted onboarding"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["READY_TO_SIGN"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Your application is ready to sign."]}," Review it and sign the merchant agreement."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Sign application"]}," → hosted onboarding"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["COMPLETED"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Your application is signed."]}," Any remaining owners must sign before review can begin. Once all signatures are collected, review starts automatically."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No application editing action; refresh status when the merchant returns"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["KYC_IN_PROGRESS"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Your application is being reviewed."]}," We're verifying your business and its owners."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No action; refresh status when the merchant returns"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["APPROVED"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Your application is approved."]}," Check payment setup below."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Use the payment setup state"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["APPROVED_ON_HOLD"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PENDED"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Check your application review."]}," Read the expanded approval status to show whether action or waiting is needed."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Use the review details below"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["FAILED"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Onboarding could not be completed."]}," Show the available review outcome or support contact."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Contact support"]}," using your configured support destination"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Every merchant starts at ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["IN_PROGRESS"]},", even before any application data is sent, so use ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Start application"]}," for a"," ","merchant you have just created and ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Continue application"]}," after that. Clearing a required field moves a"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["READY_TO_SIGN"]}," merchant back to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["IN_PROGRESS"]},". Treat a status you don't know as one you don't act on: new statuses may"," ","be added."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"requests-for-more-information","__idx":5},"children":["Requests for more information"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For a submitted application, request ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /v1/merchants/{merchant_id}?expand=approval_status"]}," when review details are"," ","needed. The expansion calls the KYC provider live; avoid continuous polling."]},{"$$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":"Expanded approval_status"},"children":["Expanded ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["approval_status"]}]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Suggested heading and message"},"children":["Suggested heading and message"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Action"},"children":["Action"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["APPROVED_WITH_REVIEW"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["More information needed."]}," Your application is approved, but the review team needs additional information."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Provide information"]}," → ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status_review_url"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PENDED_ACTION_REQUIRED"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["More information needed."]}," Send the requested information so review can continue."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Provide information"]}," → ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status_review_url"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["APPROVED_UNDER_REVIEW"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PENDED_UNDER_REVIEW"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Your information is being reviewed."]}," No additional information is requested right now."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Optional ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["View review status"]}," → ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status_review_url"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["APPROVED"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Your application is approved."]}," Check payment setup below."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Use the payment setup state"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DECLINED"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Your application was declined."]}," Contact support if you need help understanding the outcome."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Contact support"]},"; don't offer another application as a retry"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Missing value"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Review details are not available yet."]}," Check again later."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Refresh status"]},"; keep the known application status visible"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Only show a review button when ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status_review_url"]}," is present. A missing expansion can mean KYC has not decided or"," ","could not be reached; it is not a decline. A failed status request should say ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["We couldn't refresh your status"]}," and"," ","offer ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Try again"]},", rather than replacing the merchant's status with a failure outcome."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"payment-setup","__idx":6},"children":["Payment setup"]},{"$$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":"payment_onboarding_status"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["payment_onboarding_status"]}]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Suggested heading and message"},"children":["Suggested heading and message"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Action"},"children":["Action"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["NOT_STARTED"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Payments are not set up yet."]}," Application approval and payment setup are separate steps."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Continue showing application progress; don't offer a payment action"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ONBOARDED"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Payment setup is complete."]}," Your account has been set up for payments."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Show setup completion; this guide doesn't provide a payment action"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["FAILED"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Payment setup needs attention."]}," We couldn't finish setting up payments."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Contact support"]},"; don't ask the merchant to repeat their application"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For a new integration, use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["merchant.payments_onboarded"]}," to learn when setup completes. If the event is missed, read"," ","the current merchant's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["payment_onboarding_status"]},". The public API and merchant webhooks do not return payment gateway"," ","credentials. Endpoints for taking payments are not published yet."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["deactivated"]}," is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["true"]},", show ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Account deactivated"]}," with a support destination instead of a ready-to-use payment"," ","action, even when earlier onboarding statuses were successful. Don't use these UI suggestions to override a current"," ","KYC restriction. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/tutorials#how-kyc-works"},"children":["How KYC works"]}," for review conditions."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"keep-the-status-screen-current","__idx":7},"children":["Keep the status screen current"]},{"$$mdtype":"Tag","name":"Image","attributes":{"srcSet":"/assets/status-screen-current-v3-light.9854ebbe0d91bbb87e514b32a90c5bc662b4e667e12f6133513bd4dd36b9133d.33f780a6.png light, /assets/status-screen-current-v3-dark.2a635450112e95531a68b0cdd72ce6bf373959f51ef740e719f42be91174625e.33f780a6.png dark","alt":"Keep the status screen current: verify each webhook's signature and timestamp, reject invalid deliveries, and acknowledge duplicates with a 2xx response. Persist new events before acknowledging within 8 seconds, then read the current merchant and update progress and available actions. A merchant returning or selecting Refresh status also triggers a current merchant read.","framed":false,"withLightbox":false,"width":"100%"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Persist work before acknowledging it, and finish the response within 8 seconds. Failed deliveries aren't retried"," ","automatically. Refresh from the API when a merchant returns, when an event leaves the state unclear, or when a status"," ","request is retried. Don't assume a missing webhook means onboarding failed. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/webhooks#delivery"},"children":["Webhook delivery"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"verify-the-experience","__idx":8},"children":["Verify the experience"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Test a new application, a return before all signatures are collected, an expired or replaced link, a request for more"," ","information, a declined application, payment setup failure, a missed webhook and a failed status refresh. Use"," ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/testing#test-webhooks-and-onboarding"},"children":["sandbox test events"]}," for the supported simulations; the testing guide lists"," ","which cases need a real hosted flow or fixtures."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Next: ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/onboarding"},"children":["implement hosted onboarding"]},", ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/tutorials#how-kyc-works"},"children":["read KYC statuses"]},", or"," ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/testing"},"children":["test the integration"]},"."]}]},"headings":[{"value":"Merchant experience flows","id":"merchant-experience-flows","depth":1},{"value":"Start onboarding","id":"start-onboarding","depth":2},{"value":"Resume an unfinished application","id":"resume-an-unfinished-application","depth":2},{"value":"Show progress with a clear next action","id":"show-progress-with-a-clear-next-action","depth":2},{"value":"Application and review","id":"application-and-review","depth":3},{"value":"Requests for more information","id":"requests-for-more-information","depth":3},{"value":"Payment setup","id":"payment-setup","depth":3},{"value":"Keep the status screen current","id":"keep-the-status-screen-current","depth":2},{"value":"Verify the experience","id":"verify-the-experience","depth":2}],"frontmatter":{"seo":{"title":"Merchant experience flows"}},"lastModified":"2026-11-07T07:52:38.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/flows","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}