Payment Page Integration - Steps¶

The Worldline Payment Page is a web-based solution for accepting cards and alternative payment methods for e-commerce businesses. When checking out from your web store, the consumer is redirected to a branded payment page hosted on one of Worldline servers. The customer enters the payment details and completes the payment. The consumer is then returned to your web store with the payment transaction status. The financial credentials never need to touch your site.

Behind the scenes, when redirected to the Payment Page server, the consumer is presented with a payment selection web page.

To assist the consumer in completing a payment there is also built-in support for server side retry-handling, where the payment page is displayed again for declined transactions to allow the consumer to correct their details or select another payment method instead of being redirected back to the merchant.

If customer is redirected to a third-party payment method during a session in the Payment Page flow, the contact with the consumers may be lost (for example, the consumer close the browser). Therefore, an outgoing host-to-host notification when an order status has changed state is available. Depending on the nature of the payment method, the final status of a payment may not be known when the consumer returns to the merchant’s site. The Worldline can poll third-party payment method providers for updates and send outgoing notifications to the merchant, andalso provides an alternate way where a merchant may pull order information using a the Web Service Interface. The information regarding the successful or failed payments is also available in the Worldline Standard Reports and in the OneSource merchant portal.

Reference documents Please contact your Worldline Integration Manager for our reference documentation.

Step 1 - Configuration and Solution Design¶

The Payment Page product allows flexibility in terms of how the system handles 3D Secure, timeouts, stored tokens, and other aspects of the payment processing.

Payment methods: Basic flow¶

The Payment Page flow is slightly dependent on the selected payment method selected since the underlying payment methods differ in behavior. However, you can build a future-proof implementation of Payment Page if you consider those behaviors from the outset.

Payment Method Type	Description
Cards	Real-time response from Payment Page, immediate confirmation of payment
Consumer redirect payment methods - Internet Bank Payments and e-wallets	Real-time response from Payment Page, usually immediate confirmation of payment but sometimes delayed as the user may close the browser instead of coming back
Offline consumer push payments - bank transfers	Response from Payment Page will always indicate delayed confirmation of payment
Payouts	Response from Payment Page will always indicate delayed confirmation of refund

Our recommendation is to implement the following high level steps for all the payment methods

Redirect to Payment Page.
Wait for the response with the current status.
If current status is not final, wait for the notification, report file or query Worldline Web Service Interface to get the final confirmation before releasing the product or service they have paid for

A detailed Payment Page flow illustrated for alternative payment methods (Cards, IBP and other redirects, EFT, SEPA Direct Debit, and Payout). For a current list of available payment methods within each family, contact Worldline.

Step 2 - Client Side Implementation¶

Redirect the customer¶

When the consumer is redirected from the merchant to the Payment Page, the merchant has to pass on a few data elements, such as amount, currency, and other data elements to the Payment Page. As some of the data elements contain sensitive information, Payment Page implements a secure protocol to protect the data. To assist the merchant in packing the data in a correct manner, a Java or .Net reference implementation is included in the Start Kit. A merchant may use the Java or .Net implementation as is or implement the needed functionality by using the reference implementation for guidance.

Secure the redirection¶

The security solution in the Payment page consists of host authentication and message encryption. The certificates are used to authenticate the other part when the merchant communicates with Worldline. The public certificate is signed by Worldline and is used continuously until replaced by Worldline. During the implementation of the Payment Page, you need to install certificates in the environment your application is calling from twice:

First set - is used during the development of the Payment Page solution at the merchant site. For your benefit, the certificates used during development and test in the Acceptance Test Environment are provided as part of the Start Kit.
Second set - is implemented at the time of launching the Payment Page solution in production for live traffic. The production certificates are issued by Worldline as part of moving the solution to the production environment, and you must request the certificate to be signed by Worldline. For more information refer to, Migration to Production Environment .

Redirecting to Worldline¶

The consumer is to be redirected to the Payment Page to complete their payment

Call the createRedirectURL method for Java reference/createPaymentPageUrl method for .Net reference with the desired order parameters from your checkout application. Several parameters are (R) required when initiating this call, while others are (C) conditional or (O) optional depending on merchant configuration. For example, you need to provide:
1. Your Merchant ID
2. Unique order parameters, such as Order ID, Amount, Currency.
3. Which payment page to present through the template reference parameter.Each page is allocated with a reference ID by the system. It is recommended to take this into account when building the integration on the client side since you may want to be flexible for easily accessing newly added pages when entering new markets, adding brands or other situations.
4. Your return URL to use for the payment response
5. Flag whether to store the card details at Worldline for future usage (tokenization) and so on. For more information, refer to, Payment Page request and response parameters.

