Page de paiement hebergee

La Page de paiement hebergee est une solution d'integration de paiement simplifiee qui vous permet de traiter des transactions en ligne tout en deleguant la gestion des donnees sensibles des titulaires de carte a la plateforme Worldline.

Avantages

• Conformite PCI - Deleguez la gestion des donnees sensibles a Worldline
• Design flexible - Personnalisation visuelle facile avec des modeles
• Integration rapide - Demarrez rapidement avec un minimum de code

Prerequis

Avant d'implementer cette methode d'integration, assurez-vous d'avoir :

• Un compte marchand actif sur Worldline Direct
• Au moins une methode de paiement activee dans le Portail Marchand
• Une cle API et un secret API configures
• Un serveur capable d'effectuer des requetes API RESTful

Utilisez nos SDKs

Nous recommandons d'utiliser l'un de nos SDKs serveur pour une integration simplifiee. Les SDKs sont disponibles pour .NET, Java, Node.js, PHP, Python et Ruby.

Flux d'integration

Integration etape par etape

Etape 1 : Initialiser le SDK

Configurez votre SDK serveur avec vos identifiants :

C#

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);

Java

CommunicatorConfiguration configuration = new CommunicatorConfiguration()
    .withApiEndpoint(URI.create("https://payment.preprod.direct.worldline-solutions.com"))
    .withAuthorizationType(AuthorizationType.V1HMAC)
    .withApiKeyId("YOUR_API_KEY")
    .withSecretApiKey("YOUR_API_SECRET");

Client client = Factory.createClient(configuration);

PHP

$communicatorConfiguration = new CommunicatorConfiguration(
    'YOUR_API_KEY',
    'YOUR_API_SECRET',
    'https://payment.preprod.direct.worldline-solutions.com',
    'OnlinePayments'
);

$client = Factory::createClient($communicatorConfiguration);

Points d'acces des environnements :

Environnement	URL
Test	https://payment.preprod.direct.worldline-solutions.com
Production	https://payment.direct.worldline-solutions.com

Etape 2 : Creer une session Hosted Checkout

Envoyez une requete CreateHostedCheckout pour generer une session de paiement :

C#

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);

Java

CreateHostedCheckoutRequest body = new CreateHostedCheckoutRequest();

AmountOfMoney amountOfMoney = new AmountOfMoney();
amountOfMoney.setAmount(2980L);
amountOfMoney.setCurrencyCode("EUR");

Order order = new Order();
order.setAmountOfMoney(amountOfMoney);
body.setOrder(order);

HostedCheckoutSpecificInput hostedCheckoutSpecificInput = new HostedCheckoutSpecificInput();
hostedCheckoutSpecificInput.setReturnUrl("https://yoursite.com/return");
body.setHostedCheckoutSpecificInput(hostedCheckoutSpecificInput);

CreateHostedCheckoutResponse response = client
    .withNewMerchant("YOUR_MERCHANT_ID")
    .hostedCheckout()
    .createHostedCheckout(body);

Exemple de reponse :

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

Duree de la session

La session reste valide pendant trois heures par defaut. Personnalisez cette duree avec hostedCheckoutSpecificInput.sessionTimeout.

Etape 3 : Rediriger le client

Utilisez le redirectUrl de la reponse pour rediriger les clients vers le formulaire de paiement securise :

window.location.href = response.redirectUrl;

Important

• Les URLs de redirection sont valides pendant trois heures
• N'integrez pas l'URL dans une iframe
• Pour les WebView mobiles, activez le stockage DOM

Etape 4 : Gerer les resultats de la transaction

Apres le paiement, les clients sont rediriges vers votre returnUrl. Recuperez le statut de la transaction :

C#

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

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

Java

GetHostedCheckoutResponse status = client
    .withNewMerchant("YOUR_MERCHANT_ID")
    .hostedCheckout()
    .getHostedCheckoutStatus(hostedCheckoutId);

Integer statusCode = status.getCreatedPaymentOutput()
    .getPayment()
    .getStatusOutput()
    .getStatusCode();

Etape 5 : Afficher les resultats

Affichez un retour approprie en fonction du code de statut :

Code de statut	Signification	Action
0-99	En attente	Afficher le message "En cours de traitement"
100-199	Autorise	Confirmer la commande
500-599	Rejete	Afficher l'erreur, proposer de reessayer
800-899	Capture	Confirmer et executer la commande
900-999	Rembourse	Afficher la confirmation de remboursement

Fonctionnalites avancees

Carte enregistree (Paiements par token)

Activez les paiements en un clic pour les clients recurrents :

var body = new CreateHostedCheckoutRequest
{
    CardPaymentMethodSpecificInput = new CardPaymentMethodSpecificInputForHostedCheckout
    {
        Token = "previously_stored_token"
    },
    // ... reste de la requete
};

Personnalisation du modele

Personnalisez l'apparence de la page de paiement :

1. Creez des modeles avec le Template Builder ou telechargez-les via le Portail Marchand
2. Referencez votre modele dans la requete API :

HostedCheckoutSpecificInput = new HostedCheckoutSpecificInput
{
    Variant = "my-custom-template"
}

Parametres de langue

Definissez la langue de la page de paiement avec les codes de locale ISO :

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

Pre-selection de la methode de paiement

Ignorez l'ecran de selection de la methode de paiement :

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

Limiter les tentatives de paiement

Reduisez la fraude en limitant les tentatives (1-10) :

HostedCheckoutSpecificInput = new HostedCheckoutSpecificInput
{
    AllowedNumberOfPaymentAttempts = 3
}

Webhooks

Implementez les webhooks comme mecanisme de notification de secours :

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

    // Traiter la mise a jour du statut de paiement

    return Ok();
}

Timing des webhooks

Les webhooks sont asynchrones et peuvent arriver apres le retour du client sur votre site. Utilisez-les comme sauvegarde, pas pour les decisions de paiement en temps reel.

Bonnes pratiques

1. Toujours utiliser les webhooks - Implementez-les comme sauvegarde pour les redirections manquees
2. Verifier les methodes de paiement - Assurez-vous que les methodes sont activees avant de creer des sessions
3. Gerer tous les statuts - Implementez une gestion appropriee pour les succes, echecs et etats en attente
4. Utiliser les tokens - Stockez les tokens pour les clients recurrents afin d'ameliorer la conversion
5. Activer la detection de fraude - Utilisez les fonctionnalites de prevention de la fraude de la plateforme
6. Tester minutieusement - Validez tous les scenarios dans l'environnement de test

SDKs serveur

Langage	Package
.NET	NuGet
Java	Maven
Node.js	npm
PHP	Packagist
Python	PyPI
Ruby	RubyGems

Prochaines etapes

• Configurer les webhooks pour des notifications de statut fiables
• Explorer les moyens de paiement pour activer plus d'options
• Implementer 3-D Secure pour une securite renforcee