Documentation
Documentation
Payment Page

1Introduction

Pour créer un paiement via la plateforme, vous avez le choix entre la payment page integration, où le client est redirigé vers notre page de paiement, la iframe integration, où le formulaire de paiement est placé dans un iframe à l’aide de notre intégration JavaScript, ou la lightbox integration, afin d’obtenir une intégration transparente et conforme à la norme PCI DSS dans votre checkout.

Le processus de la page de paiement est le suivant (simplifié) :

  1. Créez un transaction object via notre API.

  2. Demandez l’URL de la page de paiement.

  3. Redirigez l’utilisateur vers la page de paiement.

  4. Traitez la requête webhook entrante pour autoriser la transaction dans l’application du marchand.

2Interactions entre les systèmes

Intégration de la page de paiement
Figure 1. Diagramme de séquence de l’intégration de la page de paiement

3Détails de l’intégration de la page de paiement

Avant de commencer l’intégration de la page de paiement, vous devriez :

  1. Créer un compte et vous inscrire.

  2. Créer un utilisateur d’application sous Account > Utilisateurs > Utilisateur d’application.

  3. Apprendre à vous authentifier et vous connecter à notre service web.

Note
 Veuillez consulter notre dépôt GitHub où nous proposons des SDK prêts à télécharger dans différents langages, qui facilitent considérablement vos efforts d’intégration.

Nous vous proposons également un client API qui vous permet de tester les requêtes envoyées à l’API et de consulter les réponses.

3.1Processus

  1. Lorsque le client termine le checkout, créez une commande dans votre boutique.

  2. Vous devez créer un transaction object à l’aide de la méthode create du Transaction Service.

  3. Utilisez le service build payment page URL pour créer l’URL de la page de paiement et redirigez le client vers cette URL. Le client saisit les données de paiement sur la page de paiement. Selon le mode de paiement, il sera redirigé si nécessaire.

  4. Lorsque la transaction est traitée ou a échoué de notre côté, le client est redirigé vers la successUrl ou la failedUrl définie lors de la création de l’objet de transaction.

  5. Écoutez la notification pour marquer la commande dans le système du marchand comme authorized ou failed.

Vous pouvez améliorer ce processus en laissant le client sélectionner le mode de paiement déjà dans l’application du marchand. Avec l’opération fetch possible payment methods du Transaction Service, nous offrons la possibilité de récupérer les modes de paiement activés pour un espace donné. Comme nous décrivons ici le mode d’intégration de la page de paiement, vous devez passer payment_page comme mode d’intégration.

En résultat, la méthode renvoie les modes de paiement possibles. Ces modes de paiement constituent la base de la liste des modes de paiement présentés au client. La propriété allowedPaymentMethods de l’objet de transaction permet de restreindre les modes de paiement autorisés pour la transaction concernée à la sélection effectuée précédemment par le client.

3.1.1Créer un objet de transaction

Pour créer un objet de transaction, vous devez utiliser l’opération Créer une transaction. Ici, vous fournissez les données client dont vous disposez, y compris les lignes d’articles et les prix. Cela créera une transaction à l’état pending dans votre espace.

Requête

