Skip to main content

Server-to-Server Integration

The Server-to-Server solution enables direct exchange of transaction data between your server and Worldline's payment platform. This gives you full control over the customer experience while handling payments directly.

Benefits​

  • Full Control - Design your own payment page
  • Seamless Experience - Customers stay in your environment
  • Flexibility - Complete customization of the checkout flow
PCI DSS Compliance

This method involves handling card data, which requires PCI DSS compliance. Consider using Hosted Tokenization to reduce your PCI scope significantly.

Prerequisites​

Before implementing this integration, ensure you have:

  1. An active Worldline Direct account
  2. At least one payment method activated in the Merchant Portal
  3. Configured API Key and API Secret
  4. PCI DSS compliance (if handling card data directly)
  5. Server capable of processing RESTful API requests

Integration Flow​

Step-by-Step Implementation​

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 Payment Request​

Collect card details from your checkout page and send a CreatePayment request:

var body = new CreatePaymentRequest
{
    Order = new Order
    {
        AmountOfMoney = new AmountOfMoney
        {
            Amount = 2980,
            CurrencyCode = "EUR"
        },
        Customer = new Customer
        {
            MerchantCustomerId = "customer123",
            ContactDetails = new ContactDetails
            {
                EmailAddress = "customer@example.com"
            },
            BillingAddress = new Address
            {
                CountryCode = "NL",
                City = "Amsterdam"
            }
        },
        References = new OrderReferences
        {
            MerchantReference = "order-12345"
        }
    },
    CardPaymentMethodSpecificInput = new CardPaymentMethodSpecificInput
    {
        PaymentProductId = 1, // Visa
        Card = new Card
        {
            CardNumber = "4111111111111111",
            Cvv = "123",
            ExpiryDate = "1225",
            CardholderName = "John Doe"
        },
        ThreeDSecure = new ThreeDSecure
        {
            RedirectionData = new RedirectionData
            {
                ReturnUrl = "https://yoursite.com/return"
            }
        }
    }
};

var response = await client.WithNewMerchant("YOUR_MERCHANT_ID")
    .Payments
    .CreatePaymentAsync(body);

Step 3: Handle Response​

The response includes a merchantAction object that indicates the next step:

{
  "payment": {
    "id": "000000123400000012340000100001",
    "status": "PENDING_AUTHENTICATION",
    "statusOutput": {
      "statusCode": 50
    }
  },
  "merchantAction": {
    "actionType": "REDIRECT",
    "redirectData": {
      "redirectURL": "https://issuer-bank.com/3ds/authenticate"
    }
  }
}
ScenariomerchantAction.actionTypeNext Step
Frictionless 3DSnullTransaction complete, check status
3DS ChallengeREDIRECTRedirect customer to URL
No 3DSnullTransaction complete, check status

Step 4: Handle 3-D Secure (if required)​

If actionType is REDIRECT, redirect the customer to the authentication URL:

if (response.merchantAction?.actionType === 'REDIRECT') {
    window.location.href = response.merchantAction.redirectData.redirectURL;
}

After authentication, the customer returns to your returnUrl.

Step 5: Retrieve Payment Status​

After the customer returns, retrieve the final payment status:

var paymentDetails = await client.WithNewMerchant("YOUR_MERCHANT_ID")
    .Payments
    .GetPaymentDetailsAsync(paymentId);

var statusCode = paymentDetails.StatusOutput.StatusCode;

Step 6: Display Results​

Handle the payment status appropriately:

Status CodeMeaningAction
0-99PendingShow processing message
100-199AuthorizedConfirm order, capture later
500-599RejectedShow error, offer retry
800-899CapturedConfirm and fulfill order

Using Tokens​

Reduce PCI scope by using tokens instead of raw card data:

Permanent Tokens (Card-on-File)​

Store customer cards for future purchases:

CardPaymentMethodSpecificInput = new CardPaymentMethodSpecificInput
{
    Token = "stored_token_from_previous_transaction"
}

Temporary Tokens (Hosted Tokenization)​

Use temporary tokens from the Hosted Tokenization Page:

CardPaymentMethodSpecificInput = new CardPaymentMethodSpecificInput
{
    Token = "temporary_token_from_tokenization"
}
Recommended Approach

Using tokens significantly reduces your PCI DSS compliance requirements while maintaining a seamless checkout experience.

Webhooks​

Implement webhooks for reliable payment status notifications:

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

    // Update order status in your database
    UpdateOrderStatus(paymentId, statusCode);

    return Ok();
}
Important

Webhooks are asynchronous. Always use them as a backup notification mechanism, not for real-time checkout decisions.

Best Practices​

  1. Use Tokens - Minimize PCI scope by using tokenization
  2. Implement 3-D Secure - Always include 3DS properties for card payments
  3. Include Customer Email - Required for conversion tracking in MyPerformance
  4. Use Consistent References - Keep merchantReference consistent for analytics
  5. Handle All Statuses - Implement proper handling for all possible outcomes
  6. Set Up Webhooks - Never rely solely on return redirects

Client SDKs​

For collecting card details on the client side:

PlatformSDK
JavaScriptGitHub
iOS (Swift)GitHub
AndroidGitHub
Flutterpub.dev
React Nativenpm

Next Steps​