Présentation > Modes de paiement > PayPal >

Intégration directe avec le SDK PayPal JS

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 directe avec le SDK PayPal JS

Intégration directe avec le SDK PayPal JS

Ce guide décrit comment ajouter bouton intelligent PayPal à votre page de paiement par une intégration directe du SDK JavaScript de PayPal.

Conditions préalablesCopied to Clipboard

Pour proposer le bouton intelligent PayPal comme option de paiement à vos payeurs en utilisant le SDK JavaScript de PayPal :

Assurez-vous que votre your payment service provider dispose d'un compte PayPal et a créé une application avec son compte PayPal. Votre Your payment service provider doit avoir reçu l'ID de client de PayPal et l'avoir stocké dans votre profil du commerçant dans Merchant Manager.
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.

Flux d'informationsCopied to Clipboard

Les étapes suivantes décrivent le flux d'informations d'une intégration directe avec le SDK JS PayPal :

Le payeur clique sur le bouton intelligent PayPal sur votre page de paiement.
Javascript dans le navigateur du payeur envoie une requête à votre serveur.
Votre serveur effectue l'opération Initiate Browser Payment (Lancer un paiement avec redirection) sur la passerelle pour lancer le processus de paiement avec PayPal.
La passerelle retourne l'ID d'interaction de PayPal à votre serveur.
Votre serveur retourne l'ID d'interaction au Javascript qui s'exécute dans le navigateur du payeur.
Le navigateur du payeur affiche alors l'interface utilisateur PayPal.
Le Javascript dans le navigateur du payeur interagit avec votre serveur pour procéder au processus de paiement.
Votre serveur effectue l'opération Confirm Browser Payment (Confirmer le paiement avec redirection) sur la passerelle pour effectuer le paiement.

Ajoutez un bouton intelligent à l'aide du SDK JavaScript de PayPalCopied to Clipboard

Suivez les étapes décrites ci-dessous pour créer votre intégration avec le SDK JavaScript de PayPal.

Étape 1 : Obtenir l'identifiant client

Obtenez l'ID de client en soumettant la demande Payment Options Inquiry (Demande d'options de paiement) à la passerelle. La réponse retourne un ID de client que vous devez utiliser dans les étapes suivantes.

Exemple de demande


https://<your_host_name>/api/rest/version/<api_version>/merchant/<your_gateway_merchantId>/paymentOptionsInquiry

Exemple de réponse


{
    "merchant": "TESTPP_V2_MER33;",
    "paymentTypes": {
        "paypal": {
            "currencies": [
                {
                    "currency": "AUD"
                },
            ],
            "transactionSources": [
                {
                    "transactionSource": "INTERNET"
                }
            ]
            "clientId": "ARLDC7ynAfGNlnJy8PuLanMRQvteg9RsfxAMLK-43amD5_urCn0Jl1APryAyWEvIm_GY1ippISEwsoza",
            "accountId": "RMU2YU3VN8SUL"
        }
    },
    "result": "SUCCESS",
    "supportedPaymentOperations": [
        {
           "supportedPaymentOperation": "AUTHORIZE"
        }
    ]
}

Étape 2 : Ajoutez le SDK JavaScript PayPal à votre page Web

Pour activer la fonctionnalité de bouton intelligent PayPal, ajoutez le SDK JavaScript PayPal à votre page Web. Utilisez l'ID de client que vous avez reçu dans la réponse à la demande Payment Options Inquiry (Demande d'options de paiement) à l'étape 1 comme valeur du paramètre de la demande d'ID de client.

Exemple de code HTML



<!DOCTYPE html>

<head>
    <meta name="viewport" content="width=device-width, initial-scale=1"> 
    <meta http-equiv="X-UA-Compatible" content="IE=edge" /> 
</head>

<body>
<script src="https://www.paypal.com/sdk/js?client-id=PayPal_CLIENT_ID and merchant-id=PayPal_MERCHANT_ID">
</script>
</body>

Pour plus d'informations sur cette étape, reportez-vous à l'étape 2 du guide du développeur PayPal.

