Skip to main content

Overview

The SDK is configured once and exposes resource groups (invoices, tokens, commerce, events, websockets, etc.).

Authentication

The SDK supports multiple auth contexts (set once or per request). Choose the minimum required for your surface:
  • apiKeyx-api-key (merchant scope)
  • commerceApiKeyx-commerce-api-key (commerce scope)
  • bearerTokenAuthorization: Bearer ... (dashboard JWT)
  • userAccessTokenUser-Authorization: Bearer ... (commerce user routes)
  • sessionToken + signaturex-session-token + x-signature (payor/session browser-safe)

Request

Construct a client

Switch auth context

If both keys are configured, the SDK selects the correct header per endpoint and never sends both headers.

Response

The configured client will automatically attach the correct headers and defaults:

Errors

  • 401 auth missing/invalid: verify the credential you configured matches the endpoint (merchant vs commerce vs payor).
  • 403 forbidden: key may be scoped/suspended, or environment access may not be enabled.
  • Browser runtime error when using server keys: use session/ws tokens instead of server API keys.

Examples

Retries and timeouts

Browser safety

By default, the SDK rejects server API keys in browser runtimes. If you truly need to override this (not recommended), you must opt in:

WebSockets

WebSocket usage requires a webSocketFactory (browser provides WebSocket; Node.js typically uses ws).
Next: Invoices