Skip to main content

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​

EnvironmentBase URL
Productionhttps://connect.invisipay.fi/
Testhttps://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​

ItemConvention
Field namesUse snake_case; enum values follow their attribute definitions
AmountsPositive decimal strings with at most 8 decimal places; JSON numbers, scientific notation, and thousands separators are not accepted
CurrenciesLowercase codes: usdc, usdt
Amount unitsThe currency's own units: "10.12345678" means 10.12345678 USDT when currency=usdt, independently of the payment network
TimesRFC 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 400 with idempotency_key_parameter_mismatch. Check the original request.
  • While the original request is still processing, the response may be 409 with idempotency_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:

AttributeTypeRequiredDescription
page_sizeintegerNoItems per page; default 20, range 1–100
page_tokenstringNoThe 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"
}
}
AttributeTypeDescription
typestringError category, listed below
codestringSpecific error code, in lowercase
messagestringHuman-readable error description
paramstringOptional related request parameter
detailsobjectOptional additional error information
HTTP statuserror.typeMeaning
400invalid_request_errorInvalid parameters or an operation not allowed in the current state
400idempotency_errorThe same idempotency key was used with different parameters
401authentication_errorAPI Key missing or invalid
403permission_errorMerchant disabled or operation not permitted
404not_found_errorResource missing or inaccessible
409conflict_errorOriginal idempotent request still processing, or resource conflict
429rate_limit_errorRequest rate exceeded
5xxapi_errorPlatform 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.