Use existing token

Our platform allows you to store your customers' credit card data permanently for 1‑click payments. By pre‑filling the Hosted Fields with the stored data, your customers' payment experience will become even smoother and improve your conversion rate.

As the token is already existing at the time of the transaction request, the payment flow is different:

• Step 1: Instruct our platform you want to use an existing token. To do so, modify the request CreateHostedFieldsSession by adding the property tokens. List all the identifiers for existing tokens for your customer:
  {"locale":"en-GB", "tokens": "Your_token"}
• Step 2 : Load the JavaScript library to checkout page.
• Step 3 : Initialise the Hosted Fields on your checkout page. As the card data will be pre-filled, only display the CVV. var config = { "sessionData": "apiResponse.sessionData", "logLevel": "debug", "style": { "input": { "color": "#000000", "font-family": "courier, monospace", "font-size": "14px" }, "input::placeholder": { "color": "#999999" } }, "fields": { "csc": { "id": "csc", "title": "Your card security code", "caption": "Your card security code", "placeholder": "123" } } }
• Step 4 : Populate the hostedFields instance with the token to be used:
  hostedFields.useToken(existingTokenId); Mind that the same session can be loaded multiple times on the same page.
  Make sure to call useToken on the right instance if you choose to load more than one token.
• Step 5 : Listen for validation events, submit and create the payment like in the regular flow.

Flows

Find a full transaction flow involving every party and (optional) steps in this overview:

1. Your customers go to your check-out page and finalise the purchase.
2. You send a CreateHostedFields session to our platform. Our platform returns the sdkUrl / hostedFieldsSessionId.
3. You load the sdkUrl library to initialise the Hosted Fields in the input fields on your checkout page.
4. Your customers enter their card details in the input fields and submit the card data to our platform.
5. Our platform tokenises the card data. 
6. You send a CreatePayment request to our to our platform using our Server-to-server integration method, including the mandatory 3-D Secure properties.
   6'(optional).We perform a fraud prevention check.
7. Our platform sends a response containing a merchantAction object, instructing you how to proceed. These scenarios are possible:
   a) 3-D Secure frictionless flow (merchantAction.actionType=null). The flow continues at step 13).
   b) 3-D Secure challenge flow (merchantAction.actionType="REDIRECT"). The flow continues at step 8).
   c) No 3-D Secure authentication (merchantAction.actionType=null). The flow continues at step 13).
8. You redirect the customer to her/his issuing bank for 3-D Secure authentication. The customer identifies herself/himself.
9. Our platform receives the 3-D Secure authentication result from the issuer. Based on the result, two scenarios are possible:
   a) If the identification was unsuccessful, we redirect your customers to your returnUrl, ending the flow. You request/show the transaction result as described in step 12.
   b) If the identification was successful, the flow continues at step 10.
10. We process the transaction and receive the result from the acquirer.
11. We redirect your customer to your returnUrl.
12. You request the transaction result from our platform and show it on your returnUrl/in your webshop.
13. If the transaction was successful, you can deliver the goods/services.

What is PCI DSS Compliance? 

PCI DSS is a security standard designed to protect cardholder data. Compliance prevents fraud, maintains customer trust, and avoids penalties. 

To become PCI DSS compliant, merchants must follow specific steps to ensure their payment data security and adherence to standards: 

1. Understand PCI DSS Requirements: Familiarize yourself with the PCI DSS standards that protect cardholder data and ensure secure payment transactions.
2. Consultation and Training: Utilize Worldline services to gain insights into the criteria you need to meet.
3. Use PCI DSS Validated Solutions: Implement validated third-party solutions for payment data processing.
4. Implement Security Standards: Process card data in accordance with security standards and ensure your equipment and systems meet these requirements.
5. Identify the Relevant SAQ: Complete the appropriate Self-Assessment Questionnaire (SAQ) based on your card payment processing methodology (see SAQ types on the first slide).
6. Compliance Reporting: Depending on your merchant level (from 1 to 4), regularly submit compliance reports through the respective methods like audits, ASV scans, or SAQs.
7. Use Worldline Portals: Leverage the Worldline's web-based, self-service portal that offers tools to validate PCI DSS compliance and provides the needed resources for a comprehensive compliance journey.
8. Contractual Obligations: Remember that compliance obligations are part of the general conditions for merchants using Worldline services. 

By following these steps, merchants can ensure they meet PCI DSS requirements, thereby securing payment data and complying with regulatory standards. 

Maintaining Compliance 

Regularly update your security measures, review policies, and keep staff informed on best practices. We are here to assist with expert guidance. Contact us for more information. 

Das SDK hat noch viel mehr zu bieten. Sehen Sie sich die folgenden Möglichkeiten an, denn sie helfen Ihnen beim Entwickeln der perfekten Lösung.

• Verfügbare Zahlungsarten abrufen
• Idempotente Anfragen senden
• Protokollierung verwenden
• Verbindungs-Pooling
• Kommunikation anpassen
• Webhooks

