> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fexco.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Set up a client certificate (Rate Service Connect API)

> Generate a private key and submit a Certificate Signing Request (CSR) to Fexco to obtain the client certificate required for Rate Service Connect API authentication.

The Rate Service Connect API requires a client certificate issued by Fexco before you
can make authenticated requests. Certificates have a fixed validity
period, if a certificate expires, all API authentication will fail until
a new one is issued. Complete this setup once, and repeat the process
before your certificate expires.

## Before you start

* `openssl` installed on the system where you will generate keys and CSRs.
* Your Fexco-assigned acquirer ID, a three-letter alphabetic code such
  as `TST`, provided by your Fexco project manager during onboarding.

Follow the steps below to generate a private key, create a CSR, and submit it to Fexco for signing.

**Step 1**

### Generate a private key

Run the following command in your terminal. Replace `YOUR_ACQUIRER_ID`
with your three-letter acquirer identifier. The command saves the
private key to `client_YOUR_ACQUIRER_ID.key` in your current
directory. Subsequent steps reference this file by name.

```bash theme={null}
openssl genpkey -algorithm RSA \
  -out client_YOUR_ACQUIRER_ID.key \
  -pkeyopt rsa_keygen_bits:4096
```

After generating the key, restrict file access so that only the
owner can read it.

```bash theme={null}
chmod 600 client_YOUR_ACQUIRER_ID.key
```

**Step 2**

### Create an OpenSSL configuration file

In the same directory as your private key, create a file named
`openssl-san.cnf` with the contents below.

> [!NOTE]
>
> Replace `C`, `ST`, and `L` with your own country, state, and
> location. The values below are placeholders only.

```ini theme={null}
[req]
default_bits = 4096
prompt = no
default_md = sha256
distinguished_name = dn
req_extensions = v3_req

[dn]
C=YOUR_COUNTRY_CODE
ST=YOUR_STATE
L=YOUR_CITY
O=YOUR_ACQUIRER_ID
OU=YOUR_CARD_ACCEPTOR_ID
CN=YOUR_CLIENT_NAME

[v3_req]
subjectAltName = @alt_names

[alt_names]
email = YOUR_TEAM_EMAIL
```

Replace `YOUR_COUNTRY_CODE`, `YOUR_STATE`, `YOUR_CITY`,
`YOUR_ACQUIRER_ID`, `YOUR_CARD_ACCEPTOR_ID`, `YOUR_CLIENT_NAME`, and
`YOUR_TEAM_EMAIL` with your own values.

The table below describes the fields validated during certificate
signing and API authentication:

| Field | Description |
| :- | :- |
| `O` (Organisation) | Your Fexco-assigned acquirer ID exactly as provided. Validated against the `x-acquirer-id` request header on every API call. |
| `OU` (Organisational Unit) | Your card acceptor or merchant ID. Validated against the `x-card-acceptor-id` header when merchant validation is enabled. |
| `CN` (Common Name) | A descriptive label for this certificate. Include an environment label such as `Test` or `Production` for operational clarity. |
| `email` | A team distribution list or shared mailbox alias, not an individual email address. Fexco uses this address for certificate renewal reminders. |

**Step 3**

### Generate the Certificate Signing Request

Replace `YOUR_ACQUIRER_ID` with your acquirer ID and run the command
in your terminal. It uses the private key from step 1
(`client_YOUR_ACQUIRER_ID.key`) and the configuration file from step 2
(`openssl-san.cnf`) to produce a `.csr` file, the file you will
submit to Fexco for signing. `openssl` creates it automatically in
your current directory.

```bash theme={null}
openssl req -new \
  -key client_YOUR_ACQUIRER_ID.key \
  -out client_YOUR_ACQUIRER_ID.csr \
  -config openssl-san.cnf
```

**Step 4**

### Validate the CSR

Run this command in your terminal before submitting the CSR. It
prints the CSR contents as human-readable text directly in your
terminal.

```bash theme={null}
openssl req -in client_YOUR_ACQUIRER_ID.csr -noout -text
```

Check the output against the list below to confirm all fields are correct before proceeding.

* `Organisation (O)` matches your acquirer ID exactly.
* `Organisational Unit (OU)` matches your card acceptor ID exactly.
* `X509v3 Subject Alternative Name` shows a team mailbox, not an individual address.
* Public key algorithm shows RSA 4096-bit.
* Signature algorithm shows `sha256`.

**Step 5**

### Submit the CSR to Fexco

Send only the `.csr` file to Fexco for signing. Do not send the
private key.

> [!NOTE]
>
> The CSR submission channel is confirmed during onboarding. Contact
> your Fexco project manager for instructions on where to submit the
> file.

Once Fexco processes the CSR, they will return a signed client
certificate. If you do not receive the certificate within the expected
timeframe, contact your Fexco project manager or technical support
representative with the submission details.

## Security best practices

* **Never share your private key:** Only the `.csr` file is shared with Fexco.
* **Rotate certificates before they expire:** Request a new certificate
  before the current one expires to avoid service interruption.
* **Store private keys securely:** Use a Hardware Security Module (HSM)
  or a secure key store in production environments.

## Next steps

Once Fexco returns your signed certificate, you are ready to authenticate Rate Service Connect API requests.

* [JWT authentication (Rate Service Connect API)](https://docs.fexco.com/dcc/api-reference/authentication/jwt-pki.md): use your
  certificate to build and sign a JWT for each Rate Service Connect API request.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.