Intégration de paiement personnalisée

Ce document explique comment Monetization permet la prise en charge du traitement des paiements pour les fournisseurs de services de paiement tiers non pris en charge nativement ou pour les cas où vous décidez de gérer la logique de traitement des paiements en dehors de Monetization via vos processus d’intégration.

Catégorie:

Développement et intégration

Sujets dans ce document :

Traitement des paiements par des tiers dans Monetization
Traitement asynchrone des paiements
- Exportation de factures
  - Exporting job – fichier CSV vers SFTP
  - Notification - méthode webhook
- Importation de paiements
  - Importation de fichiers CSV via SFTP
  - Importation via appel API
    - Authentification
    - Demande d’importation de paiement
Traitement synchrone des paiements

Traitement des paiements par des tiers dans Monetization

Le traitement des paiements par des tiers est réalisable via deux méthodes : synchrone et asynchrone. La méthode synchrone nécessite des réponses immédiates de votre composant d’intégration de paiement, tandis que la méthode asynchrone combine l’extraction de factures de Monetization, puis l’importation des paiements ultérieurement.

Information :

En règle générale, votre cas d’utilisation détermine quelle méthode de traitement est optimale.

Traitement asynchrone des paiements

Pour le traitement asynchrone des paiements, vous exportez des factures de Monetization, et les paiements sont traités entièrement en dehors de Monetization. Lorsque vous avez les résultats du traitement des paiements, vous les importez via des fichiers CSV (Comma-Separated Values) ou l’API (Application Programming Interface) de Monetization.

Exportation de factures

Vous pouvez exporter des factures de Monetization en configurant un mapper d’exportation de factures et en planifiant un travail d’exportation (Exporting Job), qui exportera les fichiers vers un emplacement SFTP (Secure File Transfer Protocol), ou en vous abonnant à une création de facture via Webhook, qui déclenchera une demande de facture à l’adresse URL (Uniform Resource Locator) fournie chaque fois qu’une nouvelle facture est créée.

Exporting job – fichier CSV vers SFTP

Pour exporter des factures sous forme de fichiers CSV, un mapper d’exportation de factures (Invoice Export mapper) doit être configuré pour mapper les paramètres de facturation aux colonnes du fichier CSV. L’interface utilisateur de Monetization permet une telle configuration sous Business configuration Export Invoice mappers.

Example of invoice export mapper configuration Figure 1 : Exemple de configuration de mapper d’exportation de factures

Les exportations de factures sont planifiées via des Exporting Jobs, qui peuvent être des tâches ponctuelles ou automatisées pour s’exécuter sur des périodes spécifiques. L’Exporting Job enregistrera le fichier CSV exporté dans l’emplacement SFTP respectif storage/invoice/folder_name/file_name.csv.

Example of invoice export job Figure 2 : Exemple de travail d’exportation de factures

Notification - méthode webhook

L’exportation de factures via des webhooks vous permet de recevoir les factures immédiatement après leur création. Ceci est réalisé en configurant une règle de notification de facture (Invoice Notification Rule), qui enverra chaque facture créée sous la forme d’une demande de corps JSON (JavaScript Object Notation) à l’adresse URL fournie, ainsi que toutes les options d’en-tête préconfigurées.

Example of invoice creation webhook configuration Figure 3 : Exemple de configuration de webhook de création de facture

Importation de paiements

Vous pouvez importer des transactions de paiement dans Monetization en configurant un mapper d’importation de paiement et en téléchargeant les fichiers CSV de paiement vers l’emplacement d’entrée SFTP ou en utilisant l’API REST (Representational State Transfer) de Monetization.

Importation de fichiers CSV via SFTP

Pour que Monetization importe des transactions de paiement via des fichiers CSV, un mapper d’importation de paiement (Payment Import Mapper) doit être configuré. La configuration est possible via l’interface utilisateur de Monetization sous Business configuration Import Payment mappers.

Le Payment mapper permet de mapper les colonnes CSV aux paramètres de transaction de paiement et de définir un préfixe de fichier, qui doit être présent dans les fichiers téléchargés.

Les fichiers sont téléchargés sur le serveur SFTP dans le dossier edl/input et seront déplacés vers les dossiers edl/processed, edl/successful, edl/error et edl/rejected en fonction des résultats du traitement.

Example of payment import mapper configuration Figure 4 : Exemple de configuration de mapper d’importation de paiement

Importation via appel API