Verfügbare Zahlungsarten abrufen

Bevor Sie den eigentlichen Zahlungsvorgang einleiten, sollten Sie eine GetPaymentProducts-Anfrage an unsere Plattform senden. Die Antwort enthält eine Liste der in Ihrer PSPID verfügbaren Zahlungsarten. Je nach den Vorlieben Ihrer Kunden können Sie eine Auswahl auf unserer Hosted Checkout Page oder in Ihrer eigenen Webshop-Umgebung mit nachfolgenden CreatePayment-Anfragen anbieten.

/* 
 *…. Initialisierung....
 */

$merchantClient = $client->merchant($merchantId);

// Anfrage zum Abruf aller aktiven Zahlungsmethoden in Ihrer PSPID erstellen
$queryParams = new GetPaymentProductsParams();

// Beispiel-Parameter
$queryParams->setCountryCode("BE");
$queryParams->setCurrencyCode("EUR");

// Anfrage senden und Antwort abrufen
$paymentProductsResponse = $merchantClient
    ->products()
    ->getPaymentProducts($queryParams);

Idempotente Anfragen senden

Eines der wichtigsten Merkmale der REST-API ist ihre Fähigkeit, versehentlich doppelt gesendete Anfragen (z. B. Zahlungsanfragen) zu erkennen und zu verhindern. Mit dem SDK können Sie sehr einfach sicherstellen, dass Sie nur einmalige (idempotente) Anfragen an unsere Plattform senden.

Dazu verwenden Sie das zusätzliche Argument CallContext und setzen Sie seine Eigenschaft $idempotenceKey mit dem Aufruf von setIdempotenceKey() für das zuvor erstellte Objekt, und dann rufen Sie die API-Funktion CreatePayment auf. Das SDK sendet einen X-GCS-Idempotence-Key-Header mit dem idempotence-Schlüssel als Wert.

Wenn Sie auf diese Weise Anfragen an unsere Plattform senden, überprüfen wir Folgendes:

• Wenn Sie eine weitere Anfrage mit demselben Idempotence-Schlüssel senden, enthält die Antwort einen X-GCS-Idempotence-Request-Timestamp-Header. Das SDK setzt die Eigenschaft $idempotenceRequestTimestamp des ArgumentsCallContext
• Wenn die erste Anfrage noch nicht abgeschlossen ist, gibt die RESTful Server API einen Statuscode 409 zurück. Dann wirft das SDK eine IdempotenceException mit dem ursprünglichen Idempotenzschlüssel und dem Zeitstempel der idempotenten Anfrage

/* 
 *…. Initialisierung....
 */

$merchantClient = $client->merchant($merchantId);

$createPaymentRequest = new CreatePaymentRequest();

$idempotenceKey = "YourKeyForThePayment";
 
$callContext = new CallContext();
$callContext->setIdempotenceKey($idempotenceKey);

try {
    $createPaymentResponse = $merchantClient
        ->payments()
        ->createPayment(
            $createPaymentRequest, 
            $callContext
        );
} catch (IdempotenceException $e) {
    // Eine Anfrage mit demselben $idempotenceKey läuft noch, nach einer kurzen Pause noch einmal versuchen
    // $e->getIdempotenceRequestTimestamp() enthält den Wert des
    // Headers X-GCS-Idempotence-Request-Timestamp
} finally {
    $idempotenceRequestTimestamp = 
        $callContext->getIdempotenceRequestTimestamp();
    // $idempotenceRequestTimestamp enthält den Wert des
    // Headers X-GCS-Idempotence-Request-Timestamp
    // wenn $idempotenceRequestTimestamp nicht leer ist, war dies nicht die erste Anfrage
}

Protokollierung verwenden

Das SDK unterstützt die Protokollierung von Anfragen, Antworten und Exceptions. Diese Protokolle können hilfreich bei der Fehlersuche oder der Nachverfolgung einzelner Schritte im Zahlungsablauf sein.
Das SDK bietet zwei Implementierungen der Protokollierungsfunktion:

• SplFileObjectLogger (durch Verwendung von SplFileObject)
• ResourceLogger

Die Protokollierung können Sie aktivieren/deaktivieren durch Aufruf von:

/* 
 *…. Initialisierung....
 */

$client = new Client($communicator);

// Sie können einen Pointer zu der Datei eingeben, in der Sie 
// Daten anstelle von STDOUT speichern möchten
$logger = new ResourceLogger(STDOUT); 
$client->enableLogging($logger); 
//... Aufrufe ausführen 
$client->disableLogging();

Verbindungs-Pooling

Ihre Netzwerkressourcen können Sie verwalten, indem Sie die Zahl der möglichen Verbindungen begrenzen, die das SDK aufbaut und aufrechterhält. Client-Instanzen, die wie im Kapitel SDK initialisieren beschrieben erzeugt wurden, haben ihren eigenen Verbindungspool. Mit demselben Communicator-Objekt erzeugte Client-Instanzen teilen sich einen Verbindungspool.

