PCI DSS integration Beta

Treezor complies with the Payment Card Industry Data Security Standard (PCI DSS) to secure sensitive data (e.g., PAN, PIN, CVV) of payment cards.

Configuration – Migrating to PCI DSS services

If you have been working with Treezor since before PCI DSS became available, you must migrate to these new services. Please contact Treezor for more information.

The implementation of PCI DSS at Treezor relies on the Mutual Transport Layer Security (mTLS) protocol, which guarantees mutual authentication and encrypted communication, and prevents interception or identity theft between systems. This protocol applies to all endpoints.

In addition, all your requests transit through the following URL:

Sandbox – https://<your_company_name>.preprod.secure.treezor.co
Production – https://<your_company_name>.secure.treezor.co

This article takes you through the steps to implement mTLS, focusing on your Sandbox environment. Please bear in mind you'll have to repeat the same procedure for your Production environment.

Setting up your certificates

To use mTLS, you first need to send a CSR (Certificate Signing Request) to Treezor for your mTLS certificate (to set up, with your private key, the TLS negotiation).

In return, Treezor provides the signed certificate for you to configure your client and authenticate your requests.

You need to provide a certificate for each of your Treezor environments (Sandbox and Production), which means you’ll have to send 2 CSR files.

1. Create your RSA keys sensitive data

You need a private key to create your certificate signing request (CSR).

These keys must have the following attributes:

Type: RSA
Format: PKCS1
Size: 2048

Here is the command to run for your Sandbox, please keep in mind you'll have to do the same for your Production environment.

Linux / macOS

openssl genrsa -out <your.company.name>_privatekey_mtls.pem 2048

Security – Protect your private key

Don’t share your private keys with anyone and make sure they are securely stored (e.g., secure vault, key management system).

2. Create your CSR files

The Certificate Signing Request (CSR) is the request you send to a Certificate Authority (or CA, in this case, Treezor) to apply for a digital identity certificate. The CSR includes the public key and additional information, such as the entity requesting the certificate's common name (CN).

Here is the command to run:

Linux / macOS

openssl req -new -key <your.company.name>_privatekey_mtls.pem -out <your.company.name>_csr_mtls.pem

Then use the information in the table below to complete the CSR information.