Étape 3 : Afficher le bouton intelligent PayPal sur votre page Web

Pour afficher le bouton intelligent PayPal sur votre page Web, ajoutez le code ci-dessous à votre page Web. Utilisez l'ID de client que vous avez reçu dans la réponse à la demande Payment Options Inquiry (Demande d'options de paiement) à l'étape 1.

Exemple


<body>

  <script src="https://www.paypal.com/sdk/js?client-id=PayPal_CLIENT_ID and merchant-id=PayPal_MERCHANT_ID">
  </script>

        <div id="paypal-button-container"></div>

  <script>
          paypal.Buttons().render('#paypal-button-container'); // This function displays Smart Payment Buttons on your web page.
  </script>

</body>

Pour plus d'informations sur cette étape, reportez-vous à l'étape 3 du guide du développeur PayPal.

Étape 4 : Configurer une transaction

Vous devez définir le rappel createOrder pour informer votre hôte de soumettre la demande Initiate Browser Payment (Lancer un paiement avec redirection) à la passerelle. Pour configurer une transaction depuis votre serveur ou client, voir la rubrique Configurer une transaction du guide du développeur PayPal.

La séquence des événements diffère en fonction du flux de paiement PayPal.

Pour un paiement avec PayPal, voir la rubrique Séquence des événements au cours d'un paiement avec PayPal.
Pour une opération Pay (Payer) avec PayPal, voir la rubrique Séquence des événements au cours d'une opération Pay (Payer) avec PayPal.

Séquence des événements au cours d'un paiement avec PayPal

Soumettez la demande Initiate Browser Payment (Lancer un paiement avec redirection) à la passerelle avec browserPayment.paypal.paymentconfirmation = CONFIRM_AT_MERCHANT.

Exemple de demande


{
  "apiOperation": "INITIATE_BROWSER_PAYMENT",
  "browserPayment": {
    "operation": "PAY",
    "paypal": {
      "paymentConfirmation": "CONFIRM_AT_MERCHANT"
    }
  },
  "order": {
    "amount": "679.99",
    "currency": "USD"
  },
  "sourceOfFunds": {
    "type": "PAYPAL"
  }
}

Exemple de réponse


"browserPayment.paypal.interactionId": "EC-8AT72418NV353182U"

Implémentez un gestionnaire de rappel qui est appelé lorsqu'un payeur clique sur le bouton intelligent PayPal (affiché sous la forme createOrderCallbackHandler dans l'exemple de l'étape 4). Ce gestionnaire doit interagir avec votre serveur pour soumettre la demande Initiate Browser Payment (Lancer un paiement avec redirection) à la passerelle.

Soumettez la demande Initiate Browser Payment (Lancer un paiement avec redirection) depuis votre serveur, puis retournez browserPayment.paypal.interactionId.

La réponse Initiate Browser Payment (Lancer un paiement avec redirection) contient un jeton de paiement express dans le champ browserPayment.paypal.interactionId.

Exemple de demande


createOrder: function() {
  return fetch('/my-server/create-paypal-transaction', {
    method: 'post',
    headers: {
      'content-type': 'application/json'
    }
  }).then(function(res) {
    return res.json();
  }).then(function(data) {
    return data.interactionId; // Return the interactionId as provided by the gateway to your server
  });
}

Le JavaScript PayPal récupère le formulaire de paiement de PayPal, puis l'affiche sur le navigateur du payeur.
Le payeur se connecte à PayPal et soumet les détails de paiement à PayPal.
Enregistrez le gestionnaire onApprove avec PayPal.

Une fois la transaction réussie dans l'interface utilisateur PayPal, le gestionnaire onApprove est appelé. Soumettez alors la demande Update Browser Payment (Mettre à jour le paiement avec redirection) depuis votre serveur à la passerelle afin d'obtenir les derniers détails du paiement.

Gestionnaire approveCallback


onApprove: function (data, actions) {

    // CALL TO UPDATE_BROWSER_PAYMENT from your server;

};

