Integration checklist

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.

1. Get your sandbox credentials. You receive an account ID (account_…) and a secret key once your ISV account is set up. Every call authenticates with them as HTTP Basic auth. See Authentication.
2. Keep secrets on your server. Your account secret key and webhook signing secrets must never reach a browser or a mobile app.
3. 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.

4. Create a webhook. Subscribe an HTTPS endpoint to the merchant scope with POST /v1/webhooks, and store the signing secret it returns. See Webhooks.
5. Verify every delivery. Check X-Talus-Webhook-Signature against the raw request body and reject old timestamps. See Webhook Signatures.
6. Handle duplicates. Use the event id to process each event only once.
7. 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.

8. Create merchants. Create each merchant with POST /v1/merchants, and prefill the application with what you already know. See Merchant Onboarding Guide.
9. Send the merchant to onboarding. Create an onboarding link, sign the merchant in to your app first, then redirect them to the link. See Create an Onboarding Link.
10. Handle the return. Confirm the merchant's status with the API when they come back, instead of trusting the redirect.
11. Re-engage merchants who stop. Find merchants still IN_PROGRESS or 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 Monitor and Re-engage.
12. Handle every KYC outcome. Approved, declined, on hold and pended merchants each need their own message. Send merchants who must act to status_review_url; show a waiting message while submitted information is under review. See merchant experience flows.
13. Track payment setup separately from approval. Use merchant.payments_onboarded to mark setup complete, and confirm payment_onboarding_status from the API if the event is missed. Gateway credentials are not returned by the public API or merchant webhooks.

The payments API (taking payments, refunds and charges) is in progress. This checklist will cover it once it is published.

14. Test your webhook endpoint. Send each merchant event to your endpoint with POST /v1/events/test. Test deliveries have event IDs starting with evt_00000000000000.
15. Test onboarding end to end. Approve, decline and deactivate sandbox merchants with POST /v1/events/trigger, and check that your app reacts to each one. See Testing.
16. Test failures. Check that your app copes with API errors, a webhook signature that doesn't match, and a webhook that never arrives.

17. Give merchants their statements. List a merchant's monthly statements with GET /v1/statements/{merchant_id} and download them as PDF.

When every step above works in sandbox:

• Switch to https://api.taluspay.com and your live credentials.
• Create your webhooks again in production. Sandbox webhooks and secrets don't carry over.
• Remove approve and decline calls to POST /v1/events/trigger: they change nothing in production but still return success: true. Deactivate works in production.
• Follow the status page to hear about incidents.

Next: test the merchant experience or look up endpoints in the API reference.