Flux d'Annulation et de Capture

Lors de l'intégration avec Yuno, vous disposez de plusieurs options pour implémenter les opérations de capture et d'annulation. Ce guide présente toutes les approches disponibles et explique comment interagir avec nos API pour chaque scénario.

Nous proposons une capture en temps réel simple pour les transactions rapides, ainsi que des configurations de capture différée et d'annulation différée hautement personnalisables pour répondre à vos besoins commerciaux.

Aperçu

Modes de capture
Modes d'Annulation
- Annulation manuelle
- Annulation différée
Exigences de configuration
Exemples de Requêtes
Quand Utiliser Chaque Mode
Référence des Champs

Modes de capture

Yuno propose trois options pour la capture des paiements, déterminées par le champ capture et la configuration facultative delayed_capture_settings trouvée dans créer une API de paiement. La disponibilité réelle de la fonctionnalité ou les détails d'implémentation spécifiques peuvent varier en fonction du fournisseur de paiement via lequel vous acheminez vos paiements.

Capture en Temps Réel

Ce mode traite le paiement et transfère les fonds sans délai, combinant efficacement l'autorisation et la capture en une seule opération. achat opération. Lorsque payment_method.detail.card.capture est fixé à true, la transaction est exécutée comme un achat, ce qui signifie que l'autorisation et la capture ont lieu simultanément.

Selon l'API du fournisseur de paiement, Yuno peut exécuter ceci comme une seule transaction d'achat directe ou comme une autorisation immédiatement suivie d'un appel de capture.

{
  "payment_method": {
    "detail": {
      "card": {
        "capture": true,
        "card_data": {
          // card details
        }
      }
    }
  }
}

Capture manuelle

Avec cette configuration, Yuno ne capturera pas le paiement tant que vous n'aurez pas appelé l' API de capture ou que vous ne l'aurez pas capturé manuellement dans votre Tableau de bord Yuno. Définissez capture: false pour autoriser le paiement sans le capturer.

Les captures manuelles offrent une flexibilité maximale car elles vous donnent un contrôle total sur le moment où la capture est effectuée. Cependant, il est important de capturer dès que possible, car les fournisseurs de paiement imposent des limites de temps sur la durée pendant laquelle les autorisations peuvent rester non capturées, et ces limites varient selon le fournisseur et la région.

{
  "payment_method": {
    "detail": {
      "card": {
        "capture": false,
        "card_data": {
          // card details
        }
      }
    }
  }
}

🚧
Capturer des Montants Différents
Si vous devez capturer un montant différent de celui initialement autorisé, vous devez utiliser la capture manuelle. Les modes de capture en temps réel et de capture différée captureront toujours le montant initialement autorisé.

Capture différée

Configurez les capture: false avec les delayed_capture_settings pour planifier la capture du paiement à un moment ultérieur, spécifié dans le champ delay .

🚧
Captures du montant total uniquement
La capture différée ne s'applique que lorsque vous capturez le montant total de l'autorisation. Si vous devez capturer un montant partiel, vous devez utiliser la capture manuelle à la place.

📘
simplified_mode
Paramètres simplified_mode à true fera en sorte que Yuno réessaiera l'opération de capture au cas où une erreur se produirait lors de la tentative de capture planifiée.

{
  "payment_method": {
    "detail": {
      "card": {
        "capture": false,
        "delayed_capture_settings": {
          "delay": "P7D",
          "simplified_mode": false
        },
        "card_data": {
          // card details
        }
      }
    }
  }
}

Le champ delay est obligatoire lors de l'utilisation des opérations de capture différée et doit suivre la Norme ISO 8601. Par exemple :

"PT3H" pour 3 heures
"P7D" pour 7 jours
"P1M" pour 1 mois

Si vous appelez l'API de capture avant l'heure prévue, votre appel annulera le délai et exécutera immédiatement la capture. Cette action annule automatiquement le déclencheur Yuno prévu. Vous pouvez également capturer le paiement manuellement via votre tableau de bord Yuno.

Modes d'Annulation

Lorsque vous autorisez un paiement sans le capturer immédiatement, ces fonds sont temporairement retenus sur la méthode de paiement du client. Si vous décidez de ne pas capturer le paiement, il est important d'annuler l'autorisation pour libérer ces fonds retenus et offrir une meilleure expérience client. Les modes d'annulation vous donnent le contrôle sur le moment et la manière dont ces autorisations sont annulées.

Annulation manuelle

Avec le mode d'annulation manuelle, les paiements autorisés restent actifs jusqu'à ce que vous les annuliez explicitement. Yuno n'annulera pas automatiquement ces autorisations, vous donnant un contrôle total sur le moment de la libération des fonds. Vous pouvez annuler les autorisations à l'aide de l'API d'annulation ou via l'interface de votre tableau de bord Yuno.

