Common API conventions
This reference defines the common conventions for the merchant API.
For integration availability, see API availability. Confirm the target environment and account support each operation before using it. Pending operations are provided for integration planning.
1. Common conventions
Requests and authentication
| Environment | Base URL |
|---|---|
| Production | https://connect.invisipay.fi/ |
| Test | https://connect-dev.invisipay.fi/ |
API paths begin with /v1 and use HTTPS. Request and response bodies use JSON. These are the documented environment addresses; confirm the appropriate environment and account access before integration.
Authenticate merchant calls to the platform with an API Key using Bearer authentication:
Authorization: Bearer inv_test_...
Content-Type: application/json
Test keys begin with inv_test_; production keys begin with inv_live_. API Keys are for merchant servers only. Never expose them to browsers or mobile clients.
Platform-to-merchant Webhooks use signature verification rather than your merchant API Key. Merchant Webhook delivery is pending; use the availability guidance before depending on it.
Field formats
| Item | Convention |
|---|---|
| Field names | Use snake_case; enum values follow their attribute definitions |
| Amounts | Positive decimal strings with at most 8 decimal places; JSON numbers, scientific notation, and thousands separators are not accepted |
| Currencies | Lowercase codes: usdc, usdt |
| Amount units | The currency's own units: "10.12345678" means 10.12345678 USDT when currency=usdt, independently of the payment network |
| Times | RFC 3339 with a timezone; responses use UTC, for example 2026-10-15T08:00:00Z |
Amounts are validated when creating or updating a Checkout and are not automatically rounded. Responses remove redundant leading and trailing decimal zeros: for example, "010.500" returns "10.5". At confirmation, amounts must also meet the selected payment method's precision and amount-range requirements.
Use List available payment methods to discover the currency/network combinations available to your merchant account.
Idempotent requests
Network timeouts or process crashes can leave a request's outcome unknown. An Idempotency Key allows safe retries without executing the same operation again.
Send Idempotency-Key in the request header. UUID v4 is recommended. Operations requiring this header identify it in their Attributes table:
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000
Keys are strings of 1–255 bytes and must not contain surrounding whitespace, newlines, or NUL characters. No fixed prefix or UUID format is mandatory. Do not include personal information or secrets.
- Use a new key for a new operation, and the original key for retries, with unchanged request parameters.
- Within 24 hours, the same key does not execute the operation again. Once complete, retries return the first operation's result.
- Reusing a key with different parameters returns
400withidempotency_key_parameter_mismatch. Check the original request. - While the original request is still processing, the response may be
409withidempotency_key_in_flight. Retry later with the same key and parameters; do not start the operation again under a new key. - After 24 hours, query the original outcome before deciding whether to start a new operation.
Pagination
List operations use cursor pagination:
| Attribute | Type | Required | Description |
|---|---|---|---|
page_size | integer | No | Items per page; default 20, range 1–100 |
page_token | string | No | The previous page's next_page_token; omit on the first page |
{
"data": [],
"next_page_token": ""
}
data contains the current page's resource array. next_page_token is the next-page cursor; an empty string means there is no next page. Keep filters unchanged when requesting the next page. Some operations do not paginate; follow their definitions.
Error responses
Successful merchant API requests return 200. Failures use HTTP status codes and a common error object:
{
"error": {
"type": "invalid_request_error",
"code": "checkout_invalid_state",
"message": "This operation is not allowed in the current state.",
"param": "status"
}
}
| Attribute | Type | Description |
|---|---|---|
type | string | Error category, listed below |
code | string | Specific error code, in lowercase |
message | string | Human-readable error description |
param | string | Optional related request parameter |
details | object | Optional additional error information |
| HTTP status | error.type | Meaning |
|---|---|---|
400 | invalid_request_error | Invalid parameters or an operation not allowed in the current state |
400 | idempotency_error | The same idempotency key was used with different parameters |
401 | authentication_error | API Key missing or invalid |
403 | permission_error | Merchant disabled or operation not permitted |
404 | not_found_error | Resource missing or inaccessible |
409 | conflict_error | Original idempotent request still processing, or resource conflict |
429 | rate_limit_error | Request rate exceeded |
5xx | api_error | Platform or upstream service failure |
Handle failures using HTTP status and code, without depending on the exact wording or language of message.
Response headers
Each response includes a unique request identifier in the Request-Id header. Provide it when contacting the platform to investigate an issue.
Request-Id: 4bf92f3577b34da6a3ce929d0e0e4736
The platform generates this identifier; merchants do not need to supply it. Every retry receives a new request identifier, even when using the same Idempotency-Key.