TalusPay API

Create merchants, send them to a hosted onboarding application, and follow their progress through signing, review and payment setup. Requests use REST endpoints and JSON, except file uploads, which use multipart form data.

New integration? Start with the integration checklist, then onboard your first merchant.

Payments API in progress. You can onboard merchants and track their payment setup status. Endpoints for taking payments, refunds and charges are not published yet.

Find your next step

I want to…	Start here
Set up an integration from sandbox to production	Integration checklist
Create a merchant and open hosted onboarding	Merchant onboarding guide
Design the merchant's progress and recovery screens	Merchant experience flows
Understand application and payment statuses	How KYC works
Receive and verify merchant updates	Webhooks
Simulate approval, decline and webhook deliveries	Testing
Look up request fields and responses	API reference

Environments

Environment	API base URL	Credentials
Sandbox	`https://api.taluspay-sandbox.com`	Sandbox account ID and secret key
Production	`https://api.taluspay.com`	Live account ID and secret key

Use the sandbox base URL and sandbox credentials while building. When you go live, switch both and create your webhooks again in production. See Testing for the sandbox merchant application.

For a branded sandbox onboarding application at https://taluspay-sandbox.com/{CUSTOM_PARTNER_NAME}, contact TalusPay to enable it for your account.

Authentication

Your server authenticates API requests with HTTP Basic authentication (api-key-secret in the API reference):

Username: your account ID (account_…).
Password: your account secret key.

Make a first read-only request to check your credentials:

curl 'https://api.taluspay-sandbox.com/v1/merchants?page=1&limit=1' \
  -u "<account_id>:<secret_key>"

A successful response contains a page of merchants and a pagination object. An empty list is expected before you create your first merchant. A 401 response means the credentials are missing or invalid.

Keep secret keys on your server. Don't put them in browser code, mobile apps or URLs. Merchant access is scoped to your account.

For hosted onboarding, your server creates an onboarding link and redirects the merchant to the returned url. TalusPay handles authentication and session management within the hosted application. Each endpoint lists the authentication it accepts.

Error codes and recovery

Use the HTTP status to understand the kind of failure, and the error field for a specific business-rule error.

HTTP status	Meaning	Next step
`200`, `201`, `204`	The request succeeded.	Read the endpoint's response definition.
`400`	A required value is missing or invalid.	Correct the fields named in `message`.
`401`	Credentials are missing, invalid or expired.	Check the environment, credentials or session.
`403`	The credentials don't permit this action.	Check the endpoint's access requirements.
`404`	The resource wasn't found.	Check the ID and that it belongs to your account.
`409`	The request conflicts with existing data.	Resolve the conflict, such as a duplicate merchant email within your account (ignoring case).
`429`	Too many requests.	Reduce the request rate and use exponential backoff.
`500`, `502`, `503`, `504`	A server failed to complete the request.	Check the resource's current state before repeating a write. Contact support if it persists.

Error response

Error responses follow the API reference. For example:

{
  "status_code": 400,
  "message": "Device IMEI '357111112222333' is not available to be used.",
  "error": "DEVICE_IMEI_ALREADY_BOUND",
  "debug_id": "dbg_01k8x2v9j3m4n5p6q7r8s9t0vw",
  "timestamp": "2026-01-15T10:30:00.000Z"
}

Field	How to use it
`status_code`	The HTTP status code.
`message`	A string, or an array of validation messages. Show useful correction guidance; don't branch on this text.
`error`	A stable code for a business-rule error. Other failures can use generic exception names.
`details`	Optional extra context for some business-rule errors.
`debug_id`	A support reference, when present. Also sent in the `X-Debug-Id` response header.
`timestamp`	When the error occurred.

Request IDs

When reporting a failed request, include its debug_id or the X-Debug-Id response header, if available. Don't send credentials or onboarding URLs to support.

Versioning

The current API version is v1, included in endpoint paths such as /v1/merchants. Follow the request and response definitions in the API reference when updating your integration.