Certificate handling

Secure Sockets Layer (SSL) certificates are a security protocol that, when implemented, establishes a secure, encrypted connection between your point-of-sale (POS) system and the payment terminal in order for them to talk to each other.

Tip

Although it is not a requirement to implement an SSL certificate in order to use the Payment Terminal Application, SSL certificate implementation is an important security measure that provides protection for sensitive customer data.

This guide provides information on how your POS system handles certificates, specifically focusing on generating Certificate Signing Requests (CSRs), importing certificates, and installing trust certificates to the Payment Terminal Application. This ensures that the connection between your POS system and the payment terminal is protected against unauthorized access and data breaches.

Generate a Certificate Signing Request (CSR)

The following table contains the request fields used by the POS system to generate a certificate signing request (CSR) and send it to the Payment Terminal Application.

Generate CSR request fields
Parameter	Required	Data type	Value	Description
operation	R	String	GenerateCsr	The proxy app generates a new public and private key and uses the keys to generate a CSR (Certificate Signing Request).
commonName	R	String	Ex: "www.example.com"	The fully-qualified domain name (FQDN) of the device.
subjectAltNames	O	Array	[ { "type": "dns", "value": "www. example.com" }, { "type": "ip", "value": "192.168.1.1" }	The "SAN" or Subject Alternative Name(s) is an optional parameter that can be passed in with additional domains and/or IP addresses. This allows for a single certificate to be used to work with and secure multiple domains and/or subdomains.
organization	O	String	Ex: "ABC Corp"	This field specifies the legal name of the organization that owns the certificate. It helps verify the identity of the entity requesting the certificate and ensures that the certificate is issued to a legitimate organization.
organizational Unit	O	String	Ex: "ABC Store"	This field is used to specify a division or department within the organization. It can help further identify the specific part of the organization that is responsible for the certificate.
country	O	String	Ex: "US"	Country code where the POS is located
state	O	String	Ex: "FL"	State/Providence code where the POS is located
locality	O	String	Ex: "Tampa"	City where the POS is located
keyUse	R	String	Ex: "replace"	The 'keyuse' parameter defines the context in which the signed key will be used. 'replace': Intended to replace the current WSS certificate. 'rotate': Intended as a subsequent use certificate for when the current WSS certificate expires. Default: ‘replace’

The following table contains the response fields for generating a CSR.

Generate CSR response fields
Parameter	Data type	Value	Potential responses
operation	String	GenerateCsr	Same as request
commonName	String	Ex: "www.example.com"	The fully-qualified domain name (FQDN) of the device.
result	Int	Ex: 0	0: Generate CSR Success. 1: Error generating CSR 3: Invalid request, i.e. field missing. 5: Busy. CSR generation in progress.
csr	String	Ex: ---- BEGIN CERTIFICATE REQUEST----- Base64 text ---- END CERTIFICATE REQUEST-----	This is the data to be put in the device.csr file, the device.csr file will then be signed by your CA (Certificate Authority) and output a device cert for your specific device.

Sample request:

Json

{
    "operation": "GenerateCsr",
    "commonName": "www.example.com",
    "organization": "JPMC",
    "organizationalUnit": "omniTest",
    "country": "US",
    "state": "FL",
    "locality": "Tampa",
    "subjectAltNames": [
        {
            "type": "dns",
            "value": "www2.example.com"
        },
        {
            "type": "ip",
            "value": "192.168.1.1"
        }
    ],
    "keyUse": "replace"
}

Sample response:

Json

{
    "operation": "GenerateCsr",
    "commonName": "www.example.com",
    "result": 0,
    "csr": "-----BEGIN CERTIFICATE REQUEST-----Base64 text-----END CERTIFICATE REQUEST-----"
}

Import a certificate

The following table contains the request fields used by the POS system to import a certificate to the Payment Terminal Application.

Attention

Encode special characters in the CSR or certificate, such as \n \r, using unicode format \u000A or with double back slash \\n \\r.

Import a certificate request fields
Parameter	Required	Data type	Value	Description
operation	R	String	ImportCertifi cate	The operation name
commonName	R	String	Ex: "www. example. com"	The fully-qualified domain name (FQDN) of the device.
alias	O	String	Ex: "SN1234567 890"	The alias acts as an identifier, allowing you to reference and manage the specific certificate and its private key within the keystore.
certificate	R	String	Ex: "----- BEGIN CERTIFICA TE----- Encoded Base64 text ---- END CERTIFICA TE---- "	CA Issued Certificate in Base64-encoded PEM (Privacy Enhanced Mail) format. The certificate starts with ----- BEGIN CERTIFICATE----- and ends with -----END CERTIFICATE--- , which is the standard PEM format. Between the header and footer the Base64-encoded data.
keyUse	R	String	Ex: "replace"	The 'keyuse' parameter defines the context in which the signed key will be used. 'replace': Intended to replace the current WSS certificate. 'rotate': Intended as a subsequent use certificate for when the current WSS certificate expires. Default: ‘replace’

The following table contains the response fields for importing a certificate.

Import a certificate response fields
Parameter	Data type	Value	Potential responses
operation	String	ImportCertificate	The operation name
alias	String	Ex: "SN1234567890"	Ex: "SN1234567890"
result	Int	Ex: 0	0: Store certificate success. 1: Error storing certificate in keystore. 3: Invalid request, i.e. field missing. 5: Busy. Certificate store in progress.

Sample request:

Json

{
  "operation": "ImportCertificate",
  "commonName": "www.example.com",
  "certificate": "-----BEGIN CERTIFICATE-----Encoded Base64 text-----END CERTIFICATE",
  "keyUse": "replace"
}

Sample response:

Json

{
  "operation": "ImportCertificate",
  "alias": "SN1234567890",
  "result": 0
}

Install a trust certificate

The following table contains the request fields used by the POS system to install a trust certificate to the Payment Terminal Application.

Install a certificate request fields
Parameter	Required	Data type	Value	Description
operation	R	String	InstallTrustC ertificate	This installs the root CA file to the truststore
alias	R	String	Ex: "deviceTrust Cert"	The alias given to this trust certificate. Should be unique.
certificate	R	String	Ex: "----- BEGIN CERTIFICATE----- Encoded Base64 text ---- END CERTIFICATE---- "	CA Issued Certificate in Base64-encoded PEM (Privacy Enhanced Mail) format. The certificate starts with ----- BEGIN CERTIFICATE----- and ends with -----END CERTIFICATE--- , which is the standard PEM format. Between the header and footer the Base64-encoded data.

The following table contains the response fields for installing a trust certificate.

Install a certificate response fields
Parameter	Data type	Value	Potential responses
operation	String	InstallTrustCertificate	The operation name
alias	String	Ex: "deviceTrustCert"	The alias given to this trust certificate. Should be unique.
result	Int	Ex: 0	0: Install certificate success. 1: Error storing certificate in key store. 3: Invalid request, i.e. field missing. 5: Busy. Certificate

Sample request:

Json

{
  "operation": "InstallTrustCertificate",
  "alias": "deviceTrustCert",
  "certificate": "-----BEGIN CERTIFICATE-----Encoded Base64 text-----END CERTIFICATE"
}

Sample response:

Json

{
  "operation": "InstallTrustCertificate",
  "alias": "deviceTrustCert",
  "result": 0
}