- Directives d'intégration
- Fonctionnalités prises en charge (options de paiement)
- Conversion de devise dynamique
Conversion de devise dynamique
Mastercard Gateway peut vous proposer une estimation du taux en temps réel d'un prestataire de services de conversion de devise dynamique pour les biens et services dont le prix est établi dans votre devise préférée. Vous pouvez proposer ce taux de change au payeur qui peut alors choisir de payer dans votre devise préférée ou dans la devise de la carte. Ce service permet aux titulaires de carte de connaître, au moment de l'achat, le montant exact qui leur sera facturé dans leur devise.
Avantages clés
- Les payeurs peuvent payer des biens ou des services dans leur devise de facturation sur le point de vente.
- Vous percevez une partie des frais de conversion de devise.
- La commande est traitée dans la devise de la commande.
- Les payeurs voient le montant de la commande dans leur devise sur le relevé de carte.
- Les payeurs ne voient pas de frais de conversion de devise sur le relevé de carte (ces frais sont inclus dans l'estimation du taux indiquée).
Conditions préalables aux devis
- Vous devez être enregistré auprès du prestataire de services de conversion de devise dynamique voulu.
Mastercard Gateway prend actuellement en charge les éléments suivants :
- FEXCO.
Gestion des estimations de taux via la passerelle
Concernant l'application de la conversion de devise dynamique à une transaction, il existe quatre scénarios de base qui s'excluent mutuellement :
- Vous ne voulez pas appliquer la conversion de devise dynamique à la transaction, par exemple si la devise de la carte du payeur correspond à votre devise préférée.
- Vous voulez appliquer la conversion de devise dynamique s'il existait une offre, mais ce n'est pas le cas.
- Vous voulez appliquer la conversion de devise dynamique. Le prestataire de services de conversion de devise dynamique a fait une offre. Vous l'avez transmise au payeur et celui-ci l'a rejetée.
- Vous voulez appliquer la conversion de devise dynamique. Le prestataire de services de conversion de devise dynamique a fait une offre. Vous l'avez transmise au payeur et celui-ci l'a acceptée.
Demander une estimation du taux
Vous pouvez demander une estimation du taux en indiquant des données pour les champs suivants dans la demande Payment Options Inquiry (Demande d'option de paiement) (apiOperation=PAYMENT_OPTIONS_INQUIRY) :
order.amount.order.currency.paymentType. S'il est renseigné, ce champ doit être défini surCREDIT.
currencyConversion.gatewayCode=UNSUPPORTED_CARD_BRAND.Lorsque vous appelez l'opération Payment Options Inquiry (Demande d'options de paiement) à l'aide du protocole REST, veillez à ce que les paramètres de la demande soient inclus dans l'URI (comme paramètres de demande) et non dans le corps du code JSON. Une demande REST en Curl pour une estimation du taux de conversion de devise dynamique est illustrée ci-dessous.
curl --user merchant.TESTMERCHANT-DCC:<PASSWORD>"https://ap-gateway.mastercard.com/api/rest/version/72/merchant/TESTMERCHANT-DCC/paymentOptionsInquiry?order.amount=123.34&order.currency=USD&sourceOfFunds.provided.card.prefix=531335999"
Réponses d'état de l'estimation du taux
Mastercard Gateway retourne les renseignements suivants à propos de l'offre CDD. Certaines d'entre elles seront incluses dans les informations affichées pour le payeur sur votre page de paiement ou votre terminal PED, conformément au modèle et aux exigences légales.
currencyConversion.gatewayCode:QUOTE_PROVIDED: Estimation proposée.NOT_ELIGIBLE: Conversion de devise dynamique non disponible pour cette carte et/ou devise.UNSUPPORTED_CARD_BRAND: Type de carte non pris en charge.INSUFFICIENT_INFORMATION: Champs obligatoires manquants dans la demande.ERROR: Prestataire de services de conversion de devise dynamique dans l'impossibilité de traiter cette opération.
currencyConversion.provider: Nom du prestataire d'estimation CDD.currencyConversion.providerCode: Généré par le prestataire de services de conversion de devise dynamique ; résume la réussite ou autre de la demande d'estimation CDD.currencyConversion.providerReceipt: Référence unique du prestataire de services de conversion de devise dynamique pour l'estimation (non indiquée systématiquement).currencyConversion.exchangeRateSource: Organisme financier utilisé comme source pour le taux de change.currencyConversion.payerExchangeRate: Taux de change utilisé pour convertir le montant de la transaction dans la devise du payeur. Cela inclutcurrencyConversion.marginPercentage.currencyConversion.payerAmount: Montant total de la transaction dans la devise du payeur.currencyConversion.payerCurrency: Devise du devis CDD indiquée par le prestataire de services de conversion de devise dynamique.currencyConversion.marginPercentage: Majoration de change appliquée en tant que pourcentage au montant de la transaction pour la fourniture du service de conversion.currencyConversion.exchangeRateTime: Horodatage de l'entrée en vigueur du taux de conversion.currencyConversion.quoteExpiry: Horodatage de l'expiration de l'offre de conversion de devise dynamique. (Non indiqué systématiquement.)currencyConversion.offerText: Fragment HTML contenant un formulaire de saisie pour l'offre de conversion de devise dynamique. Il doit être présenté au payeur afin de connaître son choix.currencyConversion.requestId: Identifiant unique de la demande de devis CDD, comme retourné dans la réponse PAYMENT_OPTIONS_INQUIRY.
Référence de l'API Payment Options Inquiry (Demande d'options de paiement)[REST][NVP]
Utilisation de l'estimation du taux pour une transaction
-
Si vous obtenez une estimation du taux du prestataire de services de conversion de devise dynamique (
currencyConversion.gatewayCode=QUOTE_PROVIDED), vous pouvez faire une offre de conversion de devise au payeur.Offres d'estimation du tauxTexte de l'offre
Visa et Mastercard ont des exigences spécifiques pour l'affichage des informations CDD aux payeurs afin que ceux-ci disposent des informations requises pour faire un choix en connaissance de cause. Cela comprend les détails des frais dans l'offre CDD et le reçu de la transaction (si le payeur accepte l'offre).
Principes fondamentaux des réglementations en matière de conversion de devise dynamique :
- Le titulaire de la carte peut payer dans la devise du commerçant ou dans sa propre devise, les détails de la transaction étant totalement transparents.
- Le titulaire de la carte a la possibilité d'accepter ou de refuser l'offre de conversion de devise dynamique.
- Les modalités associées à la conversion de devise dynamique sont intégralement communiquées au titulaire de la carte.
Présentation de l'offre
Le texte de l'offre vous sera indiqué dans
paymentTypes.card.currencyConversion.offerText. Vous pouvez indiquer les paramètres régionaux du texte de l'offre en définissantlocale=<Valid language identifier or IETF language tag of payer's locale>(enpour l'anglais,pt-BRpour le portugais brésilien,es-MXpour l'espagnol mexicain, etc.).Un texte d'offre CDD au format HTML spécifique de paramètres régionaux est retourné dans
paymentTypes.card.currencyConversion.offerTextpour les paramètres régionaux pris en charge suivants :- Français (fr_FR)
- Allemand (de_DE)
- Espagnol du Mexique (es_MX)
- Chinois :
- Chinois simplifié (zh_CN)
- Chinois de Hong Kong (zh_HK)
- Portugais du Brésil (pt_BR)
- Japonais (ja_JP)
- Indonésien (id_ID)
- Anglais :
- États-Unis (en_US)
- Royaume-Uni (en_UK)
- Australie (en_AU)
Si les paramètres régionaux ne sont pas pris en charge, Mastercard Gateway proposera un texte d'offre selon le modèle suivant :
- Le code de langue est mis en correspondance avec les paramètres régionaux pris en charge les plus proches, le cas échéant.
- Si vous ne définissez pas
interaction.localeou si les paramètres régionaux et la langue de base indiqués ne sont pas pris en charge, Mastercard Gateway tentera d'utiliser vos paramètres régionaux par défaut configurés. Si ces paramètres régionaux et cette langue de base ne sont pas pris en charge, l'offre est présentée enen_US.
Le payeur peut alors :-
Accepter l'offre de conversion de devise dynamique et choisir de payer dans la devise de la carte.
Dans ce cas, lancez une demande de transaction avec les paramètres suivants :
currencyConversion.requestIdcomme retourné dans la réponse de Mastercard Gateway.currencyConversion.uptake=ACCEPTED.
Communiquez au payeur le texte du reçu indiqué dans
paymentTypes.card.currencyConversion.receiptTextdans la réponseRETRIEVE_TRANSACTION. Celui-ci utilise les mêmes paramètres régionaux que le texte de l'offre. -
Refuser l'offre de conversion de devise dynamique et choisir de payer dans la devise de la commande (
currencyConversion.uptake=DECLINED).Dans ce cas, lancez une demande de transaction avec les paramètres suivants :
currencyConversion.requestIdcomme retourné dans la réponse de Mastercard Gateway.currencyConversion.uptake=DECLINED.
-
Si vous recevez l'un des éléments suivants dans la réponse de l'opération Payment Options Inquiry (Demande d'options de paiement) :
currencyConversion.gatewayCode=UNSUPPORTED_CARD_BRANDcurrencyConversion.gatewayCode=NOT_ELIGIBLEcurrencyConversion.gatewayCode=ERROR
Vous devez définir
currencyConversion.uptake=NOT_AVAILABLEdans votre demande de transaction et indiquer lecurrencyConversion.requestIdcorrect.
Cela permet au prestataire de conversion de devise dynamique d'utiliser les données à des fins d'analyse et de rapports.
Si vous obtenez une estimation du taux à l'extérieur de la passerelle, vous devez indiquer clairement les détails de la conversion de devise dynamique qui vous sont retournés dans la demande de transaction par le prestataire de services de conversion de devise dynamique.
Si vous souhaitez utiliser l'API d'authentification pour authentifier le payeur avant d'effectuer le paiement, vous devez transmettre les champs de conversion de devise dynamique comme décrit dans l'opération Initiate Authentication (Initier l'authentification). Une fois l'authentification du payeur terminée, vous pouvez procéder au paiement sur la même commande avec une opération Authorize (Autoriser) ou Pay (Payer) et renseigner le champ authentication.transactionId que vous avez fourni dans les opérations Initiate Authentication (Initier l'authentification) et Authenticate Payer (Authentifier le payeur). Vous n'avez pas besoin de retransmettre les champs de conversion de devise dynamique dans votre transaction financière car ils sont repris de la transaction d'authentification du payeur référencée.
Référence de l'API Conversion de devise [REST][NVP]
Transactions de conversion de devise dynamique Capture (Collecter)/Refund (Rembourser)
Collectes
Les détails CDD doivent être indiqués dans la demande de transaction Authorize (Autoriser). Ils s'appliquent aux collectes sur la commande.
Pour une collecte complète, les détails CDD de la demande Authorize (Autoriser) seront utilisés.
Pour les collectes partielles ou en excès, Mastercard Gateway calcule le montant au prorata du pourcentage.
Référence de l'API Currency Conversion for Captures (Conversion de devise pour les collectes) [REST][NVP]
Remboursements
Si votre configuration a été effectuée par votre MSO pour la CDD dans Mastercard Gateway, cette configuration s'applique aux remboursements ultérieurs.
Options de configuration :
CURRENT: Une nouvelle estimation du taux est demandée pour indiquer le taux réel à la date de la transaction de remboursement.HISTORICAL: Le taux utilisé lors de la création de la commande sera appliqué au remboursement.
Si currencyConversion.uptake=ACCEPTED pour la transaction initiale :
- La configuration est
CURRENT:- Une estimation du taux sera demandée pour le montant de remboursement spécifique. Cela donnera lieu à un nouveau
currencyConversion.requestId. La nouvelle estimation du taux sera appliquée au remboursement. - La réponse de transaction est
currencyConversion.uptake=ACCEPTED.
- Une estimation du taux sera demandée pour le montant de remboursement spécifique. Cela donnera lieu à un nouveau
- La configuration est
HISTORICAL:- Les détails CDD indiqués pour la transaction de lancement sur la commande serviront à calculer le
currencyConversion.payerAmountpour le remboursement. - Pour les remboursements partiels ou excessifs, le
currencyConversion.payerAmountprovenant de la transaction initiale sera spécifié au prorata sous la forme d'un pourcentage du montant du commerçant. Lorsqu'un prorata est appliqué, l'arrondi standard est utilisé. - Si vous utilisez des remboursements partiels pour rembourser intégralement un montant collecté, le dernier remboursement partiel contiendra le montant collecté en suspens du payeur. Cela permet de tenir compte des arrondis sur les montants partiels. Lorsque le montant remboursé total n'est pas égal au montant collecté total, aucune validation n'aura lieu sur les montants du payeur (par exemple sur des remboursements en trop).
- La réponse de transaction est
currencyConversion.uptake=ACCEPTED.
- Les détails CDD indiqués pour la transaction de lancement sur la commande serviront à calculer le
Si currencyConversion.uptake=DECLINED, NOT_AVAILABLE ou NOT_REQUIRED pour la transaction initiale :
Si l'autorisation initiale et la collecte sont correctement traitées comme transactions non-CDD et si vous soumettez une demande de remboursement ultérieure, vous obtiendrez le résultat suivant, quelle que soit votre configuration de commerçant :
- Aucune estimation du taux ne sera demandée.
- Aucun champ
currencyConversionne sera retourné sur la réponse de transaction Refund (Rembourser) ou sur l'opération Retrieve Transaction (Extraire la transaction).
Test de votre intégration CDD
Vous pouvez tester votre intégration CDD au moyen de votre profil de commerçant de test.