worldline Direct
Sign up

We at Worldline are yearning to offer you the best online payments technology. If you are still working with our classic solution, you might want to switch to our new platform Direct. It offers state-of-the-art tools that will make your online business thrive:

Have a closer look at what is in for you and what you need to do to take advantage of Direct.

Our classic integration modes, payment methods and features will remain available until further notice.

Understand Direct advantages

Moving from our classical integration layer to Direct can be considered a paradigm shift. It does involve some efforts from your side, but they will be well rewarded. We will happily support you to ensure a smooth transition!

So why switch to Direct anyway? Although we will continue supporting the classic integration layer, Direct is the future-proof solution for your business and the key to a higher conversion rate:

On top of this, Direct eases your integration/maintenance effort:

  • Use SDKs conveniently wrapping our REST API, reducing the complexity of the payment flow, especially for rolling out 3-D Secure.
  • Install Plugins for all popular shopping carts.
  • Apply one way of authentication and free yourself from the hassle of SHA calculations, API users/passwords, IP address checks etc.
  • Delegate Back Office technical settings to our API and use the Merchant Portal as an intuitive user interface to manage your transactions.
  • Keep using your existing legacy resource like Aliases or acquirer connections for payment methods available on the Direct platform.

Are you up for it? Then have a look how to make the switch and how we will help you accomplish it!

Get account

Most of the PSPIDs are already enabled for Direct layer. To check this, login to your account and follow these steps:

  • Go to Configuration > Account > Your options. Make sure option "DIR (Merchant using Ingenico Direct integration)" is active in either "Available options" or "Default options" tab.
  • Go to Configuration > Payment methods. Check that at least one of our of our available payment methods is active. We will constantly add new ones – Keep an eye on our Release Notes for regular updates.
  • You have configured your API Key and API Secret in your account. Learn more in the "Build your Direct integration" chapter.

We are here for you if you need help getting your PSPID ready.

We recommend creating a completely new account for Direct to avoid any interference with your existing classic integration - this is a matter of a few minutes.

Choose integration mode

Once you have set up your PSPID, you are ready for the next step – choose your Direct integration mode.

So where do you start from here? To have the smoothest transition possible, choose the Direct integration mode matching your current classical integration mode. If you move to the equivalent solution (as defined in column "Direct integration mode"), this will also ensure that you can stick to your current PCI compliancy level.

This table will help you pick the right one. Follow the respective link to learn more about the integration mode, including payment flows and code samples:

Direct integration mode Classic integration mode counterpart
Hosted Checkout Page
Redirect your customers from your checkout page to our platform for entering sensitive payment data.
Hosted Payment Page
Hosted Tokenization Page
Include an iFrame payment form hosted on our save environment in your checkout page for entering sensitive payment data.
Flexcheckout
Server-to-server
Send credit card data directly from your server to our platform.
DirectLink
Mobile/Client Integration
Create your own app and
encrypt credit card data with our public key.
This mode is a Direct-specific
feature and a key reason to migrate if you develop your own mobile apps

Are you all set? Then let us explain how you can build your integration.

Build Direct integration

In comparison to the classic integration mode, Direct requires a different approach for your software developers to link your shop to our platform.

Being a REST API, Direct allows you to link your system to our platform in different ways:

  1. Software Development Kits (SDKs): Our SDKs conveniently wrap the REST API to allow developing your own webshop software in your favourite programming language.
    We distinguish between Server SDKs and Client SDKs wrapping the Server API and the Client API respectively.

    The Server SDKs include everything to process transactions via all our integration modes (Hosted Checkout Page / Hosted Tokenization Page / Server-to-server), but you will need a Client SDK for Mobile/Client Integration.

  2. Webshop plugins: Direct offers various plugins for the most popular webshop systems, with more to come. Keep an eye on our changelog for regular updates.

  3. The REST API as such: The Direct REST API is also accessible by directly sending requests to individual resources, freeing you from possible dependencies (i.e. updated SDKs/plugins). Keep the following in mind when choosing this option:
    a) The authentication mechanism is different from the one the SDKs implement. Read the dedicated chapter in our Authentication guide to learn how it works.
    b) Always target our latest API version to take advantage of the REST API’s full potential.

Now you have laid the basic fundament to work with Direct. Check out the following chapters to learn how to perform actions you are already doing with your classic integration, such as:

Parameter Mapping

To process transactions with Direct you need to provide certain information in your request. For the classic integration, you use a set of parameters for each integration mode. The most common parameters for each classic integration mode are:

Classic integration mode
Classic parameters

Hosted Payment Page

PSPID
ORDERID
CURRENCY
AMOUNT
LANGUAGE
SHASIGN
OPERATION

Flexcheckout

ACCOUNT.PSPID
ALIAS.ALIASID
ALIAS.ORDERID
ALIAS.STOREPERMANENTLY
CARD.PAYMENTMETHOD
LAYOUT.TEMPLATENAME
PARAMETERS.ACCEPTURL
PARAMETERS.EXCEPTIONURL
SHASIGNATURE.SHASIGN
CARD.BRAND
CARD.PAYMENTMETHOD
LAYOUT.LANGUAGE

