Appearance
Are you an LLM? You can read better optimized documentation at /guide/cards/pci-dss.md for this page in Markdown format
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.
openssl genrsa -out <your.company.name>_privatekey_mtls.pem 2048
1
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:
openssl req -new -key <your.company.name>_privatekey_mtls.pem -out <your.company.name>_csr_mtls.pem
1
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). |
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).
go
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)
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
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);
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
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}/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.