Pour importer une transaction de paiement via l’API de Monetization, postez une demande JSON contenant les détails de la transaction sur l’API REST de Monetization.

Note :

Un utilisateur doit d’abord être authentifié pour communiquer avec l’API de Monetization.

Authentification

L’API de Monetization utilise l’authentification par jeton porteur (Bearer Token) :

Exécutez la demande d’authentification avec le nom d’utilisateur, le mot de passe et le code de site spécifique.
Récupérez le token de la réponse.
Définissez l’en-tête Authorization sur Bearer <token> dans les demandes suivantes.
Le jeton expire après 5 minutes.

URL: {{api_url}}/authenticate

Headers
Content-Type:application/json

Body
{
    "username": "your_monetization_username",
    "password": "password",
    "site_code": "your_monetization_site_code - subdomain"
}

Demande d’importation de paiement

URL: {{api_url}}/api/v1/import

Headers
Content-Type:application/json
Authorization:Bearer {{auth_token}}
Data-Type:Payment

Body
{
    "invoice_id": 123,
    "transaction_identifier": "T-1233-cew3-445f-feew3",
    "amount": 150,
    "transaction_time": 1600613169000,
    "currency": "EUR",
    "method": "other",
    "type": "charge",
    "provider": "stripe"
}

Traitement synchrone des paiements

Le traitement synchrone des paiements nécessite une communication synchrone entre Monetization et votre composant d’intégration de paiement. Cette méthode de traitement permet les autorisations de carte de crédit/débit et les paiements immédiats.

Vous configurez Monetization pour spécifier où les demandes liées au traitement des paiements doivent être envoyées, et Monetization a des réponses prédéfinies qu’il attend en retour. Cette méthode de traitement permet le stockage de références de mode de paiement sur les clients et prend en charge les processus de collecte de paiement automatisés.

Pour Monetization, le processus d’intégration est pratiquement le même qu’une intégration prête à l’emploi avec un fournisseur existant (Stripe, Braintree, etc.). Cependant, la communication est exécutée via un composant développé par vous, qui agit comme une passerelle vers votre fournisseur de paiement local.

Opérations essentielles pour prendre en charge le traitement synchrone des paiements :

Setup Intent
Authorize
Capture
Charge

Configuration du fournisseur de paiement tiers

Pour configurer une intégration de fournisseur de paiement tiers, configurez un profil de passerelle de paiement tiers et fournissez l’adresse URL où Monetization doit envoyer les demandes.

Ceci est réalisable via l’interface utilisateur sous System configuration Payment gateways, ou en créant un profil de passerelle de paiement (Payment Gateway Profile) via l’API REST de Monetization.

URL: {{api_url}}/api/v1/payment-gateway-profiles

Headers
Content-Type:application/json
Authorization:Bearer {{auth_token}}

Request
{
    "provider": "third-party",
    "headers": {
        "PGW_URL": "URL to your payment gateway"
    }
}

Opérations client

Les opérations client ne s’appliquent que dans les cas où le fournisseur de paiement tiers prend en charge la gestion des clients. Si le fournisseur de paiement ne prend pas en charge la gestion des clients, les ids clients peuvent être remplacés par n’importe quelle valeur (par exemple, l’horodatage Unix de la demande).

Créer un client (sans carte)

Crée un client en tant qu’objet sur le service du fournisseur de paiement.

Demande envoyée par Monetization :

{
    "action": "create_customer",
    "content": {
        "customer": {
            "first_name": "John",
            "last_name": "Anderson",
            "company": "Company",
            "email": "john_anderson@testmail123.com",
            "phone": "003861234335",
            "tax_identifier": "123543569596"
        },
        "billing_address": {
            "first_name": "John",
            "last_name": "Anderson",
            "company": "Company",
            "street_address": "Address street 12",
            "locality": "Name of City",
            "postal_code": "84116",
            "region": "Region",
            "country_code": "SI",
            "country_name": "Slovenia "
        }
    }
}

Réponse attendue :

Statut HTTP (Hypertext Transfer Protocol) : 201 Created

{
    "customer": {
        "id": "payment_provider_customer_id"
    }
}

Mettre à jour le client

Met à jour un objet client sur le service du fournisseur de paiement.

Demande envoyée par Monetization :

