Default setup
The default authentication method while using the product suite of Ping Payments is two headers:
- tenant_id
- x-api-secret
The tenant_id is your personal account id at Ping Payments.
The x-api-secret is your secret key for accessing your tenant.
mTLS
The Ping Paymentsᵀᴹ API allows for increased security through the use of Mutual TLS (mTLS) authentication.
With mTLS authentication, the Ping Payments API will enforce certificate-based client authentication in combination with your unique tenant_id. Your certificate is connected to your tenant ID, and will only work for your specific tenant.
You need a certificate signed by Ping Payments to use mTLS with the Ping payments API.
This feature is opt-in.
Ping Payments recommend that security conscious customers consider using mTLS
mTLS verifies that two parties connected over a network are who they are. This verification is performed both by authenticating the private key of each party, and by checking the information in their respective TLS certificates.
mTLS Certficate requirements
- Public key: use the elliptic Curve NIST P-256 Algorithm
- Hash algorithm: use SHA2-256
- CSR: use PEM encoding
- CSR: your Common Name field should contain your tenant ID
Here's an example of the commands required to generate a working private key and CSR using OpenSSL:
> openssl ecparam -name prime256v1 -genkey -noout -out {tenant_id}.key.pem
> openssl req -new -sha256 -key {tenant_id}.key.pem -out {tenant_id}.csr.pem -subj "/CN={tenant_id}"
Keep your private key secure!
This key will be used to establish secure connections with the Ping Payments API, and should never be accessible for unauthorized individuals.
Send the CSR file you've just generated to your customer liaison at Ping Payments, and request to have mTLS enabled for your Tenant using this CSR file.
Expect to wait a few business days before you receive a signed mTLS client certificate, valid for 13 months. You can generate a new valid CSR, and repeat the signing process at any point you deem necessary. Ping Payments may also contact you about renewing your certificate when it is about to expire.
Once your tenant has been enabled for mTLS and you've received your certificate, you are ready to use mTLS authentication.
The Certificate Authority (CA) chain Ping Payments uses for the client certificate does not need to be explicitly trusted by the client, since it is not the same CA chain as the one used for the server certificate. The server certificate is signed by a public CA.
The Ping Payments API will permit that requests using both a certificate about to expire and a new certificate are used at the same time. This overlap period allows for a smooth transition over to a new certificate and private key combination without downtime.
If you wish to revoke a certificate before it expires you may contact your Ping Payments customer liaison with a copy of the certificate file, information about when the certificate should be revoked- You should also include a new CSR to be signed in its place. The process of revoking your old certificate may take a few business days.
IP-whitelisting
We also provide the possibility to white-list your back-end so that your x-api-secret and certificate only works for that particular setup. This is part of your onboarding journey at Ping Payments.