Étape 1 : Créer une session
En premier lieu, créez une session en soumettant à la passerelle une demande Create Session (Créer une session) de votre serveur Web. L'opération retourne un ID de session que vous pouvez utiliser pour référencer cette session.
Référence de l'API Create Session (Créer une session)[REST][NVP]
Étape 2 : Initiation de votre entente de facturation
Renseignez les champs suivants dans la demande Tokenize Browser Payment (Créer un jeton pour le paiement avec redirection) pour initier une entente de facturation et personnaliser l'expérience du payeur présentée par PayPal.
token: jeton que vous voulez créer ou mettre à jour. Les détails de l'entente sont stockés par rapport à ce jeton.
Vous ne devez renseigner ce champ que si vous êtes configuré pour la stratégie de génération de jetons « Indiqué par le commerçant ». Sinon, la passerelle crée le jeton pour vous.
sourceOfFunds.type = PAYPALsession.id: identifiant de la session de paiement (retourné dans l'étape 1) qui sera mis à jour avec le jeton contenant les détails de l'entente.sourceOfFunds.provided.paypal.billingAgreement.description: description que vous avez donnée pour l'entente de facturation PayPal. Cette description est affichée au payeur lorsqu'il est invité à approuver l'entente de facturation.sourceOfFunds.provided.paypal.billingAgreement.name: nom que vous avez donné à l'entente de facturation PayPal.sourceOfFunds.provided.paypal.billingAgreement.cardinality: indique le nombre d'ententes de facturation entre vous et ce payeur. Vous pouvez définir ce champ avec les valeurs suivantes :
MULTIPLE: indique que vous avez plusieurs ententes de facturation avec ce payeur. Cela signifie qu'une nouvelle entente sera retournée en réponse à chaque demande.SINGLE: indique que vous avez une seule entente de facturation avec ce payeur. Cela signifie que la même entente sera retournée en réponse à chaque demande.
browserPayment.returnUrl: URL vers laquelle le navigateur du payeur doit être redirigé après avoir approuvé l'entente de facturation au niveau de PayPal.browserPayment.paypal.agreementConfirmation: indique l'action que PayPal affiche au payeur avant que celui-ci ne soit redirigé vers votre site Web. Vous pouvez définir ce champ avec les valeurs suivantes :
AGREE: s'affiche en tant que « Accepter & Continuer » sur le site Web PayPal. Cela signifie que, lorsque le payeur a approuvé l'entente de facturation et son navigateur est revenu sur votre site Web, vous ne traiterez pas de paiement par rapport à cette entente de facturation à ce stade.AGREE_AND_PAY: s'affiche en tant que « Accepter & Payer » sur le site Web PayPal. Cela signifie que, lorsque le payeur a approuvé l'entente de facturation et son navigateur est revenu sur votre site Web, vous traiterez un paiement par rapport à cette entente de facturation.
browserPayment.paypal.displayShippingAddress: indique si vous souhaitez que PayPal affiche l'adresse d'expédition au payeur sur le site Web PayPal. Vous pouvez définir ce champ sur « true » ou « false ».
Par défaut, l'adresse d'expédition est affichée au payeur. Pour plus d'informations, voir Affichage/remplacement de l'adresse d'expédition.browserPayment.paypal.overrideShippingAddress: indique si vous souhaitez autoriser le payeur à modifier l'adresse d'expédition pour le paiement sur le site Web PayPal. Vous pouvez définir ce champ sur « true » ou « false ».
Par défaut, le payeur est autorisé à modifier l'adresse d'expédition. Pour plus d'informations, voir Affichage/remplacement de l'adresse d'expédition.
Après la soumission de cette demande, vous devez rediriger le navigateur du payeur vers l'URL retournée dans le champ browserPayment.redirectUrl.
Référence de l'API Tokenize Browser Payment (Créer un jeton pour le paiement avec redirection) [REST][NVP]
Exemple de demande
L'exemple ci-dessous illustre une demande Tokenize Browser Payment (Créer un jeton pour le paiement avec redirection) dans laquelle le jeton a été généré à l'aide de la stratégie de génération de jetons « Indiqué par le commerçant ».
| URL |
htt/rest/version/72/merchant/{merchantId}
|
| Méthode HTTP |
POST |
{
"apiOperation": "TOKENIZE_BROWSER_PAYMENT",
"browserPayment": {
"paypal": {
"agreementConfirmation": "AGREE_AND_PAY",
"displayShippingAddress": true,
"overrideShippingAddress": false
},
"returnUrl": "https://<return_url>"
},
"correlationId": "f4d8b752-4f68-47c6-81e7-2ee488f821a0",
"session": {
"id": "SESSION0002567768179L82204264I7"
},
"shipping": {
"address": {
"city": "<city>",
"country": "<country>",
"postcodeZip": "<post_code>",
"stateProvince": "<state>",
"street": "test1",
"street2": "test2"
},
"contact": {
"firstName": "<merchant_first_name>",
"lastName": "<merchant_last_name>"
}
},
"sourceOfFunds": {
"provided": {
"paypal": {
"billingAgreement": {
"description": "Test Billing Agreement",
"name": "Test Name",
"cardinality": "MULTIPLE"
}
}
},
"type": "PAYPAL"
},
"token": "975890899756"
}
Exemple de réponse
{
"browserPayment": {
"redirectUrl": "https://<redirect_url>"
},
"correlationId": "f4d8b752-4f68-47c6-81e7-2ee488f821a0",
"merchant": "<test_merchant_Id>",
"response": {
"gatewayCode": "NO_VERIFICATION_PERFORMED"
},
"result": "SUCCESS",
"session": {
"id": "SESSION0002567768179L82204264I7"
}
}
Récupérer les détails de la session
Le jeton, généré par la passerelle ou celui que vous avez indiqué dans la demande Tokenize Browser Payment (Créer un jeton pour le paiement avec redirection), est stocké dans une session de paiement et retourné dans la réponse Tokenize Browser Payment (Créer un jeton pour le paiement avec redirection).
Si vous êtes configuré pour les jetons générés par la passerelle, soumettez une demande Retrieve Session (Extraire la session) immédiatement en utilisant le champ session.id et obtenez la valeur retournée dans le champ sourceOfFunds.token. Si le payeur n'a pas pu mettre en place l'entente de facturation avec succès, le jeton n'est pas retourné.
Si vous êtes configuré pour les jetons indiqués par le commerçant, passez à l'étape 3 : Extraction des détails de l'entente de facturation.
Exemple de demande Retrieve Session (Extraire la session)
Un exemple de demande Retrieve Session (Extraire la session) pour un ID de session obtenu à partir de la réponse Tokenize Browser Payment (Créer un jeton pour le paiement avec redirection) où le jeton a été généré par la passerelle est illustré ci-dessous.
| URL |
htt/rest/version/72/merchant/{merchantId}/session/{sessionId}
|
| Méthode HTTP |
GET |
Exemple de réponse Retrieve Session (Extraire la session)
{
"merchant": "<test_merchant>",
"session": {
"id": "SESSION0002567768179L82204264I7",
"updateStatus": "SUCCESS",
"version": "82cbc9f602"
},
"sourceOfFunds": {
"token": "975890899756"
},
"version": "72"
}
Personnaliser votre entente de facturation sur PayPal
Pour personnaliser de manière plus précise l'expérience du payeur au niveau de PayPal, vous pouvez renseigner des paramètres supplémentaires lors de la configuration de l'entente au niveau de PayPal.
- Nom de l'entente
- Description de l'entente
- Données personnalisées du commerçant : Données d'entente spécifiques au commerçant.
- Ignorer l'adresse d'expédition : si ce paramètre est défini sur true, l'adresse d'expédition n'est pas collectée auprès du payeur au cours de l'approbation de l'entente.
- Adresse d'expédition non modifiable : Si ce paramètre est défini sur true, l'adresse d'expédition est affichée, mais est non modifiable.
- Inclure l'adresse d'expédition : vous devez autoriser le payeur à indiquer une adresse d'expédition si celle-ci est différente de l'adresse par défaut.
Assurez-vous que les champs de l'adresse d'expédition dans la demande Tokenize Browser Payment (Créer un jeton pour le paiement avec redirection) et la configuration de l'entente de facturation PayPal sont définis afin de créer l'expérience souhaitée pour le payeur au cours de l'approbation de l'entente de facturation.
Étape 3 : Extraction des détails de l'entente de facturation
Avant de procéder à un paiement au titre de l'entente de facturation, vous devez vérifier si le jeton contenant les détails de l'entente est valide. En effet, le payeur peut choisir d'annuler l'entente de facturation sur le site Web de PayPal, auquel cas l'état du jeton devient non valide. Si vous effectuez un paiement avec un jeton non valide, la transaction échouera.
Lorsque le payeur est revenu sur la page spécifiée par le champ browserPayment.returnUrl, vous pouvez soumettre une demande Retrieve Token (Extraire le jeton). Vous devez indiquer l'ID de jeton pour récupérer les détails de l'entente de facturation. Les détails suivants sont retournés si le payeur s'est inscrit avec succès à l'entente de facturation. Sinon, l'erreur « jeton non trouvé » est retournée.
sourceOfFunds.provided.paypal.billingAgreement.cardinalitysourceOfFunds.provided.paypal.billingAgreement.descriptionsourceOfFunds.provided.paypal.billingAgreement.idsourceOfFunds.provided.paypal.billingAgreement.namesourceOfFunds.provided.paypal.payerIdsourceOfFunds.provided.paypal.accountEmailsourceOfFunds.provided.paypal.accountHolder
Exemple de demande Retrieve Token (Extraire le jeton)
Un exemple de demande Retrieve Token (Extraire le jeton) pour un ID de jeton obtenu à partir de la réponse Retrieve Session (Extraire la session) ou tel qu'indiqué par vous dans la demande Tokenize Browser Payment (Créer un jeton pour le paiement avec redirection) est illustré ci-dessous.
| URL |
htt/rest/version/72/merchant/{merchantId}/token/{tokenId}
|
| Méthode HTTP |
GET |
Exemple de réponse Retrieve Token (Extraire le jeton)
{
"repositoryId": "TEST8108F6CF-6899-42",
"result": "SUCCESS",
"shipping": {
"address": {
"city": "<city>",
"country": "<country>",
"postcodeZip": "<pos_code>",
"stateProvince": "<state>",
"street": "test1",
"street2": "test2"
},
"contact": {
"firstName": "<merchant_first_name>",
"lastName": "<merchant_last_name>"
}
},
"sourceOfFunds": {
"provided": {
"paypal": {
"accountEmail": "test@test.com",
"accountHolder": "FirtName LastName",
"billingAgreement": {
"cardinality": "MULTIPLE",
"description": "Test Billing Agreement",
"id": "B-NGxIf31554266975867",
"name": "Test Name"
},
"payerId": "K4ZK9KRAXRVNA"
}
},
"type": "PAYPAL"
},
"status": "VALID",
"token": "975890899756",
"usage": {
"lastUpdated": "2019-04-03T04:49:48.029Z",
"lastUpdatedBy": "<test_merchant>",
"lastUsed": "2019-04-03T04:49:48.029Z"
},
"verificationStrategy": "NONE"
}
Étape 4 : Lancement d'un paiement par rapport à l'entente de facturation
Si l'entente de facturation es approuvée et valide, vous devez immédiatement initier un paiement par rapport à cette entente si vous avez défini le champ browserPayment.paypal.agreementConfirmation=AGREE_AND_PAY dans la demande Tokenize Browser Payment (Créer un jeton pour le paiement avec redirection).
Renseignez les champs suivants dans une demande Pay (Payer), en plus des champs standard :
sourceOfFunds.type = PAYPALsourceOfFunds.token: indiquez l'ID du jeton identifiant les détails de l'entente de facturation (comme reçu de la part de PayPal) sur la passerelle. Vous pouvez utiliser cet ID de jeton pour les paiements ponctuels et récurrents.
Vous pouvez afficher les détails de l'entente de facturation pour une transaction Authorize (Autoriser) ou Pay (Payer) en effectuant une opération Retrieve Transaction (Extraire la transaction) ou via Merchant Administration.
Exemple de demande Pay (Payer)
L'exemple ci-dessous illustre une demande de transaction Pay (Payer) utilisant le jeton qui identifie les détails de l'entente de facturation avec PayPal.
| URL |
htt/rest/version/72/merchant/{merchantId}/order/{orderid}/transaction/{transactionid}
|
| Méthode HTTP |
PUT |
{
"apiOperation": "PAY",
"order": {
"amount": "123.46",
"currency": "USD",
"description": "Quantity description",
"item": [
{
"name": "name",
"quantity": "40",
"sku": "sku",
"unitPrice": "2.8"
}
],
"itemAmount": "112.00",
"tax": [
{
"amount": "0.29",
"rate": "9.77"
}
],
"taxAmount": "11.46"
},
"shipping": {
"address": {
"city": "<city>",
"country": "<country>",
"postcodeZip": "<pos_code>",
"stateProvince": "<state>",
"street": "test1",
"street2": "test2"
},
"contact": {
"email": "test@test.com",
"firstName": "FirstName"
}
},
"sourceOfFunds": {
"token": "975890899756"
}
}