{
    "action": "update_customer",
    "content": {
        "customer": {
            "id": "payment_provider_customer_id_1",
            "first_name": "John",
            "last_name": "Anderson",
            "company": "Company",
            "email": "john_anderson@testmail123.com",
            "phone": "003861234335",
            "tax_identifier": "123543569596"
        },
        "billing_address": {
            "first_name": "John",
            "last_name": "Anderson",
            "company": "Company",
            "street_address": "Address street 12",
            "locality": "Name of City",
            "postal_code": "84116",
            "region": "Region",
            "country_code": "SI",
            "country_name": "Slovenia "
        }
    }
}

Réponse attendue :

Statut HTTP : 204 No Content

Pas de corps de réponse

Lire le client

Lit un objet client du service du fournisseur de paiement.

{
    "action": "read_customer",
    "content": {
        "id": "payment_provider_customer_id_1"
    }
}

Réponse attendue :

Statut HTTP : 200 OK

{
    "content": {
        "customer": {
            "id": "payment_provider_customer_id_1",
            "first_name": "John",
            "last_name": "Anderson",
            "company": "Company",
            "email": "john_anderson@testmail123.com",
            "phone": "003861234335",
            "tax_identifier": "123543569596"
        },
        "billing_address": {
            "first_name": "John",
            "last_name": "Anderson",
            "company": "Company",
            "street_address": "Address street 12",
            "locality": "Name of City",
            "postal_code": "84116",
            "region": "Region",
            "country_code": "SI",
            "country_name": "Slovenia "
        },
        "credit_cards": [
            {
                "is_default": true,
                "card_holder_name": "John Anderson",
                "expiration_month": "03",
                "expiration_year": "2026",
                "type": "Mastercard",
                "token": "payment_provider_card_token",
                "last_four": "1234"
            }
        ]
    }
}

Supprimer le client

Supprime un objet client du service du fournisseur de paiement.

Demande envoyée par Monetization :

{
    "action": "delete_customer",
    "content": {
        "id": "payment_provider_customer_id_1"
    }
}

Réponse attendue :

Statut HTTP : 204 No Content

Pas de corps de réponse

Opérations de carte

Les opérations de carte font référence à la configuration ou à la suppression de cartes de crédit et de débit.

Configuration (demande de configuration de carte)

Déclenche un processus par lequel un client peut fournir des détails de carte de crédit, qui sont tokenisés et stockés dans Monetization. Lors d’une demande d’ajout d’une nouvelle carte de crédit, Monetization enverra une demande de configuration à votre composant d’intégration.

Votre composant d’intégration doit gérer toute logique liée aux services du fournisseur de paiement et renvoyer une adresse URL de redirection à Monetization en guise de réponse. Le client sera alors redirigé vers l’adresse URL fournie, où votre formulaire hébergé par le fournisseur de paiement collectera et tokenisera les détails de la carte du client.

Credit card setup Figure 5 : Configuration de carte de crédit

Demande envoyée par Monetization :

{
    "action": "setup",
    "content": {
        "customer": {
            "id": "payment_provider_customer_id_1",
            "first_name": "John",
            "last_name": "Anderson",
            "company": "Company",
            "email": "john_anderson@testmail123.com",
            "phone": "003861234335",
            "tax_identifier": "123543569596"
        },
        "billing_address": {
            "first_name": "John",
            "last_name": "Anderson",
            "company": "Company",
            "street_address": "Address street 12",
            "locality": "Name of City",
            "postal_code": "84116",
            "region": "Region",
            "country_code": "SI",
            "country_name": "Slovenia "
        }
        "custom_attributes": {
            "callback_url": "https://callbackurl.com"
        }
    }
}

Réponse attendue :

Statut HTTP : 201 Created

{
    "customer": {
        "id": "payment_provider_customer_id"
    },
    "redirect_url": "https://card-data-collection-form.com"
}

Supprimer la carte

Envoie une demande à votre composant d’intégration pour gérer la logique de suppression de la référence de la carte de crédit via les services du fournisseur de paiement, puis supprime la référence de Monetization en cas de succès.

Demande envoyée par Monetization :

{
    "action": "delete_credit_card",
    "content": {
        "customer": {
            "id": "provider_customer_id_34"
        },
        "credit_card": {
            "token": "provider_card_token_x23423532"
        }
    }
}

Réponse attendue :

Statut HTTP : 204 No Content

Pas de corps de réponse

Opérations de transaction

Les opérations de transaction font référence aux actions transactionnelles exécutées sur les jetons de mode de paiement stockés (carte de crédit/débit). Ces actions comprennent :

