Skip to main content

Hosted Checkout Page

The Hosted Checkout Page is a streamlined payment integration solution that enables you to process online transactions while delegating sensitive cardholder data handling to Worldline's platform.

Benefits​

  • PCI Compliance - Delegate handling of sensitive data to Worldline
  • Flexible Design - Easy visual customization with templates
  • Quick Integration - Get up and running fast with minimal code

Prerequisites​

Before implementing this integration method, ensure you have:

  • An active merchant account on Worldline Direct
  • At least one payment method activated in the Merchant Portal
  • Configured API Key and API Secret
  • Server capability for RESTful API requests
Use Our SDKs

We recommend using one of our Server SDKs for simplified integration. SDKs are available for .NET, Java, Node.js, PHP, Python, and Ruby.

Integration Flow​

Step-by-Step Integration​

Step 1: Initialize SDK​

Configure your Server SDK with your credentials:

var configuration = new CommunicatorConfiguration
{
    ApiEndpoint = new Uri("https://payment.preprod.direct.worldline-solutions.com"),
    AuthorizationType = AuthorizationType.V1HMAC,
    ApiKeyId = "YOUR_API_KEY",
    SecretApiKey = "YOUR_API_SECRET"
};

var client = Factory.CreateClient(configuration);

Environment Endpoints:

EnvironmentURL
Testhttps://payment.preprod.direct.worldline-solutions.com
Productionhttps://payment.direct.worldline-solutions.com

Step 2: Create Hosted Checkout Session​

Send a CreateHostedCheckout request to generate a payment session:

var body = new CreateHostedCheckoutRequest
{
    Order = new Order
    {
        AmountOfMoney = new AmountOfMoney
        {
            Amount = 2980,
            CurrencyCode = "EUR"
        },
        Customer = new Customer
        {
            MerchantCustomerId = "customer123",
            BillingAddress = new Address
            {
                CountryCode = "NL"
            }
        }
    },
    HostedCheckoutSpecificInput = new HostedCheckoutSpecificInput
    {
        ReturnUrl = "https://yoursite.com/return",
        Variant = "your-template-name"
    }
};

var response = await client.WithNewMerchant("YOUR_MERCHANT_ID")
    .HostedCheckout
    .CreateHostedCheckoutAsync(body);

Example Response:

{
  "RETURNMAC": "12345678-90ab-cdef-1234-567890abcdef",
  "hostedCheckoutId": "123456",
  "merchantReference": "7e21badb48fe45848bbc1efef2a88504",
  "redirectUrl": "https://payment.preprod.direct.worldline-solutions.com/..."
}
Session Duration

The session remains valid for three hours by default. Customize this using hostedCheckoutSpecificInput.sessionTimeout.

Step 3: Redirect Customer​

Use the redirectUrl from the response to redirect customers to the secure payment form:

window.location.href = response.redirectUrl;
Important
  • Redirect URLs are valid for three hours
  • Do not embed the URL in an iframe
  • For mobile WebView, enable DOM storage

Step 4: Handle Transaction Results​

After payment, customers are redirected to your returnUrl. Retrieve the transaction status:

var status = await client.WithNewMerchant("YOUR_MERCHANT_ID")
    .HostedCheckout
    .GetHostedCheckoutStatusAsync(hostedCheckoutId);

var statusCode = status.CreatedPaymentOutput?.Payment?.StatusOutput?.StatusCode;

Step 5: Display Results​

Show appropriate feedback based on the status code:

Status CodeMeaningAction
0-99PendingShow "Processing" message
100-199AuthorizedConfirm order
500-599RejectedShow error, offer retry
800-899CapturedConfirm and fulfill order
900-999RefundedShow refund confirmation

Advanced Features​

Card-on-File (Token Payments)​

Enable one-click payments for returning customers:

var body = new CreateHostedCheckoutRequest
{
    CardPaymentMethodSpecificInput = new CardPaymentMethodSpecificInputForHostedCheckout
    {
        Token = "previously_stored_token"
    },
    // ... rest of request
};

Template Customization​

Customize the payment page appearance:

  1. Create templates using the Template Builder or upload via Merchant Portal
  2. Reference your template in the API request:
HostedCheckoutSpecificInput = new HostedCheckoutSpecificInput
{
    Variant = "my-custom-template"
}

Language Settings​

Set the payment page language using ISO locale codes:

HostedCheckoutSpecificInput = new HostedCheckoutSpecificInput
{
    Locale = "fr_FR"  // French (France)
}

Payment Method Pre-selection​

Skip the payment method selection screen:

HostedCheckoutSpecificInput = new HostedCheckoutSpecificInput
{
    PaymentProductFilters = new PaymentProductFiltersHostedCheckout
    {
        RestrictTo = new PaymentProductFilter
        {
            Products = new List<int> { 1 }  // Visa only
        }
    }
}

Limit Payment Attempts​

Reduce fraud by limiting retry attempts (1-10):

HostedCheckoutSpecificInput = new HostedCheckoutSpecificInput
{
    AllowedNumberOfPaymentAttempts = 3
}

Webhooks​

Implement webhooks as a backup notification mechanism:

[HttpPost("webhook")]
public IActionResult HandleWebhook([FromBody] WebhookEvent webhookEvent)
{
    var payment = webhookEvent.Payment;
    var statusCode = payment.StatusOutput.StatusCode;

    // Process the payment status update

    return Ok();
}
Webhook Timing

Webhooks are asynchronous and may arrive after the customer returns to your site. Use them as a backup, not for real-time checkout decisions.

Best Practices​

  1. Always use webhooks - Implement as backup for missed return redirects
  2. Verify payment methods - Ensure methods are activated before creating sessions
  3. Handle all statuses - Implement proper handling for success, failure, and pending states
  4. Use tokens - Store tokens for returning customers to improve conversion
  5. Enable fraud detection - Use the platform's fraud prevention features
  6. Test thoroughly - Validate all scenarios in the test environment

Server SDKs​

LanguagePackage
.NETNuGet
JavaMaven
Node.jsnpm
PHPPackagist
PythonPyPI
RubyRubyGems

Next Steps​