Il est crucial d'annuler les autorisations que vous ne capturerez pas dès que possible pour libérer les fonds retenus. L'expérience client est considérablement impactée lorsque les autorisations ne sont pas annulées, car les fonds peuvent rester réservés pendant des périodes variables selon la région du client et le réseau de cartes.

Annulation différée

Configurez les delayed_cancel_settings pour définir un délai lors de l'annulation des autorisations non capturées, similaire aux captures différées. Cette fonctionnalité automatise la libération des fonds des clients si vous décidez de ne pas les capturer dans un délai spécifié, améliorant considérablement l'expérience client en empêchant les retenues indéfinies sur leurs méthodes de paiement.

Le champ delay est obligatoire lors de l'utilisation des opérations d'annulation différée et doit suivre la Norme ISO 8601. Par exemple :

"PT3H" pour 3 heures
"P7D" pour 7 jours
"P30D" pour 30 jours

📘
simplified_mode
Paramètres simplified_mode à true fera en sorte que Yuno réessaiera l'opération d'annulation au cas où une erreur se produirait lors de la tentative d'annulation planifiée.

{
  "payment_method": {
    "detail": {
      "card": {
        "capture": false,
        "delayed_cancel_settings": {
          "delay": "P30D",
          "simplified_mode": false
        },
        "card_data": {
          // card details
        }
      }
    }
  }
}

Si vous appelez l'API de capture ou l'API d'annulation avant l'heure prévue, votre appel annulera le délai et exécutera l'action immédiatement. Cette action annule automatiquement le déclencheur Yuno prévu. Vous pouvez également capturer ou annuler le paiement manuellement via votre tableau de bord Yuno.

⚠️
Paramètres de Capture et d'Annulation Différées
Nous recommandons de ne pas utiliser à la fois delayed_capture_settings et delayed_cancel_settings simultanément pour éviter les comportements inattendus. Utilisez-en un seul à la fois en fonction de vos besoins.

Exigences de configuration

delayed_capture_settings et delayed_cancel_settings ne sont valables que lorsque capture = false
Si capture = true, ces objets doivent être omis ou définis sur null
Les opérations manuelles peuvent être effectuées via les endpoints API ou via votre tableau de bord Yuno.

Exemples de Requêtes

Exemple 1 : Capture en Temps Réel

{
  "country": "US",
  "amount": {
    "currency": "USD",
    "value": "20000"
  },
  "customer_payer": {
    "id": "<customer_id>",
    "first_name": "John",
    "last_name": "Doe",
    "email": "[email protected]"
  },
  "workflow": "DIRECT",
  "payment_method": {
    "detail": {
      "card": {
        "capture": true,
        "card_data": {
          "number": "4111111111111111",
          "expiration_month": 11,
          "expiration_year": 28,
          "security_code": "123",
          "holder_name": "John Doe"
        }
      }
    },
    "type": "CARD"
  },
  "account_id": "<account_id>",
  "description": "Real-time capture payment",
  "merchant_order_id": "000023"
}

Exemple 2 : Capture Manuelle Uniquement

{
  "country": "US",
  "amount": {
    "currency": "USD",
    "value": "20000"
  },
  "customer_payer": {
    "id": "<customer_id>",
    "first_name": "John",
    "last_name": "Doe",
    "email": "[email protected]"
  },
  "workflow": "DIRECT",
  "payment_method": {
    "detail": {
      "card": {
        "capture": false,
        "card_data": {
          "number": "4111111111111111",
          "expiration_month": 11,
          "expiration_year": 28,
          "security_code": "123",
          "holder_name": "John Doe"
        }
      }
    },
    "type": "CARD"
  },
  "account_id": "<account_id>",
  "description": "Authorization only - manual capture",
  "merchant_order_id": "000024"
}

Exemple 3 : Capture Différée

{
  "country": "US",
  "amount": {
    "currency": "USD",
    "value": "20000"
  },
  "customer_payer": {
    "id": "<customer_id>",
    "first_name": "John",
    "last_name": "Doe",
    "email": "[email protected]"
  },
  "workflow": "DIRECT",
  "payment_method": {
    "detail": {
      "card": {
        "capture": false,
        "delayed_capture_settings": {
          "delay": "P7D",
          "simplified_mode": false
        },
        "card_data": {
          "number": "4111111111111111",
          "expiration_month": 11,
          "expiration_year": 28,
          "security_code": "123",
          "holder_name": "John Doe"
        }
      }
    },
    "type": "CARD"
  },
  "account_id": "<account_id>",
  "description": "Authorization with delayed capture",
  "merchant_order_id": "000025"
}

Exemple 4 : Annulation Différée

