{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Integration checklist","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":"integration-checklist","__idx":0},"children":["Integration checklist"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use this checklist to build your TalusPay integration from your first sandbox call to going live. Work through the"," ","steps in order: each one links to the guide with the details."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"set-up-your-sandbox","__idx":1},"children":["Set Up Your Sandbox"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Get your sandbox credentials."]}," You receive an account ID (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["account_…"]},") and a secret key once your ISV account is"," ","set up. Every call authenticates with them as HTTP Basic auth. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/#authentication"},"children":["Authentication"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Keep secrets on your server."]}," Your account secret key and webhook signing secrets must never reach a browser or"," ","a mobile app."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Check your onboarding experience."]}," Make sure your branding, default pricing and hardware catalog are configured,"," ","so new merchants inherit them. Ask TalusPay to change anything that is missing."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"set-up-webhooks","__idx":2},"children":["Set Up Webhooks"]},{"$$mdtype":"Tag","name":"ol","attributes":{"start":4},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Create a webhook."]}," Subscribe an HTTPS endpoint to the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["merchant"]}," scope with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /v1/webhooks"]},", and store the"," ","signing ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["secret"]}," it returns. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/webhooks#subscribing"},"children":["Webhooks"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Verify every delivery."]}," Check ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["X-Talus-Webhook-Signature"]}," against the raw request body and reject old timestamps."," ","See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/webhooks#webhook-signatures"},"children":["Webhook Signatures"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Handle duplicates."]}," Use the event ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]}," to process each event only once."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Respond quickly."]}," Return a 2xx status within 8 seconds and do slow work afterwards. Failed deliveries are not"," ","retried, so read the merchant from the API whenever you are unsure of its state."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"onboard-merchants","__idx":3},"children":["Onboard Merchants"]},{"$$mdtype":"Tag","name":"ol","attributes":{"start":8},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Create merchants."]}," Create each merchant with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /v1/merchants"]},", and prefill the application with what you"," ","already know. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/onboarding#1-create-a-merchant"},"children":["Merchant Onboarding Guide"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Send the merchant to onboarding."]}," Create an onboarding link, sign the merchant in to your app first, then redirect"," ","them to the link. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/onboarding#2-create-an-onboarding-link"},"children":["Create an Onboarding Link"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Handle the return."]}," Confirm the merchant's status with the API when they come back, instead of trusting the"," ","redirect."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Re-engage merchants who stop."]}," Find merchants still ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["IN_PROGRESS"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["READY_TO_SIGN"]}," and send them back with the"," ","latest unexpired link, or create one if needed. Creating a link replaces all earlier links for that merchant. See"," ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/onboarding#5-monitor-and-re-engage-incomplete-onboardings"},"children":["Monitor and Re-engage"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Handle every KYC outcome."]}," Approved, declined, on hold and pended merchants each need their own message. Send"," ","merchants who must act to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status_review_url"]},"; show a waiting message while submitted information is under review."," ","See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/flows#show-progress-with-a-clear-next-action"},"children":["merchant experience flows"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Track payment setup separately from approval."]}," Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["merchant.payments_onboarded"]}," to mark setup complete, and"," ","confirm ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["payment_onboarding_status"]}," from the API if the event is missed. Gateway credentials are not returned by"," ","the public API or merchant webhooks."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"take-payments","__idx":4},"children":["Take Payments"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The payments API (taking payments, refunds and charges) is in progress. This checklist will cover it once it is"," ","published."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"test-your-integration","__idx":5},"children":["Test Your Integration"]},{"$$mdtype":"Tag","name":"ol","attributes":{"start":14},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Test your webhook endpoint."]}," Send each merchant event to your endpoint with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /v1/events/test"]},". Test"," ","deliveries have event IDs starting with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["evt_00000000000000"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Test onboarding end to end."]}," Approve, decline and deactivate sandbox merchants with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /v1/events/trigger"]},", and"," ","check that your app reacts to each one. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/testing#test-webhooks-and-onboarding"},"children":["Testing"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Test failures."]}," Check that your app copes with API errors, a webhook signature that doesn't match, and a"," ","webhook that never arrives."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"reporting","__idx":6},"children":["Reporting"]},{"$$mdtype":"Tag","name":"ol","attributes":{"start":17},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Give merchants their statements."]}," List a merchant's monthly statements with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /v1/statements/{merchant_id}"]}," ","and download them as PDF."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"go-live","__idx":7},"children":["Go Live"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When every step above works in sandbox:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Switch to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://api.taluspay.com"]}," and your live credentials."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Create your webhooks again in production. Sandbox webhooks and secrets don't carry over."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Remove approve and decline calls to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /v1/events/trigger"]},": they change nothing in production but still return"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["success: true"]},". Deactivate works in production."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Follow the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://status.taluspay.com"},"children":["status page"]}," to hear about incidents."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Next: ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/testing#merchant-experience-test-cases"},"children":["test the merchant experience"]}," or look up endpoints in the"," ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/openapi"},"children":["API reference"]},"."]}]},"headings":[{"value":"Integration checklist","id":"integration-checklist","depth":1},{"value":"Set Up Your Sandbox","id":"set-up-your-sandbox","depth":2},{"value":"Set Up Webhooks","id":"set-up-webhooks","depth":2},{"value":"Onboard Merchants","id":"onboard-merchants","depth":2},{"value":"Take Payments","id":"take-payments","depth":2},{"value":"Test Your Integration","id":"test-your-integration","depth":2},{"value":"Reporting","id":"reporting","depth":2},{"value":"Go Live","id":"go-live","depth":2}],"frontmatter":{"seo":{"title":"Integration checklist"}},"lastModified":"2026-11-04T11:41:24.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/checklist","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}