Few web browsers have a maximum limit of allowed characters in the URL and we recommend that the created URL doesn't exceed 1500 characters. To prevent this you should try not to pass unnecessary information for example, in the additional parameters field.

Example:

Java

        PaymentPageRequest request = new PaymentPageRequest();
        request.setMid(1234567890L);
        request.setTransactionChannel("Web Online");
        request.setOrderId("orderid");
        request.setAmount(123.0);
        request.setCurrency("SEK");
        request.setConsumerCountry("SE");
        request.setConsumerLanguage("sv");
        request.setReturnUrl("http://merchant.com?f=3&f=q");
        request.setAuthorizationType(AuthorizationType.PRE_AUTHORIZATION);

        String redirectUrl = paymentPageHandler.createRedirectUrl(request);

C#

private PPDOTNETPaymentPageHandler pph = new PPDOTNETPaymentPageHandler();
private PPDOTNETCustomerRedirect customerRedirect;

customerRedirect = new PPDOTNETCustomerRedirect();
customerRedirect.Mid = 1699538718;
customerRedirect.TransactionChannel = "Web Online";
customerRedirect.StoreFlag = 1;
customerRedirect.TransactionType = "debit";
customerRedirect.OrderId = "PP_1430740594567";
customerRedirect.Amount = 50.2;
customerRedirect.Currency = "EUR";
customerRedirect.CustomerCountry = "SE";
customerRedirect.CustomerLanguage = "sv";
customerRedirect.RedirectReturnUrl = "https://my-website-dot-com/return-endpoint";
customerRedirect.PaymentMethodId = 0;
customerRedirect.RedirectTimeOut = 999;

if (cbKeySize.SelectedItem.Equals("2048"))
{
 pph.init(createCertMerchant(KEYSIZE_2048), certdrwp, string.Empty, new PPDOTNETSecurityHandlerV6());
}

Log.AppendText(NEWLINE + pph.createPaymentPageUrl(customerRedirect));

The secure URL created by the API will look like https://secure.payments.worldline.com/pay?creq=AB7114CH21A...

Using this Redirect the consumer’s browser to the secure URL. This must be performed with a HTTP GET Redirect, and sends the consumer to the Payment Page.

Handle the redirect back from Worldline¶

When the consumer has completed their interaction with the Payment Page, they are redirected to the return URL that was specified in the redirect call.

The result of the consumer’s interaction with the Payment Page is sent through the HTTP GET to the “return URL” that was provided in the request as: https://[“return url”]/?response=BEii9iVIovcIfS_zH...
The payment result is encrypted in the response parameter. Use the UnpackResponse method to decode and verify the contents of response. For more information, refer to, Payment Page request and response parameters.
There are six statuses that can appear in the response, as described in the table below, indicating what kind of message to present to the consumer or what action to take. Note: The Worldline do not present the result of a payment to the consumer.

Java

PaymentPageResponse response = paymentPageHandler.unpackResponse(respString);

Long mid = response.getMid();
String orderId = response.getOrderId();
String status = response.getStatus();

C#

PPDOTNETPaymentPageResponse ppr = pph.unpackResponse(p);
Log.AppendText(NEWLINE + "Mid: " + ppr.Mid);
Log.AppendText(NEWLINE + "OrderId: " + ppr.OrderId);
Log.AppendText(NEWLINE + "Status: " + ppr.Status);
Log.AppendText(NEWLINE + "Scheme Reference Id: " + ppr.SchemeReferenceId);

See below table for a description of the status

Status	Description
OK	The payment has been successfully processed by the Payment Page.
NOK	The payment was not completed. The user has used several attempts to submit a payment and ultimately been redirected back to the merchant due to exceeding the (configurable) maximum number of retries. NOK may also be returned if Worldline detects a possible fraud attempt. Contact your Integration Manager about Worldline fraud protection offerings.
USERCANCEL	The consumer pressed the cancel button. You may redirect the consumer back to the payment page.
TIMEOUT	The consumer tried to initiate a payment after the timeout set by the merchant has expired.
PENDING	The final status of the payment is not yet determined. The final status of the payment will be notified via a notification, in a report or pulled from Worldline Web Interface depending on your setup. Note that this is an expected result for many payment methods.
ERROR	The Payment Page detects that there is something wrong in the URL content or the configuration of the merchant. If this result status is encountered, the merchant should review their parameters and contact Worldline if the problem cannot be identified.