{
  "country": "US",
  "amount": {
    "currency": "USD",
    "value": "20000"
  },
  "customer_payer": {
    "id": "<customer_id>",
    "first_name": "John",
    "last_name": "Doe",
    "email": "[email protected]"
  },
  "workflow": "DIRECT",
  "payment_method": {
    "detail": {
      "card": {
        "capture": false,
        "delayed_cancel_settings": {
          "delay": "P30D",
          "simplified_mode": false
        },
        "card_data": {
          "number": "4111111111111111",
          "expiration_month": 11,
          "expiration_year": 28,
          "security_code": "123",
          "holder_name": "John Doe"
        }
      }
    },
    "type": "CARD"
  },
  "account_id": "<account_id>",
  "description": "Authorization with delayed cancel",
  "merchant_order_id": "000026"
}

Exemple 5 : Capture différée et annulation combinées avec validation améliorée

Cet exemple montre une demande de paiement complète avec des paramètres de capture différée et d'annulation, ainsi que des champs de validation client améliorés :

{
  "country": "US",
  "amount": {
    "currency": "USD",
    "value": "20000"
  },
  "customer_payer": {
    "merchant_customer_validations": {
      "account_is_verified": true,
      "email_is_verified": true,
      "phone_is_verified": true
    },
    "id": "<customer_id>",
    "first_name": "John",
    "last_name": "Doe",
    "email": "[email protected]"
  },
  "workflow": "DIRECT",
  "payment_method": {
    "detail": {
      "card": {
        "capture": false,
        "delayed_capture_settings": {
          "delay": "P20D",
          "simplified_mode": true
        },
        "delayed_cancel_settings": {
          "delay": "P40D",
          "simplified_mode": true
        },
        "card_data": {
          "number": "4111111111111111",
          "expiration_month": 11,
          "expiration_year": 28,
          "security_code": "123",
          "holder_name": "John Doe"
        },
        "verify": false
      }
    },
    "type": "CARD"
  },
  "account_id": "<account_id>",
  "description": "Payment with card details",
  "merchant_order_id": "000023"
}

⚠️
Note
Bien que cet exemple montre à la fois delayed_capture_settings et delayed_cancel_settings configurés ensemble, nous recommandons de n'en utiliser qu'un à la fois afin d'éviter tout comportement inattendu.

Quand Utiliser Chaque Mode

Utilisez la capture en temps réel lorsque :

Vous fournissez des biens ou des services immédiatement
Vous n'avez pas besoin de valider l'inventaire ou les contrôles de fraude après l'autorisation
Vous souhaitez le flux de paiement le plus simple

Utilisez la capture manuelle lorsque :

Vous devez vérifier l'inventaire avant de finaliser le paiement
Vous souhaitez capturer un montant différent de celui autorisé
Vous avez une logique commerciale complexe qui détermine s'il faut capturer ou annuler
Vous avez besoin d'un contrôle maximal sur le moment de la capture

Utilisez la capture différée lorsque :

Vous souhaitez une capture automatique après une période de temps spécifique
Vous disposez d'un processus d'exécution prévisible
Vous souhaitez réduire l'intervention manuelle tout en conservant le contrôle

Utiliser l'annulation différée lorsque :

Vous souhaitez libérer automatiquement les fonds du client si vous ne capturez pas dans un délai donné
Vous souhaitez améliorer l'expérience client en ne retenant pas les fonds indéfiniment
Vous avez une limite de temps maximale pour votre processus d'exécution

Référence des Champs

Champ	Type	Description
`capture`	`boolean`	Détermine si le paiement par carte est capturé immédiatement (`true`, achat) ou seulement autorisé (`false`, nécessite capture ou annulation).
`delayed_capture_settings.delay`	`string`	Délai avant que Yuno ne capture le paiement. Doit suivre le format de durée ISO 8601 (par exemple, "P7D" pour 7 jours, "PT3H" pour 3 heures).
`delayed_capture_settings.simplified_mode`	`boolean`	Si `true`, Yuno réessaie la capture si elle échoue.
`delayed_cancel_settings.delay`	`string`	Délai avant que Yuno n'annule l'autorisation. Doit suivre le format de durée ISO 8601 (par exemple, "P30D" pour 30 jours).
`delayed_cancel_settings.simplified_mode`	`boolean`	Si `true`, Yuno réessaie l'annulation si elle échoue.

Flux d'Annulation et de Capture

Aperçu

Modes de capture

Capture en Temps Réel

Capture manuelle

Capturer des Montants Différents

Capture différée

Captures du montant total uniquement

`simplified_mode`

Modes d'Annulation

Annulation manuelle

Annulation différée

`simplified_mode`

Paramètres de Capture et d'Annulation Différées

Exigences de configuration

Exemples de Requêtes

Exemple 1 : Capture en Temps Réel

Exemple 2 : Capture Manuelle Uniquement

Exemple 3 : Capture Différée

Exemple 4 : Annulation Différée

Exemple 5 : Capture différée et annulation combinées avec validation améliorée

Note

Quand Utiliser Chaque Mode

Utilisez la capture en temps réel lorsque :

Utilisez la capture manuelle lorsque :

Utilisez la capture différée lorsque :

Utiliser l'annulation différée lorsque :

Référence des Champs