{
   "billingAddress":{
	  "city":"Winterthur",
	  "commercialRegisterNumber":"",
	  "country":"CH",
	  "dateOfBirth":"",
	  "emailAddress":"[email protected]",
	  "familyName":"Test",
	  "gender":"",
	  "givenName":"Sam",
	  "mobilePhoneNumber":"",
	  "organizationName":"Wallee AG",
	  "phoneNumber":"",
	  "postCode":"8400",
	  "salesTaxNumber":"",
	  "salutation":"",
	  "socialSecurityNumber":"",
	  "state":"",
	  "street":"Neuwiesenstrasse 15"
   },
   "currency":"EUR",
   "language":"de-CH",
   "lineItems":[
	  {
		 "amountIncludingTax":"11.87",
		 "name":"Barbell Pull Up Bar",
		 "quantity":"1",
		 "shippingRequired":"true",
		 "sku":"barbell-pullup",
		 "type":"PRODUCT",
		 "uniqueId":"barbell-pullup"
	  },
	  {
		 "amountIncludingTax":"559",
		 "name":"Rowing Machine",
		 "quantity":"1",
		 "shippingRequired":"true",
		 "sku":"rowing-machine",
		 "type":"PRODUCT",
		 "uniqueId":"rowing-machine"
	  },
	  {
		 "amountIncludingTax":"17.98",
		 "name":"Super Whey Protein",
		 "quantity":"4",
		 "shippingRequired":"true",
		 "sku":"super-whey",
		 "taxes":[
			{
			   "rate":"10",
			   "title":"VAT"
			},
			{
			   "rate":"3.5",
			   "title":"Supplement Fee"
			}
		 ],
		 "type":"PRODUCT",
		 "uniqueId":"super-whey"
	  },
	  {
		 "amountIncludingTax":"12.5",
		 "name":"Special Chär Test",
		 "quantity":"1",
		 "shippingRequired":"false",
		 "sku":"special-chär-test",
		 "type":"SHIPPING",
		 "uniqueId":"special-chär-test"
	  },
	  {
		 "amountIncludingTax":"12.5",
		 "name":"Standard Shipping",
		 "quantity":"1",
		 "shippingRequired":"false",
		 "sku":"standard-shipping",
		 "type":"SHIPPING",
		 "uniqueId":"standard-shipping"
	  },
	  {
		 "amountIncludingTax":"-10",
		 "name":"Spring Discount",
		 "quantity":"1",
		 "shippingRequired":"false",
		 "sku":"spring-discount",
		 "type":"DISCOUNT",
		 "uniqueId":"spring-discount"
	  }
   ],
   "merchantReference":"DEV-2630",
   "shippingAddress":{
	  "city":"Winterthur",
	  "commercialRegisterNumber":"",
	  "country":"CH",
	  "dateOfBirth":"",
	  "emailAddress":"[email protected]",
	  "familyName":"Test",
	  "gender":"",
	  "givenName":"Sam",
	  "mobilePhoneNumber":"",
	  "organizationName":"Wallee AG",
	  "phoneNumber":"",
	  "postCode":"8400",
	  "salesTaxNumber":"",
	  "salutation":"",
	  "socialSecurityNumber":"",
	  "state":"",
	  "street":"Neuwiesenstrasse 15"
   }
}

Réponse

La réponse que vous recevrez contient le champ id (dans l’exemple ci-dessous 109472) qui sera désormais utilisé pour effectuer d’autres opérations avec cette transaction.

{
	"allowedPaymentMethodBrands": [],
	"allowedPaymentMethodConfigurations": [],
	"authorizationAmount": 603.85,
	"authorizationTimeoutOn": "2017-12-07T08:44:09.119Z",
	"autoConfirmationEnabled": true,
	"chargeRetryEnabled": true,
	"confirmedBy": 0,
	"createdBy": 0,
	"createdOn": "2017-12-07T08:14:09.119Z",
	"currency": "EUR",
	"customersPresence": "VIRTUAL_PRESENT",
	"endOfLife": "2017-12-21T08:14:09.119Z",
	"group": {
		"id": 109478
	},
	"id": 109472,
	"language": "de-CH",
	"linkedSpaceId": 396,
	"merchantReference": "DEV-2630",
	"metaData": {},
	"plannedPurgeDate": "2017-12-21T08:14:09.119Z",
	"refundedAmount": 0,
	"state": "PENDING",
	"timeZone": "Z",
	"version": 1
}

3.1.2Mettre à jour des transactions

Les propriétés d’une transaction peuvent être mises à jour tant que celle-ci n’est pas à l’état confirmed. Pour ce faire, utilisez l’opération update du service de transaction.

Note
 Consultez la section Versionnage / verrouillage des objets qui décrit comment vous devez gérer la propriété version pour éviter les conflits de verrouillage optimiste.

Requête

Dans l’exemple ci-dessous, nous allons mettre à jour les lignes d’articles et supprimer la ligne de remise que nous avons ajoutée dans l’exemple précédent.