DirectLink

PSPID
ORDERID
USERID
PSWD
AMOUNT
CURRENCY
CARDNO
ED
CN
SHASIGN
CVC
browserAcceptHeader
browserColorDepth
browserJavaEnabled
browserLanguage
browserScreenHeight
browserScreenWidth
browserTimeZone
browserUserAgent
ACCEPTURL
DECLINEURL
EXCEPTIONURL
LANGUAGE
FLAG3D
OPERATION

In Direct, these parameters translate to properties in JSON format. To help you re-create your classic integration for the new platform, we provide a mapping of these classic parameters with Direct properties. Check out API Reference for a full overview of available properties.

Classic parameter

Direct property

PSPID

N/A

PSPID routing is covered by the SDK initialisation/By replacing {merchantId} in the API resource. Learn more in our dedicated Authentication guide.

ORDERID

order.references.merchantReference

Not mandatory for Direct. If omitted, our platform will generate a random string.

CURRENCY amountOfMoney.currencyCode
AMOUNT

amountOfMoney.amount

LANGUAGE

hostedCheckoutSpecificInput.locale

Not mandatory for Direct. If omitted, our platform will take the language configured in your Back Office (Configuration > Account > Your administrative details > Language).

SHASIGN

N/A

Authentication is covered in the SDK initialisation/manual authentication for requests sent directly to our API. Learn more in our dedicated Authentication guide.

OPERATION cardPaymentMethodSpecificInput.authorizationMode
ACCOUNT.PSPID

N/A

PSPID routing is covered by the SDK initialisation/By replacing {merchantId} in the API resource. Learn more in our dedicated Authentication guide.

ALIAS.ALIASID tokens
ALIAS.ORDERID N/A
ALIAS.
STOREPERMANENTLY
askConsumerConsent
CARD.
PAYMENTMETHOD
N/A
LAYOUT.
TEMPLATENAME
variant
PARAMETERS.
ACCEPTURL

N/A

Is covered bycardPaymentMethodSpecificInput.returnURL in the subsequent Server-to-server/ CreatePayment request with the tokenised credit card profile.

PARAMETERS.
EXCEPTIONURL

N/A

Not applicable. Is covered by cardPaymentMethodSpecificInput.returnURL in the subsequent Server-to-server/ CreatePayment request with the tokenised credit card profile.

SHASIGNATURE.
SHASIGN

N/A

Authentication is covered in the SDK initialisation/manual authentication for requests sent directly to our API. Learn more in our dedicated Authentication guide.

CARD.BRAND N/A
CARD.
PAYMENTMETHOD
N/A
LAYOUT.
LANGUAGE
locale
USERID

N/A

Authentication is covered in the SDK initialisation/manual authentication for requests sent directly to our API. Learn more in our dedicated Authentication guide.

PSWD

N/A

Authentication is covered in the SDK initialisation/manual authentication for requests sent directly to our API. Learn more in our dedicated Authentication guide.

CARDNO cardPaymentMethodSpecificInput.card.cardNumber
ED cardPaymentMethodSpecificInput.card.expiryDate
CN cardPaymentMethodSpecificInput.card.cardholderName
CVC cardPaymentMethodSpecificInput.card.cvv
browserAcceptHeader order.customer.device.acceptHeader
browserColorDepth order.customer.device.browserData.colorDepth
browserJavaEnabled order.customer.device.browserData.javaEnabled
browserLanguage order.customer.device.locale
browserScreenHeight order.customer.device.browserData.screenHeight
browserScreenWidth order.customer.device.browserData.screenWidth
browserTimeZone order.customer.device.timezoneOffsetUtcMinutes
browserUserAgent order.customer.device.userAgent
ACCEPTURL

cardPaymentMethodSpecificInput.threeDSecure.redirectionData.returnURL

Direct uses one redircection URL for all outcomes. Read more in the Optimise payment experience chapter.

DECLINEURL
EXCEPTIONURL
FLAG3D cardPaymentMethodSpecificInput.threeDSecure.skipAuthentication

Process transactions

Any request for a new transaction requires you to send data to our platform. To ease the migration effort for your, have a look at

  • The Authentication mechanism to confirm the legitimacy of your requests. It replaces the various ways of the classic platform (i.e. SHA-IN calculation, API user and password etc.), easing your integration effort.
  • This table to map classic parameters to Direct properties for all integration modes.
  • Fully functional code samples for any of our SDKs.
  • The properties marked as "required" in our API reference for a minimal request.

The image above shows the "order" property in the API reference marked as a required property

