API Reference
Last updated

API Reference

The TalusPay API is built around REST principles, with resource-oriented URLs that are easy to predict. It accepts form-encoded request bodies, returns JSON-encoded responses, and adheres to standard HTTP response codes, authentication, and HTTP verbs.

You can utilize the TalusPay API in test mode, which operates independently of your live data and does not interact with banking networks. The API key you provide determines whether a request is executed in live mode or test mode.

For sandbox testing environments, please refer to the Testing Documentation.

If you account and required custom merchant onboarding application you can use https://taluspay-sandbox.com/{CUSTOM_PARTNER_NAME} - please contact our support to enable this feeature.

Authentication

HTTP requests to the REST API are protected with HTTP Basic authentication (account-secret). In short, you will use your account SID as the username and your account secret key as the password for HTTP Basic authentication.

curl -X POST https://api.taluspay.com/{version_id}/merchants
-u '[YOUR ACCOUNT ID]:[YOUR ACCOUNT SECRET KEY]'

Test mode account secret keys have the prefix sk_test_ and live mode secret keys have the prefix sk_live_.

Additionally, endpoints with authentication will check if the merchant belongs to the account.

For onboarding calls you create merchant session (account-merchant-session-token) - which uses HTTP Bearer JWT - this is short-lived session (token expiration).

Error Codes - HTTP Status Mapping

The following table maps Stripe error codes to HTTP status codes to help with consistent error handling in your API.

HTTP Status CodeNameDescription
200OKEverything worked as expected.
400Bad RequestThe request was unacceptable, due to missing or invalid required parameter.
401UnauthorizedNo valid Auth key provided.
403ForbiddenThe Auth key doesn’t have permissions to perform the request.
404Not FoundThe requested resource doesn’t exist.
409ConflictThe request conflicts with another request (perhaps due to using the same idempotent key).
429Too Many RequestsToo many requests hit the API too quickly. We recommend an exponential backoff of your requests.
500, 502, 503, 504Server ErrorsSomething went wrong. If this persists please contact us.

Error Response

The error response object has the following structure:

Fields

  • error_code: A numerical value that represents a specific error. This is a http status code in most cases.

    • Type: number
    • Example: 400

  • message: A descriptive message providing more details about the error. It can be a single string or an array of strings.

    • Type: string or string[]
    • Example: "An error has occurred" or ["Error 1", "Error 2"]

  • error: A string field that represents the type or category of the error.

    • Type: string
    • Example of a domain error: COULD_NOT_CREATE_MERCHANT
    • Example of payload validation error: BAD_REQUST
Example

A typical error response might look like:

{
    "error_code": 400,
    "message": ["Error 1", "Error 2"],
    "error": "BAD_REQUST"
}
{
    "error_code": 400,
    "message": "Merchant already exists",
    "error": "COULD_NOT_CREATE_MERCHANT"
}

Request IDs

Every API request is assigned a unique request identifier, which you can find in the response headers under "X-Request-Id." Additionally, you can locate request identifiers in the URLs of individual request logs within your Dashboard.

To help us resolve your issue more quickly, please include the request identifier when you reach out to us regarding a specific request.

Versioning

Each version release of our API, starting with v1, is designed to ensure stability and smooth transitions for developers. Major releases may include backwards-incompatible changes, requiring attention during upgrades. The current version is v1, and all updates, including new features, fixes, and potential deprecations, are documented in our changelog. For details on API updates and guidelines for handling version upgrades, you can refer to our comprehensive API changelog and upgrade documentation.

 
Next page