Switch to Direct
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:
- A powerful REST API
- Support for payment methods on local and international markets
- Manifold features and tools to support your business model and to optimise your customers’ payment experience
- And much more!
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:
- As mobile payments are becoming the dominant online transaction processing mode, Direct follows a “Mobile first!” approach: All our features, tools, payment methods, integration modes etc. are optimised for mobile devices
- Direct offers great opportunities for design control. Adapt the overall payment experience (the check-out process, the payment page itself etc.) to your corporate identity at your liking!
- With the advent of SCA, we keep implementing features to keep 3-D Secure both smooth and save, such as:
- Direct is subject to continuous improvement and the addition of new features. Keep an eye on our Release Notes for regular updates
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:
- 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 - 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
- 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 |
|---|---|
| PSPID ORDERID CURRENCY AMOUNT LANGUAGE SHASIGN OPERATION |
|
|
ACCOUNT.PSPID |
|
| 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 Not mandatory for Direct. If omitted, our platform will take the language configured in your Back Office (Configuration > Account > Your administrative details > Language) |
| 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
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:
- Customise Hosted Checkout Page
- Customise Hosted Tokenization Page
- Best practices for designing your customers payment experience
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 |
|
| 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!
- Create and customise requests with our Request Builder reflecting your business logic in your preferred programming language. It is a very useful tool especially in combination with our SDKs
- 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