Who this page is for

Teams setting up machine-to-machine access to Lume APIs.

This page covers mTLS client certificates. For OAuth access tokens, see Getting an Access Token.

For PayControl user sign-in, see the PayControl documentation.

Before you begin

Your organisation has completed Lume onboarding.
You know whether you are setting up access for UAT or Production.
You have access to the Certificate Management Portal for the required environment.
OpenSSL, or an equivalent tool, is available in your environment.

Paymentology provides the OAuth configuration separately, including the token URL, audience, OAuth client_id, and client_secret.

What you create and receive

Item	Responsibility
Private key	Created and retained securely by your organisation
Certificate Signing Request (CSR)	Created by your organisation and submitted through the Certificate Management Portal. Paymentology Service Delivery Team creates the account and grants access for you.
Client certificate	Issued after the CSR is approved; used with the private key for mTLS
OAuth credentials	Provided as part of onboarding; used to obtain access tokens

Generate a private key and CSR

Use an automated process where possible, so that private keys are generated and stored securely. The following OpenSSL commands are provided as an example.

Create a certificate request configuration file

Create a file named pty-mtls-client-cert.conf:

[ req ]
default_bits       = 4096
prompt             = no
default_md         = sha256
distinguished_name = dn

[ dn ]
C  = UK
ST = London
L  = London
O  = Your Company
OU = Engineering
CN = YourCompany - UAT

Update the organisation and environment values to match the certificate you are requesting. Create separate certificate material for UAT and Production.

Generating a private key

openssl genrsa -out pty-mtls-client-cert.key.pem 4096

Keep this file confidential. Store it in an approved secret-management system or protected keystore. Do not send it to Paymentology or upload it to the Certificate Management Portal.

Generate the CSR

openssl req -new -key pty-mtls-client-cert.key.pem -out pty-mtls-client-cert.csr -config pty-mtls-client-cert.conf

Request and download your client certificate

Sign in to the Certificate Management Portal using the credentials provided during onboarding.
Select the appropriate environment: UAT or Production.
Submit the CSR generated in the previous step.
After approval, download the issued client certificate in PEM format (.cer).
Configure your integration to present the client certificate and its matching private key when establishing the TLS connection.

Certificate access is managed separately for UAT and Production. Ensure that the correct certificate is installed in each environment.

Maintain your certificate

Monitor the certificate expiry date and renew it before it expires. If you need to renew, replace, or revoke a certificate, follow the Certificate Management Portal process or contact Paymentology support.