Wenn Sie mehrere Client-Instanzen verwenden, die sich einen einzigen Verbindungspool teilen, müssen Sie die folgenden Schritte ausführen:

1. Einen gemeinsamen Communicator erzeugen
2. Client-Instanzen mit diesem Communicator erzeugen

/* 
 *…. Initialisierung....
 */

// CommunicatorConfiguration-Instanz 
// mit richtigen Einstellungen erzeugen
$sharedCommunicatorConfiguration = 
new CommunicatorConfiguration(
    $apiKey,
    $apiSecret,
    $apiEndpoint,
    $integrator,
    $proxyConfiguration
);
 
$connection = new DefaultConnection();

// Communicator-Instanz
$communicator = new Communicator(
$connection, 
$sharedCommunicatorConfiguration
);
 
$client1 = new Client($communicator);
$client2 = new Client($communicator);

Kommunikation anpassen

Die Client-Instanzen kommunizieren über eine Communicator-Instanz mit unserer Plattform. Der Communicator hingegen verwendet Connection für die eigentlichen HTTP-Anfragen, und ConnectionResponse zum Speichern der HTTP-Antwort.

Connection und ConnectionResponse sind Schnittstellen. Das SDK bietet eine Standardimplementierung dieser Schnittstellen mit den Klassen DefaultConnection und DefaultConnectionResponse.

You can provide your own implementation of the interface of Connection to use in Communicator object as for example YourConnection class.

/*
 *…. Initialisation....
 */

$communicatorConfiguration = new CommunicatorConfiguration(
    $apiKey,
    $apiSecret,
    $apiEndpoint,
    $integrator,
    $proxyConfiguration
);

// Use you own implementation of the Connection interface
$connection = new YourConnection();

// Authenticator instance
$authenticator = new V1HmacAuthenticator($communicatorConfiguration);

// Communicator instance
$communicator = new Communicator(
    $communicatorConfiguration,
    $authenticator,
    $connection
);

Webhooks

The part of the SDK that handles the webhooks support is called the webhooks helper. It transparently handles both validation of signatures against the event bodies sent by the webhooks system (including finding the secret key for key IDs - not to be confused with the API Key and API Secret), and unmarshalling of these bodies to objects. This allows you to focus on the essentials, without going through all the additional information and extracting the desired ones by yourself. To learn more about webhooks, read our dedicated guide. 

Provide secret keys

Configure the "WebhooksKey" / "WebhooksKeySecret" and your server webhooks endpoints in the Merchant Portal:

$keyId = "WebhooksKey";
$secretKey = "WebhooksKeySecret";

Secret keys are provided using a function that takes two arguments:

• The key ID to return the secret key for.
• A callback function that either takes an error as its first argument, or the secret key for the given key ID as its second argument (in which case the first argument must be null).

The SDK provides one implementation for this method: InMemorySecretKeyStore::getSecretKey($keyId). This will retrieve secret keys from an in-memory key store for proper $keyId.

Keys can be added or removed using the following methods:

• InMemorySecretKeyStore::storeSecretKey($keyId, $secretKey) to store a secret key for a key ID.
• InMemorySecretKeyStore::removeSecretKey($keyId) to remove the stored secret key for a key ID.
• InMemorySecretKeyStore::clear() to remove all stored secret keys.

If more advanced storage is required, e.g. using a database or file system, we recommend writing your own implementation.

Initialise webhooks helper

Include and initialise the webhooks helper as follows:

$keyId = 'dummy-key-id';
$secretKey = 'dummy-secret-key’';
$secretKeys = [
    $keyId => $secretKey
];
$secretKeyStore = new InMemorySecretKeyStore($secretKeys);
// At this moment $secretKeys are stored because they are given to constructor
// but you can set empty array of $secretKeys and after that you can
// manage InMemorySecretKeyStore functions as mentioned above
// or even you can extend InMemorySecretKeyStore class to
// implement your own methods to manage $secretKeys
$helper = new WebhooksHelper($secretKeyStore);

Use webhooks helper

From an entry point that you have created on your own, call the unmarshal method of the webhooks helper. It takes the following arguments:

• The body, as a string or Buffer. This should be the raw body as received from the webhooks system.
• An object containing the request headers as received from the webhooks system. The keys should be the header names.

// Initialisation
$bodyOfRequest = 'JSON_Body_Of_The_Request';

// Retrieve the headers from the Webhook message, depends on your implementation.
$webhookHeaders = $request->getHeaders();

// Transform the received headers
$requestHeaders = [];
foreach ($webhookHeaders as $webhookHeader) {
    $requestHeaders[$webhookHeader->getName()] = $webhookHeader->getValue();
}

try {
    $webhookEvent = $helper->unmarshal($bodyOfRequest, $requestHeaders);
} catch (SignatureValidationException $e) {
    // Your code to handle errors
}

Warning about support