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

# FPS e-Cert Certificate Application and Setup Guide

> Guide for applying and configuring SSL certificates for FPS App-to-App integration, particularly for HSBC merchants.

<Info>
  This guide is required if you are an FPS merchant using App-to-App payment, especially for HSBC merchants.
</Info>

***

## When Do You Need an e-Cert?

If you are integrating FPS App-to-App using a **merchant-specific Universal Link**, an e-Cert (server certificate) is required to secure the domain.

This applies to banks such as **HSBC**, which operate in direct integration mode and require domain validation and organisation name matching.

***

## Important Notes for FPS App-to-App Certificate

<Warning>
  The **merchant organisation name** (subject field in the X.509 certificate) **must exactly match** the payee name registered in the FPS Addressing Service.

  This requirement comes from FPS Technical Specification 6.9.2.

  Payment apps MUST validate that the organisation name in the merchant certificate matches the payee name returned from the FPS addressing service.

  The **certificate domain name** is assigned and configured by QFPay based on the integration context. Merchants do not select this domain themselves.

  Each **distinct domain** requires a **separate e-Cert application** (e.g. `fps.payment.example-shop.com`), which incurs additional cost and processing time.

  Merchants must also add the following **CNAME record** in their DNS configuration:

  ```
  Host: fps.merchant.com
  Type: CNAME
  Value: hk.qfapi.com
  ```
</Warning>

***

## FPS e-Cert Application Overview

| Step | Description                                                                       |
| ---- | --------------------------------------------------------------------------------- |
| 1    | Complete application form **CPos 798F**                                           |
| 2    | Submit the form in person at any Hongkong Post office                             |
| 3    | Present authorised ID and pay the subscription fee                                |
| 4    | Receive PIN envelope for CSR submission                                           |
| 5    | Generate and submit CSR via the designated e-Cert portal                          |
| 6    | Wait \~10 working days for approval and domain/email validation                   |
| 7    | Upon approval, submit CSR to issue certificate                                    |
| 8    | Download and install the e-Cert on your HTTPS server                              |
| 9    | Send **certificate and private key** to QFPay Technical Support for configuration |

***

## CSR Generation Requirements

Before submitting the certificate application, generate a **Certificate Signing Request (CSR)**.

Example OpenSSL command:

```
openssl req -new -SHA256 -newkey rsa:2048 -nodes \
-keyout <key_name>.key \
-out <cert_name>.csr \
-subj "/C=HK/ST=HongKong/L=HongKong/O=<Your_Organisation_Name>/OU=/CN=<your_domain>"
```

### Parameter Breakdown

| Field              | Description                                  |
| ------------------ | -------------------------------------------- |
| `-newkey rsa:2048` | Generate a new RSA key pair (2048-bit)       |
| `-nodes`           | Skip password encryption for the private key |
| `-keyout`          | Path to save the private key                 |
| `-out`             | Path to save the CSR                         |
| `-subj`            | Subject fields included in the certificate   |

**Notes**

* `O=` (organisation name) **must exactly match** the FPS payee name registered in the FPS Addressing Service.
* `CN=` (common name) is the domain name configured by QFPay.
* Leave `OU=` empty if no department is specified.

***

## Documents Required

* Completed CPos Form 798F
* Business Registration (BR) copy
* Company Incorporation (CI) copy
* Domain ownership proof (invoice, DNS screenshot, or domain email confirmation)

***

## Post-Issuance Responsibilities

<Info>
  Hongkong Post will send **expiration reminders** to the registered email **30 days and 14 days before expiry**.\
  Merchants are responsible for timely renewal and notifying QFPay.
</Info>

After certificate issuance:

* Send the certificate (`.cer` / `.crt`) and private key (`.key`) to QFPay Technical Support.
* QFPay will complete backend setup for the FPS payment endpoint.

***

## FPS Specification Reference

**Section 6.9.2 — Certificate Validation Logic**

The payment app (e.g. HSBC app) validates that the **Organisation Name (O)** in the X.509 certificate matches the FPS payee name.

The comparison is:

* Case-insensitive
* Whitespace-insensitive

If the values do not match, the payment will be rejected.

***

## Resources

* [e-Cert Form 798F (Apply for e-Cert Server)](https://www.ecert.gov.hk/product/ecert/apply/certapply.html#t4)
* [e-Cert Application Flowchart (PDF)](https://www.ecert.gov.hk/product/ecert/apply/img/e-Cert_\(S\)_Flow.pdf)

***