Multiple responses and no response¶

When implementing response handling the consumer is in control of the information flow. Expect that on occasion there will be multiple responses for a single transaction due to reloads and navigating through the history. The best way to handle this is to make sure that if the merchant receives a response with status OK, this must always take precedence over any previous or later responses with another status. In certain cases it is also possible that no response is sent. For example, if the consumer is redirected to the bank for 3D Secure verification and never comes back, the Payment Page has no way of returning the consumer to the merchant.

Binaries¶

Binaries and dependency information for Maven, Ivy, Gradle and others can be found at https://bintray.com/worldlinenordics/payment-api/payment-api . Here you can also find Change History and Version Numbers.

Follow the instructions of how to use JCenter as a Maven repository provided by Bintray, click the SET ME UP icon on the page

Example for Maven:¶

XML

<dependency>
  <groupId>com.worldline.payments</groupId>
  <artifactId>payment-api</artifactId>
  <version>4.4.1</version>
  <type>pom</type>
</dependency>

Example for Gradle:¶

compile 'com.worldline.payments:payment-api:4.4.1'

It is also possible to manually download the jar file from this page.

Test Keys¶

All keys needed for testing are provided as a ZIP file, test_keys.zip, supporting security version 6.

Step 3 - Customize the Payment Pages¶

Available markets from Worldline¶

The following markets are provided as default, but may change over time so please check with your account manager.

Market	Payment methods available	Description	Recommended language
International	Visa, MasterCard, American Express, PayPal, UnionPay	Standard used for internationally accepted payment methods	Any*
USA	"International" + Discover, JCB, PayPal		US English*
United Kingdom	"International" + Maestro UK, Solo, Visa Delta, Visa Electron		UK English*
Ireland	"International" + Laser		UK English*
France	"International" + Carte Bleue, Carte Aurore		French*
Germany	"International" + Maestro International, Giropay, Sofortüberweisung, SEPA Direct Debit (ELV), EFT		German*
Netherlands	"International" + Maestro International, iDEAL, SEPA Direct Debit, EFT		Dutch*
Austria	"International" + Maestro International, EPS, SEPA Direct Debit		Austrian German*
Sweden	"International" + IBP Swedbank, IBP SEB, IBP Nordea, IBP SHB/ Handelsbanken, Maestro International, Visa Electron		Swedish*
Finland	"International" + IBP Säästöpankki, IBP S-Pankki, IBP OP-Pohjola, IBP Aktia, IBP Danske Bank, IBP Nordea, Maestro International, Visa Electron		Finnish*, Swedish
Denmark	"International" + IBP Nordea, Dankort, Dankort Visa		Danish*
Norway	"International"	Use International template and local language	Norwegian*
Spain	"International"	Use International template and local language	Spanish*
Italy	"International"	Use International template and local language	Italian*
China	"International" + Alipay, IPS (IBP and debit cards), UnionPay		Simplified Chinese*
South Korea	"International" + Local payments (requires Internet Explorer)		Korean*
Brazil	"International" + Boleto, Hiper, Diners, Aura, Elo		Brazilian Portuguese
Australia	"International" + BPay, UnionPay		English
Lithuania	"International" + EFT		Lithuanian
Poland	"International" + Dotpay		Polish
Belgium	"International" + Bancontact		UK English*

Notes:

These pages are tested with JavaScript and cookies activated.

Languages¶

We have listed the recommended language for each market, although any language may be used for any market, and this is specified in each redirect request using standard ISO codes. Worldline provides localized language properties for a number of markets.

Note: The pages require local language settings in the Operating System of the client computer to display correctly (e.g. Simplified Chinese may not look right on Western locale settings).

Timeout¶

A timeout can be set in the redirect to Payment Page and is configured in seconds. If a consumer attempts to initiate a payment after the timeout is reached it will be rejected and return status TIMEOUT. If this parameter is not set, or set to zero, it means that the request will never time out.

Tokenization¶

If tokenization is used, this is specified as part of the call before sending the consumer to Payment Page. For SEPA Direct Debit tokenization is by default enabled as it stores Mandate Information.

