mTLS client certificates

The Payout server-to-server APIs are authenticated with an mTLS client certificate that you obtain from a Qualified Trust Service Provider (QTSP) and import into your Payout account. They currently cover:

• M2M Withdrawals: withdrawals through Payout API v2, with optional Verification of Payee. Requires a QWAC for the mTLS connection and a QSEAL to sign payment instructions.

A certificate you imported once can be used by every server-to-server API whose profile requirements it meets.

Certificate profiles

A standard eIDAS QWAC and QSEAL are enough: no PSD2-specific extensions are required, such as the QcStatement-PSD2 of ETSI TS 119 495 or PSP roles like PSP_AS, PSP_PI, PSP_AI and PSP_IC. Those are issued only to licensed payment service providers. M2M clients are typically merchants and other B2B companies, and they obtain plain qualified certificates from a supported QTSP.

Common requirements for all profiles:

• Issued by a QTSP on the EU Trusted List. Currently supported issuers: I.CA (První certifikační autorita) and Disig. To use a certificate from another QTSP on the list, contact [email protected] and we will add its CA to our trust store.
• Contains your organisation identifier (IČO / LEI / VAT) in the organizationIdentifier subject attribute.
• Key usage matches the certificate's role:
  • QWAC: digitalSignature + keyEncipherment
  • QSEAL: nonRepudiation
• Minimum key size: RSA 2048 or ECDSA P-256.

Generate the private keys yourself and send only the CSR to the QTSP.

Endpoints

Certificates are managed on the standard hosts, not on the mTLS hosts, because you import them before mTLS can work:

Setup

1. Obtain certificate(s) from a QTSP

Check in Certificate profiles which profiles you need, then send a CSR to the QTSP of your choice.

2. Obtain a bearer token

curl -X POST https://app.payout.one/api/v1/authorize \
  -H "Content-Type: application/json" \
  -d '{"client_id":"<CLIENT_ID>","client_secret":"<CLIENT_SECRET>"}'

Response:

{ "token": "...", "valid_for": 6000 }

3. Import your certificate(s)

Upload the PEM-encoded certificate. Send only the certificate, never the private key:

curl -X POST https://app.payout.one/api/v1/mtls/certificates \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "qwac",
    "pem": "-----BEGIN CERTIFICATE-----\n..."
  }'

For M2M Withdrawals, repeat for the QSEAL certificate with "type": "qseal".

The response has status 201 and the certificate starts as pending:

{
  "type": "qwac",
  "thumbprint": "49165a9f...",
  "status": "pending",
  "issuer_dn": "CN=...,O=...",
  "subject_dn": "C=SK,...,organizationIdentifier=NTRSK-12345678,CN=...",
  "subject_org_id": "NTRSK-12345678",
  "valid_from": "2025-06-09T06:23:06Z",
  "valid_until": "2026-06-09T06:23:06Z"
}

4. Wait for manual approval

Payout manually verifies that the imported certificates match the contractual data of your account. You can check the status at any time:

curl https://app.payout.one/api/v1/mtls/certificates/<thumbprint>/status \
  -H "Authorization: Bearer <TOKEN>"

After approval the status changes to approved and the certificate can be used. If Payout cannot approve it, the status changes to rejected.

5. Start calling the API

Once the certificate is approved, present it in the TLS handshake with the mTLS host of the API:

Lifecycle

Renewal

Before your certificate expires, obtain a new one from the QTSP and import it with POST /api/v1/mtls/certificates. The new certificate is approved separately and works in parallel with the old one until that one expires, so there is no downtime.

Removal by you

You can remove your certificate at any time:

curl -X DELETE https://app.payout.one/api/v1/mtls/certificates/<thumbprint> \
  -H "Authorization: Bearer <TOKEN>"

Rejection by Payout

Payout may also reject a certificate, for example when it has been compromised or the contractual relationship ends. A rejected certificate can no longer be used.

Compromise

If you suspect your private key has been compromised:

1. Revoke the certificate at the QTSP that issued it.
2. Remove it from Payout (DELETE).
3. Notify Payout at [email protected].
4. Generate a new key pair and obtain a fresh certificate.
5. Import the new certificate and wait for re-approval.

HTTP error codes