Worldline | Detokenization

This is an advanced feature reserved for specific use cases.
If you are interested, contact us to check your eligibility for this feature.

Our Detokenization service allows you to retrieve Primary Account Numbers (PAN) for any COF token or transaction processed via our platform.
Retrieving and sharing PANs can help you extend your business and payment infrastructure by

Importing card data from other payment service providers when moving your business to Worldline.
Working in parallel with different payment service providers at once.
Implementing external services that require card data (i.e. for fraud prevention).

Detokenization is available for all credit card payment methods.
Mind that retrieving/storing card data brings in a very large number of the PCI requirements. This also applies to any third party with whom you share this data.

Onboarding

Activating Detokenization requires you to

Sign an addendum to your existing Worldline contract.
Provide a PCI DSS Attestation Of Compliance (AOC) on a yearly basis.
Nominate a person as a specific point of contact in your company who will be responsible for receiving, securing and processing related sensitive data.
Establish a process to inform us about possible difficulties when renewing the AOC.
Inform us within 48 hours about any security incident leading to a data breach of related sensitive data.

We are happy to get you started.

Integration

Using Detokenization requires ensuring the integrity of the sensitive data exchanged at any point. Therefore, we have defined a flow that honors this requirement:

Generate RSA Key Pair and CSR
Receive certificate from Worldline
Retrieve encrypted card data
Decrypt card data

1. Generate RSA Key Pair and CSR

To establish a secure connection between your server and platform, you need to set up an RSA key pair and a Certificate Signing Request (CSR).
Your request needs to include

Your company's name.
Name of the person acting as the specific point of contact in your company who will be responsible for receiving, securing and processing related sensitive data.
The person's e-mail address (to which the CSR is sent to in the subsequent step)

The public key resulting from setting up the RSA key pair/CSR will be used for decrypting the card data.

2. Receive certificate from Worldline

To create the actual certificate based on the CSR, send a POST request to our dedicated CreateCertificate endpoint:

{
     "csr": "-----BEGIN CERTIFICATE REQUEST-----
     MIICWjCCAUICAQAwFTETMBEGA1UEAwwKdGVzdC5sb2NhbDCCASIwDQYJKoZIhvcN...
     -----END CERTIFICATE REQUEST-----"
}

Property	Description
{merchantId}	Your account on our platform. Add it as a path parameter to the CreateCertificate endpoint Url.
csr	The CSR you have created in the previous step.

Upon successfully processing your request, our platform provides the certificateId and the signedCertificate itself.

Our platform will also send a confirmation e-mail to the address you have defined in the onboarding process.

The certificate is valid for 30 days. If you request a new certificate, the existing one will remain valid for another hour.

3. Retrieve encrypted PANs

With a valid certificate in place, you can retrieve PANs from our platform. We offer two ways for this:

token to PAN
payment.id to PAN

token to PAN

You can retrieve the PAN from previously created COF tokens. To do so, send a GET request to our dedicated Detokenize endpoint. Including the following path parameters in your request:

Property	Description
{merchantId}	Your account on our platform requesting the PANs. Must be identical to the one used in step 2.
tokens	Contains {aliasIds}={token} key/value pairs as separate variables for each COF token.

For security reasons, if one of the token is invalid, our platform will reject the full request and throw a 400 error. This includes tokens that

Do not exist (anymore).
Contain spelling errors.

payment.id to PAN

You can retrieve the PAN from previously processed transactions that have one of the following statuses:

Refer to our dedicated Statuses guide to learn more.

To do so, send a GET request to our dedicated Detokenize endpoint. Including the following path parameters in your request:

Property	Description
{merchantId}	Your account on our platform requesting the PANs. Must be identical to the one used in step 2.
payments	Contains {payments}={payment.id} key/value pairs as separate variables for each payment.id. A payment.id is a unique identifier for every transaction processed on our platform which is returned for every GetHostedCheckout/CreatePayment/GetPayment.

Upon successfully processing your request, our platform provides the encrypted PANs in a tokens array. For each instance, we provide the following data:

Property	Description
cardBrand	The card's scheme for this PAN.
cardExpiryDatecardHolderName	The card's expiry date and card holder name.
encryptedCardNumber	The encrypted PAN which you can decrypt using the CSR's public key.
schemeReferenceData	The card scheme's (cardBrand) unique identifier for each card, documenting its payment history for any purchase from any merchant.

4. Decrypt encryptedCardNumber

Use the private key generated in step 1 to decrypt the encryptedCardNumber for each tokens array instance.

Detokenization