Information	Description
Country	The two-letter country code representing the country where the organization is located.
State / Province	The state or province where the organization is located (e.g., Brittany, IdF).
Locality	The locality or city where the organization is located.
Organization Name	The legal name of the organization to which the entity belongs. This could be the company, department, or other organizational unit.
Organizational Unit	(optional) The specific unit within the organization. For example, "IT Department" or "Marketing".
Common Name	Usually, the fully qualified domain name (FQDN) for which the certificate is being requested. For example, if the certificate is for a website, the CN might be the domain name (e.g., https://yourcompany.com).
Email	The email address of the organization.

3. Ask Treezor to generate your certificates

CSR files and certificates aren't considered sensitive data. This is why you can exchange them by email.

Send your CSR files to your Treezor Technical Account Manager.
Treezor will send you back the signed certificates.

Security – Don't send your private keys, only the CSR files

If you were to send us your private key, you would have to generate new ones and start the process from scratch.

You now have the necessary certificates for mTLS authentication.

Reading – More information available on mTLS

Learn more about certificates, including when to renew or revoke them.

Make your requests

Now that you have your certificates, you can make PCI DSS-specific requests (see PCI DSS API Reference).

GolangPHP

package main

import (
	"crypto/tls"
	_ "embed"
	"fmt"
	"io"
	"net/http"
)

var (
	//go:embed <your.company.name>_csr_mtls.pem
	pemCertificateMTLS []byte

	//go:embed <your.company.name>_privatekey_mtls.pem
	pemPrivateKeyMTLS []byte
)

func GenerateRequest(httpMethod, requestURL string, queryParams map[string]string,
	jwtToken, scaProof string, body io.Reader) (*http.Request, error) {
	if jwtToken == "" {
		return nil, fmt.Errorf("missing JWT Token")
	}

	request, err := http.NewRequest(httpMethod, requestURL, body)
	if err != nil {
		return nil, fmt.Errorf("failed to create request: %w", err)
	}

	request.Header["Authorization"] = []string{"Bearer " + jwtToken}

	if scaProof != "" {
		request.Header["X-Trz-SCA"] = []string{scaProof}
	}

	return request, nil
}

// SendUsingMTLS sends the given HTTP request using mTLS protocol.
func SendUsingMTLS(request *http.Request) (*http.Response, error) {
	clientCertificate, err := tls.X509KeyPair(pemCertificateMTLS, pemPrivateKeyMTLS)
	if err != nil {
		return nil, fmt.Errorf("failed to load x509 key pair: %w", err)
	}

	httpClient := &http.Client{
		Transport: &http.Transport{
			TLSClientConfig: &tls.Config{
				Certificates: []tls.Certificate{clientCertificate},
			},
		},
	}

	return httpClient.Do(request)
}

php

<?php

use GuzzleHttp\Client;
use GuzzleHttp\Psr7\Request;

const MTLS_CERT_FILE = '<your.company.name>_csr_mtls.pem';
const MTLS_KEY_FILE = '<your.company.name>_privatekey_mtls.pem';

function generateRequest(string $httpVerb, string $url, array $queryParams, string $jwtToken, string $scaProof, string $body): Request
{
    if ($jwtToken === '') {
        throw new RuntimeException('missing JWT Token');
    }

    $headers = [
        'X-Trz-SCA' => $scaProof,
        'Authorization' => "Bearer $jwtToken",
        'Content-Type' => 'application/json',
    ];

    return new Request($httpVerb, $url . '?' . http_build_query($queryParams), $headers, $body);
}

/**
 * @throws \Psr\Http\Client\ClientExceptionInterface
 */
function sendUsingMTLS(Request $request)
{
    $client = new Client([
        GuzzleHttp\RequestOptions::CERT => [MTLS_CERT_FILE, ''],
        GuzzleHttp\RequestOptions::SSL_KEY => [MTLS_KEY_FILE, ''],
    ]);

    return $client->sendRequest($request);
}

PCI DSS Endpoints

The PCI DSS endpoints are the ones for which you need to add the certificate. They can only be used for cards created or migrated to PCI DSS services, and replace their equivalent in the main API Reference.

Please keep in mind that all your requests transit through the following URL:

Sandbox – https://<your_company_name>.preprod.secure.treezor.co
Production – https://<your_company_name>.secure.treezor.co

PCI DSS endpoint	Replaced endpoints
`/cards` Create a Card. Use the `medium` field to create Virtual or Physical cards.	Create Virtual Card Create Physical Card
`/cards/{cardId}/tokenize` Tokenize the card.
`/cards/{cardId}/cardImage` Rebuild the card image when changing card design, company name, or when retrieving the image results in a 404. Not necessary when initially creating a Virtual Card.	Regenerate Card
`/cards/{cardId}/renew` Renew the card manually.	Renew Card
`/cards/{cardId}/replace` Replace a physical card with the same card data.
`/cards/{cardId}/cardImage` Download the card encrypted image. Requires encryption, see Display sensitive data article.	Retrieve Image
`/cards/{cardId}/pan` Retrieve the card PAN & CVV. Use the `withCVV` field to get the encrypted CVV too. Requires encryption, see Display sensitive data article.
`/cards/{cardId}/pin` Retrieve the PIN code of the card. Requires encryption, see Display sensitive data article.
`/cards/{cardId}/assignUser` Assign the card to another user.	Reassign Card (partial replacement)
`/cards/{cardId}/changePIN` Change the PIN code knowing the current one.	Change PIN
`/cards/{cardId}/setPIN` Overwrite the PIN code.	Set PIN
`/cards/{cardId}/inappcryptogram/mastercard/apple-pay` Generate an Apple Pay cryptogram for Mastercard digitization process.	Request issuerInitiatedDigitizationData
`/cards/{cardId}/inappcryptogram/mastercard/google-pay` Generate a Google Pay cryptogram for Mastercard digitization process.	Request issuerInitiatedDigitizationData
`/cards/{cardId}/inappcryptogram/visa/apple-pay` Generate an Apple Pay cryptogram for Visa digitization process.
`/cards/{cardId}/inappcryptogram/visa/google-pay` Generate a Google Pay cryptogram for Visa digitization process.
`/inappcryptogram/{credentials}` Retrieve digitization cryptogram.
`/users` Create a user.	Create User

API – API Reference available

For a complete list of attributes for these endpoints, check the PCI DSS API Reference.

PCI DSS integration Beta ​

Setting up your certificates ​

1. Create your RSA keys sensitive data ​

2. Create your CSR files ​

3. Ask Treezor to generate your certificates ​

Make your requests ​

PCI DSS Endpoints ​