When processing a new transaction, mind that Direct:

  • Replaces the classic parameter OPERATION with property cardPaymentMethodSpecificInput.authorizationMode for CreatePayment/CreateHostedCheckout requests ,allowing you to process new transactions as authorisations or direct sales. If you authorise payments only, make sure that you capture them later.
  • Processes new transactions as authorisations and ignores the Back Office setting (Configuration > Technical information > Global transaction parameters > Default operation code). Therefore, we strongly recommend sending property cardPaymentMethodSpecificInput.authorizationMode in your request.

Follow-up on transactions

The classical integration offers the generic Direct Maintenance endpoint in combination with the OPERATION parameter for performing (final) refunds/captures etc.
Direct implements dedicated API resources for specific maintenance operations, making OPERATION obsolete:

  • Use property isFinal to close/keep open the transaction for subsequent maintenance operations.
  • Every request you send to our platform requires authentication. Learn more in the Process transactions chapter.
  • You can also use the Merchant Portal to perform these actions manually.

Move from PAYID to payment.id

Whenever you create a transaction, our platform generates a unique reference to it. You need to use this unique reference to follow-up on the transaction (i.e. to perform a maintenance operation like a capture/refund it or simply get the transaction status).

Legacy distinguishes between the:

  • PAYID (10-digit unique identifier that will never change over the course of a transaction life cycle)
  • PAYIDSUB (an incremental digit for each maintenance operation)

formatted as PAYID_PAYIDSUB.

However, Direct follows a different approach by implementing the payment.id: For both every new transaction request and maintenance operations our platform issues a unique value. Read our dedicated chapter in our Webhooks guide to learn how to implement the payment.id into your business logic to properly follow-up on transactions.

To allow you a smooth transition from the PAYID_PAYIDSUB format to the payment.id, our platform will support both format until further notice.

Optimise payment experience

The fundamentals of your customers' payment experience is the layout of the payment page and the redirection to your environment after the purchase.

Adapt payment page layout

Direct allows you to greatly customise your customers’ payment experience for any of the integration modes you choose. Check out the resources at your disposal:

Redirection after purchase

Depending on the transaction result, the classic platform redirects your customers to URLs you define in parameters ACCEPTURL/DECLINEURL/EXCEPTIONURL.

Direct follows a different approach: Instead of defining separate redirection URLs for every transaction result, you define only one single redirection URL for any scenario in property redirectPaymentMethodSpecificInput.redirectionData.returnUrl for CreateHostedCheckout/CreatePayment requests.

This requires you to customise the return page at runtime by requesting the transaction result immediately after the purchase (i.e. by using webhooks or GetPayment/GetPaymentDetails). Learn more about this in the following chapter.

Get transaction status and feedback

The classic platform uses the redirection URLs and Post Sale URLs and implements the Direct Query functionality to provide you with feedback about transaction results.

Direct offers webhooks and GetPaymentDetails endpoint to get all the information you need to follow-up on your orders. To enhance transparency, Direct implements three properties to represent a transaction status:

  • status
  • statusCategory
  • statusCode

Find an extensive overview about the return values in our dedicated Statuses guide, including a mapping of classic parameter STATUS and the aforementioned Direct properties.

Back Office / Merchant Portal

Direct reduces your efforts by outsourcing most of the Back Office technical settings to the REST API or the Merchant Portal. Check out the table for a comprehensive overview:

Back Office module (Configuration > Technical information > …) Impact on Direct integration
Global transaction parameters
  • "Default operation code": Direct ignores this setting. Send property cardPaymentMethodSpecificInput.authorizationMode.
    in your requests instead. If undefined, our platform processes transactions as authorisations by default.
  • "Payment retry": Direct ignores this setting. Send property hostedCheckoutSpecificInput.allowedNumberOfPaymentAttempts in your requests instead. If undefined, our platform grants 10 retries.
  • "Default data capture (payment) procedure"/"Processing for individual transactions" are still applicable for Direct transactions.
Global security parameters
Data and origin verification
Direct negates these settings by implementing a different authentication mechanism.
Payment page

Direct negates these settings by offering different customisation tools.

Make sure to still upload Hosted Checkout Page
/ Hosted Tokenization Page templates in the Back Office via Configuration > Template

API settings Manages Direct authentication/webhooks credentials, which you can also do via the Merchant Portal
Transaction feedback Direct negates these settings by using webhooks instead
Transaction emails Not used by Direct
Test info Not used by Direct. Refer to chapter Test integration to learn how to perform tests

Test integration

Direct offers many resources to allow you extensive testing by payment method, integration mode or desired transaction result:

  • Use the API explorer to send requests to any of our endpoints in our test environment. It works with both your PSPID/authentication credentials and even without them, enabling you to start testing right away!
  • Our Test cases page contains card numbers and precise instructions to trigger specific scenarios (i.e. successful/declined transactions). The “Testing” tab in our dedicated payment method documentations contain payment method-specific information to tailor your requests.

The test data / settings in the Back Office (Configuration > Technical Information > Test Info) are irrelevant for Direct.

Was this page helpful?

Do you have any comments?

Thank you for your response.