# 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](/checklist), then [onboard your first merchant](/onboarding).

> **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](/checklist) |
| Create a merchant and open hosted onboarding | [Merchant onboarding guide](/onboarding) |
| Design the merchant's progress and recovery screens | [Merchant experience flows](/flows) |
| Understand application and payment statuses | [How KYC works](/tutorials#how-kyc-works) |
| Receive and verify merchant updates | [Webhooks](/webhooks) |
| Simulate approval, decline and webhook deliveries | [Testing](/testing) |
| Look up request fields and responses | [API reference](/openapi) |


## 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](/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:

```bash
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](/onboarding#2-create-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](/openapi). For example:

```json
{
  "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](/openapi) when updating your integration.