Exemple de demande Update Browser Payment (Mettre à jour le paiement avec redirection)


//URL
https://<your_host_name>/api/rest/version/latest/merchant/<your_merchant_id>/transaction/151109242cvbnv
//Body
{ "apiOperation": "UPDATE_BROWSER_PAYMENT" }

Exemple de réponse Update Browser Payment (Mettre à jour le paiement avec redirection)


{
  "device": {
    "browser": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/83.0.4103.116 Safari/537.36",
    "ipAddress": "66.159.204.102"
  },
  "gatewayEntryPoint": "WEB_SERVICES_API",
  "merchant": "TESTMAN1234",
  "order": {
    "amount": 679.99,
    "chargeback": {
      "amount": 0,
      "currency": "USD"
    },
    "creationTime": "2020-09-17T09:38:41.924Z",
    "currency": "USD",
    "id": "421d49456789012345678909234527890",
    "lastUpdatedTime": "2020-09-17T09:40:11.894Z",
    "merchantAmount": 679.99,
    "merchantCurrency": "USD",
    "status": "CAPTURED",
    "totalAuthorizedAmount": 679.99,
    "totalCapturedAmount": 679.99,
    "totalRefundedAmount": 0
  },
  "response": {
    "acquirerCode": "Success",
    "gatewayCode": "APPROVED"
  },
  "result": "SUCCESS",
  "shipping": {
    "address": {
      "city": "Market City",
      "country": "AUS",
      "postcodeZip": "4322",
      "stateProvince": "Queensland",
      "street": "35 Rainbow street",
      "street2": "Floor 5, Apartment 34"
    },
    "contact": {
      "firstName": "John",
      "lastName": "Smith",
      "phone": "0745231111"
    }
  },
  "timeOfLastUpdate": "2020-09-17T09:40:11.894Z",
  "timeOfRecord": "2020-09-17T09:38:41.945Z",
  "transaction": {
    "acquirer": {
      "date": "2020-09-17",
      "id": "PAYPAL",
      "merchantId": "m.m@g.com",
      "time": "09:40:11",
      "transactionId": "SVE2APDYOXKMA7RY0"
    },
    "amount": 679.99,
    "currency": "USD",
    "id": "151109242cvbnv",
    "receipt": "SVE2APDYOXKMA7RY0",
    "source": "INTERNET",
    "stan": "0",
    "type": "PAYMENT",
    "update": [
      {
        "gatewayCode": "SUBMITTED",
        "time": "2020-09-17T09:38:42.054Z"
      },
      {
        "gatewayCode": "APPROVED",
        "time": "2020-09-17T09:40:11.896Z"
      }
    ]
  },
  "version": "59"
}

En cas de modification du montant en raison d'une modification du montant d'expédition, vous affichez le montant delta au payeur.

Une fois le paiement confirmé par le payeur, soumettez la demande CONFIRM_BROWSER_PAYMENT (Confirmer le paiement avec redirection) pour finaliser la transaction.

Exemple de demande


{
    "apiOperation": "CONFIRM_BROWSER_PAYMENT",
    "order": {
        "amount": "779.99", // amount updated as a result of updated shipping and handling charges
        "shippingAndHandlingAmount": "100.00" // updated shipping and handling charges
        ...
    }
}

