- Directives d'intégration
- Fonctionnalités prises en charge (Modes de paiement)
- Mise en œuvre d'une intégration des paiements avec redirection
- PayPal
- Intégration de la passerelle avec le SDK PayPal JS
Intégration de la passerelle avec le SDK PayPal JS
Ce guide décrit comment ajouter le bouton intelligent PayPal à votre page de paiement par une intégration avec le SDK JavaScript PayPal fourni par la passerelle.
Conditions préalables
Pour proposer le bouton intelligent PayPal comme option de paiement à vos payeurs en utilisant le SDK JavaScript PayPal de la passerelle :
- Assurez-vous que votre your payment service provider a activé PayPal sur votre profil de commerçant.
- Dans le menu Admin, dans Merchant Administration, cliquez sur Configuration PayPal et suivez les instructions pour intégrer et activer l'option PayPal pour votre profil de commerçant. Vous devez disposer du privilège requis pour mettre à jour votre configuration PayPal.
Ajouter un bouton intelligent à l'aide du SDK JavaScript PayPal de la passerelle
Suivez les étapes décrites ci-dessous pour créer votre intégration avec le SDK JavaScript PayPal de la passerelle
Étape 1 : Créer une session
Le SDK JavaScript PayPal de la passerelle utilise l'authentification basée sur la session. Créez une session pour mettre à jour les champs de demande et les valeurs que vous souhaitez stocker.
Pour créer une session, soumettez la demande Create Session (Créer une session) à partir de votre application côté serveur. La réponse retourne un ID de session que vous devez utiliser dans les étapes suivantes pour référencer cette session.
| URL | https://ap-gateway.mastercard.com/api /rest/version/72/merchant/<your_gateway_merchant_ID>/session |
| Méthode HTTP | POST |
Étape 2 : Mettre à jour la session avec les détails de paiement de la commande, de la transaction et du paiement avec redirection
Mettez à jour la session avec le montant et la devise de la commande en soumettant une demande Update Session (Mettre à jour la session) à partir de votre application côté serveur.
Mettez la session à jour avec au moins l'ID de commande, l'ID de transaction, le montant de la commande, la devise et les détails du paiement avec redirection (confirmation du paiement) en soumettant une demande Update Session (Mettre à jour la session) à partir de votre application côté serveur.
browserPayment.returnUrl est facultatif car il n'est pas requis pour afficher le bouton intelligent PayPal pour que l'interaction fonctionne.| URL | https://ap-gateway.mastercard.com/api /rest/version/72/merchant/<your_gateway_merchant_ID>/session>/<your_session_ID> |
| Méthode HTTP | PUT |
{
"apiOperation": "UPDATE_SESSION",
"browserPayment": {
"operation": "PAY",
"paypal": {
"paymentConfirmation": "CONFIRM_AT_PROVIDER"
}
},
"order": {
"amount": "679.99",
"currency": "USD"
},
"sourceOfFunds": {
"type": "PAYPAL"
}
}
Étape 3 : Inclure le SDK JS PayPal de la passerelle dans votre page de paiement
Incluez le SDK JavaScript PayPal de la passerelle (gateway-paypal.js) dans votre page de paiement en ajoutant un élément script dans l'élément de tête. Cela place l'objet GatewayPaypal dans l'espace de noms de la fenêtre.
<script type="text/javascript" src="https://ap-gateway.mastercard.com/static/gateway-paypal/1.2.0/gateway-paypal.min.js"></script>
Étape 4 : Configurer l'interaction de la passerelle PayPal
Lors du chargement de votre page de paiement, lancez l'interaction PayPal en appelant GatewayPaypal.configure (config, errorCallback, completeCallback, cancelCallback). Cela redirigera votre page de paiement vers configure.html de la méthode PayPal de la passerelle.
function errorCallback(error) {
};
function completeCallback(response) {
};
function cancelCallback(response) {
};
var config = {
merchantId: '<your_gateway_merchant_ID>', // required
orderId: '<order_ID>',//required and must match the value provided in Step 2
transactionId: '<transaction id>',// required and must match the value provided in Step 2
sessionId: '<your_session_ID>',// required
currency: '<order_currency>', // required
paymentConfirmation: '<confirmation_of_payment>', // optional, must be one of CONFIRM_AT_PROVIDER (if you want the payer to commit to the payment on the PayPal website) or CONFIRM_AT_MERCHANT (if you want the payer to commit to the payment on your website). If not provided, the value is defaulted to "CONFIRM_AT_PROVIDER".
operation: '<type_of_transaction>', // required, must be one of AUTHORIZE (transaction created in the gateway is an AUTHORIZATION transaction) or PAY (transaction created in the gateway is a PAYMENT transaction). For a successful Authorization transaction, submit a CAPTURE request to move the funds from the payer's account to your account.
apiVersion: '',// optional, Must be version 60 or above. If not provided, the value is defaulted to 60.
buttonElement: '',// required
style: {// Style options for customizing the PayPal Smart Button.
color: '<color_of_the_button>', // optional, must be one of "gold" (Recommended by PayPal), "blue", "silver", "white", "black"
shape: '<shape_of_the_button>', // optional, must be one of "rect", "pill". If not provided, the value is defaulted to "rect".
label: '<label_on_the_button>', // optional, must be one of "paypal", "checkout", "buynow", "pay". If not provided, the value is defaulted to "paypal".
tagline: '<tagline_to_be_displayed>', // optional, must be one of "true", "false". If not provided, the value is defaulted to "true".
size: '<size_of_the_button>' // optional. If not provided, the value is defaulted to the size of its container element. To customize the button width, alter the width of the container element. To customize the button height, set the height option to a value from 25 to 55.
}
};
GatewayPaypal.configure(config, errorCallback, completeCallback, cancelCallback);
merchantId
Le champ merchantId est requis afin que la passerelle puisse correctement déterminer vos options de paiement.
apiVersion
Le SDK apiVersion doit correspondre à la version que vous utilisez lors de la soumission de la demande Create Session (Créer une session) Par exemple, lors de la création d'une session, si vous utilisez apiVersion 61, vous devez vous assurer d'utiliser la même version apiVersion pour toutes les autres configurations qui lui sont liées. Entre cas de discordance entre les versions apiVersion, l'opération échouera.
apiVersion sur config() est 61. Si vous n'indiquez pas de valeur pour apiVersion, la valeur par défaut est prise en compte.buttonElement
Détermine la position du bouton sur la page. Il s'agit d'un identifiant de l'élément DOM où le bouton est affiché.
paymentConfirmation
Indique à quel endroit du processus de paiement vous souhaitez que le payeur valide le paiement ; cela peut avoir lieu sur votre site Web ou sur PayPal.
Réponses d'erreur
L'appel GatewayPaypal.configure() peut retourner les réponses d'erreur suivantes.
| response.cause | resp.explanation | Action requise |
|---|---|---|
| Erreur | Argument manquant : Merchant ID, Hosted Session ID, Payment Confirmation, Button Element et trois fonctions de rappel sont tous des arguments requis pour la méthode configure(). | Corrigez votre intégration. Renseignez tous les champs de demande obligatoires. |
| Erreur |
|
Corrigez votre intégration en indiquant des fonctions correctes. |
| Erreur | La version de l'API doit être <MIN_VERSION> ou une version ultérieure. | Corrigez votre intégration. Définissez apiVersion sur 60 ou une version ultérieure. |
Confirmation de paiement
Avec les flux de paiement Commander avec PayPal et Payer avec PayPal, vous pouvez choisir d'afficher le bouton Payer maintenant ou Continuer au niveau de PayPal.
Confirmation du paiement au niveau de PayPal
En soumettant CONFIRM_AT_PROVIDER, le bouton Payer maintenant est affiché sur la fenêtre modale de PayPal. Le bouton Payer maintenant permet au payeur de confirmer le paiement sur la fenêtre modale PayPal. Cette option vous permet de proposer au payeur une expérience de paiement plus rapide, car le payeur effectue le paiement sur le site PayPal.
Si le payeur valide le paiement sur le site PayPal, vous pouvez soumettre la demande Retrieve Transaction (Extraire la transaction) ou Retrieve Order (Extraire la commande) à la passerelle afin de vérifier le résultat de la transaction. Vous pouvez ensuite afficher la page Paiement terminé avec les derniers détails.
Decline Recovery (Refuser la récupération)
L'opération Decline Recovery (Refuser la récupération) est prise en charge uniquement avec PayPal. Au cours du processus de la transaction, si l'instrument est refusé, le payeur obtient deux autres tentatives pour effectuer le paiement. Pour les trois tentatives, un payeur peut utiliser le même instrument ou tout autre instrument enregistré auprès de PayPal pour procéder au paiement. S'il s'agit d'un nouvel instrument, le payeur doit l'enregistrer auprès de PayPal avant de procéder au paiement. Le payeur bénéficie de trois tentatives au total pour effectuer le paiement. Si, même après la troisième tentative, l'instrument est refusé, votre your payment service provider enverra la réponse TRANSACTION_REFUSED ou INSTRUMENT_DECLINED. Le payeur ne pourra alors pas poursuivre le processus de la transaction.
Séquence d'événements au cours de l'opération Decline Recovery (Refuser la récupération)
- Soumettez la demande Initiate Browser Payment (Lancer un paiement avec redirection) à la passerelle avec browserPayment.paypal.paymentconfirmation = CONFIRM_AT_PROVIDER.
Le formulaire de paiement PayPal s'affiche.
- Un payeur se connecte au formulaire de paiement PayPal, sélectionne l'instrument de paiement, puis clique sur Payer maintenant.
- Soumettez la demande Confirm Browser Payment (Confirmer le paiement avec redirection) pour appeler la demande Execute Payment (Exécuter le paiement) de PayPal.
- Si l'instrument est refusé, PayPal envoie la réponse
INSTRUMENT_DECLINEDà la demande Execute Payment (Exécuter le paiement).Le payeur bénéficie de trois tentatives au total pour effectuer le paiement.
- Une fois la réponse INSTRUMENT_DECLINED reçue par le gestionnaire d'événements onApprove, appelez la fonction actions.restart() pour permettre au payeur de choisir un instrument différent.
const restartPaymentOnInstrumentDeclined = (resp, actions) => {
if (isInstrumentDeclined(resp)) {
return actions.restart();
} else {
gatewaySuccessCallbackBP(resp);
}
}
{
"browserPayment": {
"interaction": {
"status": "INITIATED",
"timeInitiated": "2021-07-15T07:10:16.176Z"
},
"operation": "PAY",
"paypal": {
"displayShippingAddress": true,
"interactionId": "EC-9SH774983H4356451",
"overrideShippingAddress": true,
"paymentConfirmation": "CONFIRM_AT_PROVIDER"
}
},
"gatewayEntryPoint": "WEB_SERVICES_API",
"merchant": "PP_POI_1",
"order": {
"amount": 931,
"chargeback": {
"amount": 0,
"currency": "USD"
},
"creationTime": "2021-07-15T07:10:16.152Z",
"currency": "USD",
"id": "vcc-206",
"item": [
{
"brand": "MC",
"category": "NA",
"detail": {
"unitDiscountRate": 0
},
"name": "name",
"quantity": 1,
"sku": "sku",
"unitDiscountAmount": 0,
"unitPrice": 931
}
],
"itemAmount": 931,
"lastUpdatedTime": "2021-07-15T07:12:19.571Z",
"merchantAmount": 931,
"merchantCurrency": "USD",
"reference": "my order",
"status": "INITIATED",
"taxAmount": 0,
"totalAuthorizedAmount": 0,
"totalCapturedAmount": 0,
"totalDisbursedAmount": 0,
"totalRefundedAmount": 0
},
"response": {
"acquirerCode": "INSTRUMENT_DECLINED",
"acquirerMessage": "",
"debugInformation": "INSTRUMENT_DECLINED, The instrument presented was either declined by the processor or bank, or it can't be used for this payment., e5a837ee6834",
"gatewayCode": "SUBMITTED"
},
"result": "SUCCESS",
"shipping": {
"address": {
"city": "Los Angeles",
"company": "Google",
"country": "USA",
"postcodeZip": "90001",
"stateProvince": "CA",
"street": "2nd Main",
"street2": "lane 2"
},
"contact": {
"email": "ramakanth@gmail.com",
"firstName": "Ramakanth",
"lastName": "Kulkarni",
"mobilePhone": "9999999999",
"phone": "9999999999"
}
},
"sourceOfFunds": {
"provided": {
"paypal": {
"accountEmail": "CCREJECT-REFUSED@paypal.com",
"accountHolder": "Paul Levetsky",
"payerId": "LM9AM5Y34N3X8"
}
},
"type": "PAYPAL"
},
"timeOfLastUpdate": "2021-07-15T07:12:19.571Z",
"timeOfRecord": "2021-07-15T07:10:16.171Z",
"transaction": {
"acquirer": {
"date": "15 Jul 2021",
"id": "PAYPAL",
"merchantId": "NDXE9MFKNPCUA",
"time": "07:12:19"
},
"amount": 931,
"currency": "USD",
"id": "1",
"source": "INTERNET",
"stan": "0",
"type": "PAYMENT",
"update": [
{
"gatewayCode": "SUBMITTED",
"time": "2021-07-15T07:10:17.280Z"
}
]
},
"version": "62"
}
{
"browserPayment": {
"interaction": {
"status": "COMPLETED",
"timeCompleted": "2021-07-20T09:17:27.128Z",
"timeInitiated": "2021-07-20T09:15:56.313Z"
},
"operation": "PAY",
"paypal": {
"displayShippingAddress": true,
"interactionId": "EC-74C02380KE247305K",
"overrideShippingAddress": true,
"paymentConfirmation": "CONFIRM_AT_PROVIDER"
}
},
"gatewayEntryPoint": "WEB_SERVICES_API",
"merchant": "PP_POI_1",
"order": {
"amount": 1.28,
"chargeback": {
"amount": 0,
"currency": "USD"
},
"creationTime": "2021-07-20T09:15:56.278Z",
"currency": "USD",
"description": "Ordered goods",
"id": "testsdkhco33",
"item": [
{
"brand": "MC",
"category": "NA",
"name": "name",
"quantity": 1,
"sku": "sku",
"unitPrice": 1.28
}
],
"itemAmount": 1.28,
"lastUpdatedTime": "2021-07-20T09:17:27.136Z",
"merchantAmount": 1.28,
"merchantCurrency": "USD",
"reference": "my order",
"status": "FAILED",
"taxAmount": 0,
"totalAuthorizedAmount": 0,
"totalCapturedAmount": 0,
"totalDisbursedAmount": 0,
"totalRefundedAmount": 0
},
"response": {
"acquirerCode": "TRANSACTION_REFUSED",
"acquirerMessage": "",
"debugInformation": "TRANSACTION_REFUSED, The request was refused, cae635b964420",
"gatewayCode": "DECLINED"
},
"result": "FAILURE",
"shipping": {
"address": {
"city": "Los Angeles",
"country": "USA",
"postcodeZip": "90001",
"stateProvince": "CA",
"street": "2nd Main",
"street2": "lane 2"
},
"contact": {
"firstName": "Ramakanth",
"lastName": "Kulkarni"
}
},
"sourceOfFunds": {
"provided": {
"paypal": {
"accountEmail": "CCREJECT-REFUSED@paypal.com",
"accountHolder": "Paul Levetsky",
"payerId": "LM9AM5Y34N3X8"
}
},
"type": "PAYPAL"
},
"timeOfLastUpdate": "2021-07-20T09:17:27.136Z",
"timeOfRecord": "2021-07-20T09:15:56.308Z",
"transaction": {
"acquirer": {
"date": "20 Jul 2021",
"id": "PAYPAL",
"merchantId": "NDXE9MFKNPCUA",
"time": "09:17:27"
},
"amount": 1.28,
"currency": "USD",
"id": "1",
"source": "INTERNET",
"stan": "0",
"type": "PAYMENT",
"update": [
{
"gatewayCode": "SUBMITTED",
"time": "2021-07-20T09:15:57.482Z"
},
{
"gatewayCode": "DECLINED",
"time": "2021-07-20T09:17:27.128Z"
}
]
},
"version": "62"
}
Confirmation du paiement sur le site de votre boutique
En soumettant CONFIRM_AT_MERCHANT, le bouton Continuer s'affiche sur la fenêtre modale de PayPal.
Le bouton Continuer permet au payeur d'être redirigé vers le site de votre magasin pour confirmer le paiement après avoir terminé l'interaction avec la fenêtre modale PayPal. Cette option vous permet de modifier la commande si nécessaire avant d'accepter le paiement (par exemple pour ajouter des frais d'expédition et de traitement en fonction de l'adresse retournée par PayPal).
Si le payeur valide le paiement sur votre site, c'est-à-dire qu'il utilise CONFIRM_AT_MERCHANT en tant que confirmation de paiement, la page de confirmation de paiement sera affichée au payeur. Vous pouvez soumettre une demande Retrieve Transaction (Extraire la transaction) ou Retrieve Order (Extraire la commande) à la passerelle pour vérifier le résultat de la transaction. Lorsque le payeur décide de procéder au paiement, vous devez soumettre une demande CONFIRM_BROWSER_PAYMENT à la passerelle pour finaliser le paiement. Vous pouvez ensuite afficher la page Paiement terminé avec les derniers détails. Vous pouvez utiliser cette opération pour mettre à jour les attributs du paiement, tels que les frais d'expédition, de manière à refléter les détails d'expédition sélectionnés par le payeur dans l'interface utilisateur de PayPal.
{
"apiOperation": "CONFIRM_BROWSER_PAYMENT",
"order": {
"amount": "779.99",
"currency": "USD",
"shippingAndHandlingAmount": "100.00"
}
}
Récupération des détails de la transaction
Vous pouvez extraire les détails de la transaction pour l'interaction PayPal à l'aide des options suivantes :
- Opérations Retrieve Transaction (Extraire la transaction) ou Retrieve Order (Extraire la commande)
- Recherche de commandes et de transactions dans Merchant Administration : utilisez le numéro de référence indiqué au payeur sur le reçu de paiement pour voir les détails de la transaction. Le numéro de référence sera indiqué au payeur et sur votre relevé bancaire. Cela permet une validation supplémentaire de la transaction.
Comprendre le statut de la commande et de la transaction
browserPayment.paypal.paymentConfirmation est CONFIRM_AT_PROVIDER
| État de l'interaction de paiement avec redirection | Code de réponse de la passerelle de la transaction | Statut de la commande | Description |
|---|---|---|---|
| browserPayment.interaction.status=INITIATED | response.gatewayCode=SUBMITTED | order.status=INITIATED | Vous avez soumis la transaction à l'aide de l'opération INITIATE_BROWSER_PAYMENT. |
| browserPayment.interaction.status=COMPLETED | response.gatewayCode=APPROVED | order.status=CAPTURED | Le payeur a cliqué sur Payer maintenant et la demande CONFIRM_BROWSER_PAYMENT est soumise. |
INSTRUMENT_DECLINED et le statut de response.gatewayCode sera SUBMITTED et celui de order.status sera INITIATED. Ce statut restera identique si l'instrument est refusé lors des deux premières tentatives de paiement. Si l'instrument est également refusé lors de la troisième tentative, la transaction sera refusée et les statuts de la réponse .gatewayCode et de order.status deviendront respectivement DECLINED et FAILED.browserPayment.paypal.paymentConfirmation est CONFIRM_AT_MERCHANT
| État de l'interaction de paiement avec redirection | Code de réponse de la passerelle de la transaction | Statut de la commande | Description |
|---|---|---|---|
| browserPayment.interaction.status=INITIATED | response.gatewayCode=SUBMITTED | order.status=INITIATED | Vous avez soumis la transaction à l'aide de l'opération INITIATE_BROWSER_PAYMENT. |
| browserPayment.interaction.status=RETURNED_TO_MERCHANT | response.gatewayCode=SUBMITTED | order.status=INITIATED | Le payeur a cliqué sur le bouton Continuer dans PayPal et l'opération UPDATE_BROWSER_PAYMENT est soumise. |
| browserPayment.interaction.status=COMPLETED | response.gatewayCode=APPROVED | order.status=CAPTURED | Vous avez soumis l'opération CONFIRM_BROWSER_PAYMENT. |
Test de votre intégration
Lorsque vous avez terminé votre intégration avec la passerelle pour PayPal, vous pouvez la tester en utilisant la sandbox PayPal.
Pour commencer le test, créez un compte PayPal et utilisez ces informations lors de la configuration de votre profil du commerçant auprès de votre your payment service provider. Assurez-vous d'utiliser le commerçant non-TEST pour ce type de transaction.
- Utilisez votre profil du commerçant créé dans la sandbox PayPal.
- Suivez les étapes ci-dessus pour l'intégration.
- Assurez-vous d'avoir configuré l'intégration PayPal dans Merchant Administration et d'avoir accordé à un tiers l'autorisation d'effectuer des transactions en votre nom.