{
	"billingAddress": {
		"city": "Winterthur",
		"country": "CH",
		"emailAddress": "[email protected]",
		"familyName": "Test",
		"givenName": "Sam",
		"postCode": "8400",
		"street": "Neuwiesenstrasse 15"
	},
	"currency": "EUR",
	"id": 109472,
	"language": "de-CH",
	"lineItems": [
		{
			"amountIncludingTax": "11.87",
			"name": "Barbell Pull Up Bar",
			"quantity": "1",
			"sku": "barbell-pullup",
			"type": "PRODUCT",
			"uniqueId": "barbell-pullup"
		},
		{
			"amountIncludingTax": "559",
			"name": "Rowing Machine",
			"quantity": "1",
			"sku": "rowing-machine",
			"type": "PRODUCT",
			"uniqueId": "rowing-machine"
		},
		{
			"amountIncludingTax": "17.98",
			"name": "Super Whey Protein",
			"quantity": "4",
			"sku": "super-whey",
			"type": "PRODUCT",
			"uniqueId": "super-whey"
		},
		{
			"amountIncludingTax": "12.5",
			"name": "Special Chär Test",
			"quantity": "1",
			"sku": "special-chär-test",
			"type": "SHIPPING",
			"uniqueId": "special-chär-test"
		},
		{
			"amountIncludingTax": "12.5",
			"name": "Standard Shipping",
			"quantity": "1",
			"sku": "standard-shipping",
			"type": "SHIPPING",
			"uniqueId": "standard-shipping"
		}
	],
	"merchantReference": "DEV-2630",
	"shippingAddress": {
		"city": "Winterthur",
		"country": "CH",
		"emailAddress": "[email protected]",
		"familyName": "Test",
		"givenName": "Sam",
		"postCode": "8400",
		"street": "Neuwiesenstrasse 15"
	},
	"version": 3
}

Réponse

La réponse contient l’objet de transaction mis à jour.

{
	"currency": "EUR",
	"id": 109472,
	"language": "de-CH",
	"merchantReference": "DEV-2630",
	"version": 3
}

3.1.3Réaliser la présélection du paiement

Pour obtenir une meilleure intégration, il est utile de montrer à vos clients déjà dans le checkout quels modes de paiement seraient disponibles sur la base des données de l’objet de transaction. La réponse devrait être rendue et affichée comme options de paiement dans votre checkout.

Pour présélectionner le mode de paiement sur la transaction, vous devriez mettre à jour la transaction comme montré précédemment en fournissant l’identifiant allowedPaymentMethodConfiguration qui est renvoyé par fetchPossiblePaymentMethods pour la transaction donnée.

Réponse

La réponse renvoie les modes de paiement possibles pour la transaction donnée.

{
	"data": [{
		"dataCollectionType": "ONSITE",
		"description": {
			"en-US": ""
		},
		"id": 510,
		"imageResourcePath": null,
		"linkedSpaceId": 396,
		"name": "Credit / Debit Card",
		"oneClickPaymentMode": "ALLOW",
		"paymentMethod": {
			"id": 1457546097597
		},
		"plannedPurgeDate": null,
		"resolvedDescription": {
			"en-US": "Pay conveniently with your credit or debit card."
		},
		"resolvedImageUrl": "https://checkout.postfinance.ch/s/396/resource/icon/payment/method/credit-debit-card.svg",
		"resolvedTitle": {
			"en-US": "Credit / Debit Card"
		},
		"sortOrder": 1,
		"spaceId": 396,
		"state": "ACTIVE",
		"title": {
			"en-US": ""
		},
		"version": 2
	}],
	"hasMore": false,
	"limit": 1
}

Vous pouvez maintenant utiliser ces informations pour afficher la sélection du mode de paiement dans votre boutique. Une fois que le client a choisi le mode de paiement, vous pouvez mettre à jour la transaction ci-dessus en fournissant les allowedPaymentMethodConfigurations avec l’opération update du service de transaction.

Requête

{
	"allowedPaymentMethodConfigurations": [
		{
			"id": 507
		}
	],
	"id": 109472,
	"version": 4
}

3.1.4Construire l’URL de la page de paiement

Pour rediriger le client vers la page de paiement, vous utilisez l’opération Construire l’URL de la page de paiement qui renvoie l’URL de la page de paiement vers laquelle rediriger le client.

Note
 Nous offrons une grande flexibilité pour personnaliser l’apparence de la page de paiement à l’aide de notre éditeur de ressources. Vous trouverez plus d’informations dans la documentation sur les ressources et la personnalisation.

3.1.5Récupérer les mises à jour de la transaction

Pour être informé de l’état de la transaction, vous devriez enregistrer des notifications webhook de votre côté. Les webhooks vous informeront des changements d’état des entités sélectionnées et devraient déclencher le traitement ultérieur des résultats de la transaction dans votre application.

Vous trouverez plus d’informations sur les webhooks, les écouteurs de webhooks et leur configuration dans la documentation sur les webhooks.