L'opération Decline Recovery (Refuser la récupération) n'est pas prise en charge dans CONFIRM_AT_MERCHANT (c'est-à-dire, Commander avec PayPal).

Séquence des événements au cours d'une opération Pay (Payer) avec PayPal

Soumettez la demande Initiate Browser Payment (Lancer un paiement avec redirection) à la passerelle avec browserPayment.paypal.paymentconfirmation = CONFIRM_AT_PROVIDER.

Exemple de demande


{
  "apiOperation": "INITIATE_BROWSER_PAYMENT",
  "browserPayment": {
    "operation": "PAY",
    "paypal": {
      "paymentConfirmation": "CONFIRM_AT_PROVIDER"
    }
  },
  "order": {
    "amount": "679.99",
    "currency": "USD"
  },
  "sourceOfFunds": {
    "type": "PAYPAL"
  }
}

Exemple de réponse


"browserPayment.paypal.interactionId": "EC-8AT72418NV353182U"

Implémentez le rappel createOrder dans le code du bouton intelligent PayPal Lorsqu'un payeur clique sur le bouton intelligent PayPal, PayPal exécutera ce code.

Soumettez la demande Initiate Browser Payment (Lancer un paiement avec redirection), depuis votre serveur, puis retournez browserPayment.paypal.interactionId.

La réponse Initiate Browser Payment (Lancer un paiement avec redirection) contient le champ browserPayment.paypal.interactionId.

Exemple


createOrder: function() {
  return fetch('/my-server/create-paypal-transaction', {
    method: 'post',
    headers: {
      'content-type': 'application/json'
    }
  }).then(function(res) {
    return res.json();
  }).then(function(data) {
    return data.interactionId; // Return the interactionId as provided by the gateway to your server
  });
}

Le JavaScript PayPal récupère le formulaire de paiement de PayPal, puis l'affiche sur le navigateur du payeur.
Le payeur se connecte à PayPal et soumet les détails de paiement à PayPal.
Enregistrez le gestionnaire onApproveCallback avec PayPal.
Une fois la transaction réussie dans l'interface utilisateur PayPal, le gestionnaire onApprove est appelé. Soumettez alors la demande CONFIRM_BROWSER_PAYMENT (Confirmer le paiement avec redirection) depuis votre serveur à la passerelle pour finaliser le paiement.
Gestionnaire approveCallback
```
onApprove: function (data, actions) {

    // CALL TO CONFIRM_BROWSER_PAYMENT from your server;
};
        
```
Exemple de demande
```
{
    "apiOperation": "CONFIRM_BROWSER_PAYMENT"
}
        
```
(Facultatif) 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. Pour plus d'informations, voir Decline Recovery (Refuser la récupération).

Pour prendre en charge DECLINE_RECOVERY, vous devez exécuter action.restart().

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.

L'opération Decline Recovery (Refuser la récupération) n'est pas prise en charge dans CONFIRM_AT_MERCHANT (Commander avec PayPal).

action.restart()


const restartPaymentOnInstrumentDeclined = (resp, actions) => {
  if (isInstrumentDeclined(resp)) {
    return actions.restart();
  } else {
    gatewaySuccessCallbackBP(resp);
  }
}

INSTRUMENT_DECLINED



{
  "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": "johnsmith@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"
}

TRANSACTION_REFUSED



{
  "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"
}

Test de votre intégrationCopied to Clipboard

Lorsque vous avez terminé votre intégration avec 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 ces transactions.

Suivez les étapes ci-dessus pour l'intégration.
Assurez-vous de soumettre la demande Payment Options Inquiry (Demande d'options de paiement) pour recevoir l'ID de client de votre your payment service provider dans la réponse.
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.

Intégration directe avec le SDK PayPal JS

Conditions préalables Copied to Clipboard

Flux d'informations Copied to Clipboard

Ajoutez un bouton intelligent à l'aide du SDK JavaScript de PayPal Copied to Clipboard

Étape 1 : Obtenir l'identifiant client

Étape 2 : Ajoutez le SDK JavaScript PayPal à votre page Web

Étape 3 : Afficher le bouton intelligent PayPal sur votre page Web

Étape 4 : Configurer une transaction

Séquence des événements au cours d'un paiement avec PayPal

Séquence des événements au cours d'une opération Pay (Payer) avec PayPal

Decline Recovery (Refuser la récupération)

Séquence d'événements au cours de l'opération Decline Recovery (Refuser la récupération)

Test de votre intégration Copied to Clipboard

SUR CETTE PAGE

Conditions préalablesCopied to Clipboard

Flux d'informationsCopied to Clipboard

Ajoutez un bouton intelligent à l'aide du SDK JavaScript de PayPalCopied to Clipboard

Test de votre intégrationCopied to Clipboard