Autorisation
Capture
Charge
Annulation
Remboursement

Autorisation

L’autorisation est utilisée pour autoriser (bloquer) des fonds sur le mode de paiement d’un client. Les autorisations peuvent être capturées (Captured) ou annulées (Voided) ultérieurement. La demande ci-dessous est envoyée à votre composant d’intégration, qui doit gérer la logique du service du fournisseur de paiement et renvoyer une réponse.

Demande envoyée par Monetization :

{
    "action": "authorize",
    "content": {
        "amount": 20.5,
        "currency": "EUR",
        "customer": {
            "id": "provider_customer_id_34"
        },
        "credit_card": {
            "token": "provider_card_token_x23423532"
        }
    }
}

Réponse attendue :

Statut HTTP : 202 Accepted

{
    "transaction_id": "payment_provider_transaction_id",
    "amount": 25.5,
    "currency": "EUR",
    "time": "1650629967000",
    "success": true,
    "message": "Message from provider if given",
    "code": "Code from provider if given"
}

Capture

La capture fait référence à la collecte des fonds autorisés à partir d’une demande d’autorisation précédente. Le montant à collecter peut être égal ou inférieur au montant autorisé.

Tous les fonds autorisés non collectés seront restitués au client par le service du fournisseur de paiement. La demande ci-dessous est envoyée à votre composant d’intégration, qui doit gérer la logique du service du fournisseur de paiement et renvoyer une réponse.

Demande envoyée par Monetization :

{
    "action": "capture",
    "content": {
        "transaction_id": "provider_transaction_id_t2134234",
        "amount": 10.5
    }
}

Réponse attendue :

Statut HTTP : 202 Accepted

{
    "transaction_id": "payment_provider_transaction_id",
    "amount": 10.5,
    "currency": "EUR",
    "time": "1650629967000",
    "success": true,
    "message": "Message from provider if given",
    "code": "Code from provider if given"
}

Charge

Charge autorise et capture les fonds en une seule transaction immédiate. La demande ci-dessous est envoyée à votre composant d’intégration, qui doit gérer la logique du service du fournisseur de paiement et renvoyer une réponse.

Demande envoyée par Monetization :

{
    "action": "charge",
    "content": {
        "amount": 25.5,
        "currency": "EUR",
        "customer": {
            "id": "provider_customer_id_34"
        },
        "credit_card": {
            "token": "provider_card_token_x23423532"
        }
    }
}

Réponse attendue :

Statut HTTP : 202 Accepted

{
    "transaction_id": "payment_provider_transaction_id",
    "amount": 25.5,
    "currency": "EUR",
    "time": "1650629967000",
    "success": true,
    "message": "Message from provider if given",
    "code": "Code from provider if given"
}

Annulation

L’opération d’annulation (Void) annule une transaction d’autorisation et libère les fonds autorisés. La demande ci-dessous est envoyée à votre composant d’intégration, qui doit gérer la logique du service du fournisseur de paiement et renvoyer une réponse.

Demande envoyée par Monetization :

{
    "action": "void",
    "content": {
        "transaction_id": "provider_transaction_id_t2134234"
    }
}

Réponse attendue :

Statut HTTP : 202 Accepted

{
    "transaction_id": "payment_provider_transaction_id",
    "time": "1650629967000",
    "success": true,
    "message": "Message from provider if given",
    "code": "Code from provider if given"
}

Remboursement

Le remboursement (Refund) renvoie les fonds au client et fait référence à une transaction de charge ou de capture précédente. La demande ci-dessous est envoyée à votre composant d’intégration, qui doit gérer la logique du service du fournisseur de paiement et renvoyer une réponse.

Demande envoyée par Monetization :

{
    "action": "refund",
    "content": {
        "transaction_id": "provider_transaction_id_t2134234",
        "amount": 10.5
    }
}

Réponse attendue :

Statut HTTP : 202 Accepted

{
    "transaction_id": "payment_provider_transaction_id",
    "amount": 25.5,
    "currency": "EUR",
    "time": "1650629967000",
    "success": true,
    "message": "Message from provider if given",
    "code": "Code from provider if given"
}

Gestion des erreurs

Au cas où une opération ne réussirait pas sur votre composant d’intégration, renvoyez n’importe quel statut en dehors de la plage 200-300 et le message d’erreur dans le corps de la réponse.

Appareils