Intégration de paiement personnalisée
Sujet dans ce document :
- Traitement des paiements tiers dans Monetization
- Traitement des paiements asynchrone
- Traitement des paiements synchrone
Traitement des paiements tiers dans Monetization
Le traitement des paiements tiers est réalisable par 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 des factures de Monetization, puis l’importation des paiements à un moment ultérieur.
Information:
En général, votre cas d’utilisation détermine quelle méthode de traitement est optimale.Traitement des paiements asynchrone
Pour le traitement des paiements asynchrone, vous exportez des factures de Monetization, et les paiements sont traités en dehors de Monetization entièrement. Lorsque vous avez les résultats du traitement des paiements, vous les importez via des fichiers CSV ou l’API de Monetization.
Exportation des factures
Vous pouvez exporter des factures de Monetization en configurant un mappage d’exportation de factures et en planifiant un travail d’exportation, qui exportera les fichiers vers un emplacement SFTP, ou en vous abonnant à la création de factures via Webhook, ce qui déclenchera une demande de facture à l’adresse URL fournie chaque fois qu’une nouvelle facture est créée.
Travail d’exportation – Fichier CSV vers SFTP
Pour exporter des factures sous forme de fichiers CSV, un mappage d’exportation de factures doit être configuré pour mapper les paramètres de factures aux colonnes de fichiers CSV. L’interface utilisateur de Monetization permet une telle configuration sous Configuration commerciale Exportation Mappers de factures.
Figure 1 : Exemple de configuration de mappage d’exportation de factures
Les exportations de factures sont planifiées via des Travaux d’exportation, qui peuvent être des tâches ponctuelles ou automatisées pour s’exécuter pendant des périodes spécifiques. Le travail d’exportation enregistrera le fichier CSV exporté à l’emplacement SFTP respectif storage/invoice/folder_name/file_name.csv.
Figure 2: Exemple de tâche d’exportation de factures
Notification - méthode webhook
L’exportation de factures via des webhooks vous permet de recevoir des factures immédiatement après leur création. Cela est réalisé en configurant une Règle de Notification de Facture, qui enverra chaque facture créée sous forme de requête JSON à l’adresse URL fournie, ainsi que toutes les options d’en-tête préconfigurées.
Figure 3: Exemple de configuration de webhook pour la création de factures
Importation des paiements
Vous pouvez importer des transactions de paiement dans Monetization en configurant un mappage d’importation de paiement et en téléchargeant les fichiers CSV de paiement à l’emplacement d’entrée SFTP ou en utilisant l’API REST de Monetization.
Importation de fichiers CSV via SFTP
Pour que Monetization importe des transactions de paiement via des fichiers CSV, un Mappage d’Importation de Paiement doit être configuré. La configuration est possible via l’Interface Utilisateur de Monetization sous Configuration commerciale Importation Mappers de paiement.
Le mappage de paiement 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.
Figure 4: Exemple de configuration de mappage d’importation de paiement
Importation via appel API
Pour importer une transaction de paiement via l’API Monetization, envoyez une requête JSON contenant les détails de la transaction à l’API REST de Monetization.
Note:
Un utilisateur doit d’abord être authentifié pour communiquer avec l’API Monetization.Authentification
L’API Monetization utilise l’authentification par 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
tokende la réponse. - Définissez l’en-tête
AuthorizationsurBearer <token>dans les demandes à venir. - Le token 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 des paiements synchrones
Le traitement des paiements synchrones nécessite une communication synchrone entre Monetization et votre composant d’intégration de paiement. Cette méthode de traitement permet les autorisations de cartes 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’elle attend en retour. Cette méthode de traitement permet le stockage des références de méthode de paiement sur les clients et prend en charge les processus de collecte de paiements 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 s’effectue par le biais d’un composant développé par vous, qui agit comme une passerelle vers votre fournisseur de paiement local. Opérations essentielles pour soutenir le traitement des paiements synchrones :
- Configuration de l’intention
- Autoriser
- Capturer
- Facturer
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’URL où Monetization doit envoyer les demandes.
Cela peut être réalisé via l’interface utilisateur sous Configuration du système Passerelles de paiement, ou en créant un profil de passerelle de paiement 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 de votre passerelle de paiement"
}
}
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, alors les ids des clients peuvent être remplacés par n’importe quelle valeur (par exemple, un 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.
``` HTTP Status: 201 Créé
```json
{
"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 :
HTTP Status: 204 Pas de contenu
Pas de corps de réponse
Lire le client
Lit un objet client à partir du service du fournisseur de paiement. ```json { “action”: “lire_client”, “content”: { “id”: “payment_provider_customer_id_1” } }
**Réponse attendue :**
HTPP Statut : 200 OK
```json
{
"content": {
"customer": {
"id": "payment_provider_customer_id_1",
"first_name": "John",
"last_name": "Anderson",
"company": "Société",
"email": "john_anderson@testmail123.com",
"phone": "003861234335",
"tax_identifier": "123543569596"
},
"billing_address": {
"first_name": "John",
"last_name": "Anderson",
"company": "Société",
"street_address": "Adresse rue 12",
"locality": "Nom de la ville",
"postal_code": "84116",
"region": "Région",
"country_code": "SI",
"country_name": "Slovénie"
},
"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 de fournisseur de paiement.
Demande envoyée par Monetization :
{
"action": "supprimer_client",
"content": {
"id": "payment_provider_customer_id_1"
}
}
Réponse attendue :
HTTP Statut : 204 Pas de contenu
Pas de corps de réponse
Opérations de carte
Les opérations de carte se réfèrent à la configuration ou à la suppression de cartes de crédit et de débit.
Configuration (demande de configuration de carte)
Déclenche un processus où un client peut fournir les détails de sa 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 la logique liée aux services du fournisseur de paiement et renvoyer une URL de redirection vers Monetization en réponse. Le client sera ensuite redirigé vers l’URL fournie, où le formulaire hébergé par votre fournisseur de paiement collectera et tokenisera les détails de la carte du client.
Figure 5 : Configuration de la 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": "Slovénie"
}
"custom_attributes": {
"callback_url": "https://callbackurl.com"
}
}
}
Réponse attendue :
Statut HTTP : 201 Créé
{
"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 référence de 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 Pas de contenu
Pas de corps de réponse
Opérations de transaction
Les opérations de transaction se réfèrent aux actions transactionnelles exécutées sur les jetons de méthode de paiement stockés (carte de crédit/débit). Ces actions incluent :
Autorisation
L’autorisation est utilisée pour autoriser (verrouiller) des fonds sur la méthode de paiement d’un client. Les autorisations peuvent ensuite être capturées ou annulées. 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 retourner 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 Accepté
{
"transaction_id": "payment_provider_transaction_id",
"amount": 25.5,
"currency": "EUR",
"time": "1650629967000",
"success": true,
"message": "Message du fournisseur si donné",
"code": "Code du fournisseur si donné"
}
Capture
La capture se réfère à la collecte de fonds autorisés 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 retourner 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 Accepté
{
"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 des fonds en tant que transaction immédiate unique. 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 Accepté
{
"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"
}
annuler
L’opération d’annulation annule une transaction d’autorisation, libérant 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 Accepté
{
"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 retourne des 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 retourner 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 Accepté
{
"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
En cas d’échec d’une opération sur votre composant d’intégration, retournez tout statut en dehors de la plage 200-300 et le message d’erreur dans le corps de la réponse.