Retries¶

The number of retries allowed for each consumer is configured on the server side and cannot be changed in the templates. Default is three times.

Error handling on the page¶

Within the page an error text may be displayed to indicate that the consumer has performed a failed payment attempt before the current page hit. The various errors that may occur have been grouped by the appropriate action for the consumer, based on the list below, and are localized:

Incorrect payment information - The consumer should check details and try again.
Temporary error - The consumer should try again in a short while.
Payment declined - The consumer should check details or try a different bank/card.

Security¶

Since Worldline are hosting the servers where Payment Page templates are processed and displayed, the content must meet both Worldline and PCI-DSS (Payment Card Industry Data Security Standard) requirements. The merchant is responsible for any submitted files or scripts or material that is made available through Payment Page and must be cautious not to introduce vulnerabilities or exploits, such as cross site scripting (XSS). Worldline reserves the right to remove the content from its servers. For more information on web security, Worldline recommends visiting http://www.owasp.org/.

Step 4 - Testing and Certification¶

Acceptance Test Environment¶

To simplify and speed up the integration process for the merchant, Worldline provides an integration environment, the Acceptance Test Environment. The content can be tested by the merchant without the need for lengthy interaction with Worldline.

Certification¶

When the merchant has performed testing in the acceptance test environment the merchant is ready to begin the certification process. The merchant will execute transactions according to certification protocols provided by Worldline and the result will be verified. Exactly what needs to be certified depends on the payment types and methods in use. A complete specification of all available certification test cases can be found in the start kit. Note that the merchant will receive a customized version of the TestData.xls document which will specify all the test cases that the merchant needs to perform to become certified.

Step 5 - Moving to Production¶

Now that you have built and certified your solution, you need to request production certificates to ensure that you follow the security standards employed within Payment Page.

Request and install certificates for production¶

Note that the merchant needs to work with separate certificates for the production environment. A high level procedure for generating new certificates is described here:

The merchant generates an RSA 2048 key and sends a Certification Signing Request to Worldline.
Worldline responds by issuing 2 certificates
- The requested merchant certificate, signed by Worldline, used by Payment Page to encrypt the responses to the merchant.
- Worldline public certificate, used by the merchant to encrypt the requests to Payment Page.
The merchant switches certificates.

How-to guide for the PaymentPage API is described in the following sections

Java example¶

Generate a new RSA keypair for production use.
- For generating 2048 size RSA keypair:
```
>keytool -genkeypair -keystore merchant.jks –sigalg SHA256withRSA -alias merchant -keyalg RSA -keysize 2048 -dname "C=SE,O=Organisation,OU=OrganisationUnit,CN=CertificateHolder"
```
  A few notes:
- This command will create a new merchant.jks keystore, so make sure that there is no file named merchant.jks in the folder where the command is executed.
- Before running the command, replace the distinguished name "C=SE,O=Organisation,OU=OrganisationUnit,CN=CertificateHolder" with information that applies to your company. For instance, "C=US,O=Digital River World Payments Systems AB,OU=Digital River World Payments ITO,CN=payments.digitalriver.com".
- The password that keytool prompts for will be the password used for accessing the keystore. It is important that the same password is used for the key or the Worldline API will not be able to access it.
Create the certificate request that will be used by Worldline to issue a production certificate.
```
>keytool -certreq -alias merchant -file request.csr -keystore merchant.jks
```
Send the file request.csr to your integration manager at Worldline.
Worldline will respond by sending back:
- The merchant certificate, signed by Worldline. Two different formats are available. Choose any of them:
  
  a) merchant_cert.pem b) merchant_cert.p7c
- The Worldline public certificate. Two different formats are available. Choose any of them:
  
  a) drwp_cert.cer b) drwp_cert.pem
Import the issued merchant certificate in the production keystore. This will associate the certificate with the key.
```
>keytool -importcert -trustcacerts -alias merchant -file merchant_cert.p7c -keystore merchant.jks
```
Import the Worldline certificate. This will associate the certificate with the key.
```
>keytool -importcert -alias ngcert -file drwp_cert.pem -keystore merchant.jks
```
Replace the acceptance test keystore with the new keystore in production. It must be named merchant.jks. The private key generated by the keytool command in step 1 can be exported to PEM format using the tool in Appendix B – Export Private Key to PEM format.