Connecting to Lume

This guide explains how to connect to Paymentology’s Lume platform when onboarding a new programme or migrating an existing integration.

What is Lume?

Lume is Paymentology’s cloud-native platform and operating model for delivering and operating client environments.

For API integrations, Lume uses mutual TLS (mTLS) for client-certificate authentication and OAuth 2.0 for request authorisation.

What changed

Lume standardises REST API access through secure public connectivity, protected by mutual TLS (mTLS) and OAuth 2.0. This removes the need for VPN connectivity in the standard integration model.

OAuth 2.0 provides request authorisation through Bearer access tokens. Obtain an access token using the documented authentication flow and include it in API requests as required.

For a new integration, your application:

• Presents a client certificate to authenticate the connection.
• Obtains an OAuth access token using the Client Credentials flow.
• Sends the token as a Bearer token when calling an API.

For existing integrations migrating to Lume, Paymentology will confirm the applicable migration and connectivity arrangements during onboarding. OAuth 2.0 access tokens are required for machine-to-machine API access.

Why this matters

Lume uses mTLS certificates to identify your integration and OAuth 2.0 access tokens to authorise API requests. This provides a consistent, secure way to connect to the platform over the public internet.

Connect to the Lume APIs

Your onboarding configuration provides the values required for your environment, including:

• API base URL.
• OAuth token URL and audience.
• OAuth client_id and client_secret.
• Client-certificate access and environment details.
• Any endpoint-specific scopes or security requirements.

The OAuth client_id used to obtain an access token may be different from a client_id required in an API request body. Use the value specified by the relevant API documentation.

Before you begin

To access Lume APIs, a client ID and client secret will be provided during onboarding. The client secret will have a defined renewal cycle that should be followed to maintain uninterrupted access.

The three steps

1. Access Setup: Generate and securely store a private key, create a certificate signing request (CSR), and obtain a client certificate for mTLS.
2. Get an Access Token: Use the OAuth 2.0 Client Credentials flow to obtain a Bearer access token. Cache and reuse the token until shortly before the returned expires_in value.
3. Making API Calls: Configure your HTTP client to use mTLS and send the access token in the Authorization header. Follow the documentation for each endpoint’s method, request body, headers, and response format.

Secure Card APIs

PaySecure APIs use the same mTLS and OAuth controls as other Lume APIs. Some PaySecure endpoints have additional security and traceability requirements.

Refer to PaySecure API for the specific endpoint contract. Do not assume that additional headers or encryption requirements apply to every PaySecure endpoint.

Connect to PayControl

PayControl user sign-in is separate from machine-to-machine API access.

Paymentology onboards PayControl users into the organisation’s identity-management service. Once the user account and permissions have been configured, the user signs in to PayControl through Auth0.

For user access, permissions, or sign-in support, follow the PayControl onboarding guidance supplied for your organisation.