Merchant Authentication Configuration

Merchant authentication configuration stores OAuth settings for authenticating with external merchant systems. Each record defines the full OAuth flow parameters for a specific merchant, enabling the platform to obtain and refresh access tokens from merchant APIs.

Why per-merchant authentication?

Different merchants expose different APIs with different authentication requirements. Rather than hardcoding integration credentials, the platform stores OAuth configuration as data, allowing:

• New merchant integrations without code changes
• Multiple OAuth configurations per merchant (e.g. different scopes for different APIs)
• Temporal validity via start_date/end_date for credential rotation

OAuth flow configuration

The configuration models a complete OAuth 2.0 flow in three stages:

Stage 1: Authorisation request

Field	Purpose
merchant_oauth_service_name	Human-readable name for this OAuth service
merchant_oauth_auth_method	HTTP method for the auth request
merchant_oauth_auth_url	The authorisation endpoint URL
merchant_oauth_scopes	Requested OAuth scopes
merchant_oauth_auth_parameters	Additional parameters for the auth request
merchant_oauth_response_type	OAuth response type: CODE or TOKEN

Stage 2: Access token exchange

Field	Purpose
merchant_oauth_access_token_method	HTTP method for token exchange
merchant_oauth_access_token_url	The token endpoint URL
merchant_oauth_access_token_parameters	Parameters for the token request

Stage 3: Token refresh

Field	Purpose
merchant_oauth_refresh_token_method	HTTP method for refresh
merchant_oauth_refresh_token_url	The refresh endpoint URL
merchant_oauth_refresh_token_parameters	Parameters for the refresh request

Response types

The merchant_oauth_response_type column constrains the OAuth flow:

• CODE — authorisation code grant; the authorisation endpoint returns a code that is exchanged for tokens at the access token URL
• TOKEN — implicit grant; the authorisation endpoint returns the access token directly

HTTP method references

The auth method, access token method, and refresh token method fields use standard HTTP method codes, such as GET and POST. This ensures only valid HTTP methods are configured.

OAuth parameter fields

The parameter and scope fields store structured but flexible data. This accommodates the wide variation in OAuth provider requirements - some require specific query parameters, others need custom headers or body fields. Raytio reads these values and constructs the appropriate HTTP request.

Authorisation model

Authentication configuration is managed through the parent merchant's permissions. Users who can manage a merchant can maintain its OAuth configuration; users without those permissions cannot change authentication settings.