Skip to main content

Authentication, amounts and reliable retries

Select environment and protect keys​

EnvironmentAPI Base URLKey prefix
Testhttps://connect-dev.invisipay.fiinv_test_
Livehttps://connect.invisipay.fiinv_live_

Confirm account access to the selected environment. Key and target environments must match. Send Authorization: Bearer ... from the server and use JSON content type. Merchant identity comes from the verified key, not a browser-provided merchant ID.

Store keys in key management, outside browser/mobile bundles, logs and cashier URLs. Keep environments clear during rotation. Webhook verification uses the endpoint secret, not the merchant API Key.

Exact amounts​

Amounts are positive currency-unit decimal strings with at most eight fractional digits. "10.5" with currency=usdc means 10.5 USDC. JSON numbers, scientific notation and grouping separators are rejected; values are not automatically rounded.

Use exact decimal/fixed-point storage. Compare "10" and "10.00" by decimal value without floating-point conversion. Actual payments must also meet the selected payment method, asset and network precision/range requirements; inspect payment methods.

Persist idempotent operations​

  1. Generate and durably save an operation ID, key and complete request body in a local transaction.
  2. Send create/close operations using that saved record.
  3. Reload it after timeout/restart without changing amounts or generating a new key.
  4. Associate the returned resource ID, then retrieve its current state.

Keys contain 1–255 bytes, without surrounding whitespace, newline or NUL. UUID v4 is recommended. Within 24 hours, retries replay the first result; a creation replay may still show the original open state. Retrieve the resource for current status.

ResultRecovery
400 idempotency_key_parameter_mismatchRestore original parameters; create another record only after a new business decision
409 idempotency_key_in_flightBack off and retain the original key/body
Disconnection, timeout or 5xxOutcome is unknown; recover the original operation and retrieve resources
More than 24 hoursInspect the original resource or list by order before assuming another submission is safe

order_id is not unique. Platform idempotency handles one API operation; merchant fulfillment still requires order-level deduplication. See common conventions.

Errors and rate limits​

Use HTTP status and error.code, not message wording. Retain Request-Id, excluding Authorization and keys from logs. For 401, check key/environment; for 403, check permissions. A 404 can mean absent or inaccessible and is not proof of failed payment.

For 429, respect Retry-After when present and provider limits, add jitter and bound concurrency. Do not let every browser poll independently at high frequency. Timeouts or invalid responses do not mean unpaid.

Pagination and reconciliation​

Lists use page_size (default 20, range 1–100) and page_token, returning data and next_page_token. Empty token ends the list. Keep filters stable across pages, deduplicate changing resources by ID and reconcile against durable local orders and bounded query windows.

Use the server client and consult error responses plus each operation’s business errors.