Créer la commande

Cette section décrit les propriétés d'une commande, (c'est-à-dire de l'objet order) dans le cas d'une séquence de paiement standard.

Pour les fonctionnalités supplémentaires, cf. Scénarios de paiement particuliers.

Plusieurs propriétés sont nécessaires lors de la création d’une commande :

• Identification de la marketplace (marketplace) :

  Renseignez l'uuid de la marketplace sur laquelle effectuer la commande.

• Identification de la commande (reference & description):

  Deux champs sont à votre disposition pour faciliter l'identification de la commande : reference et description.

  Vous devez obligatoirement renseigner une référence acheteur. Dans le cas de la redirection, la référence sera répétée dans l'encart de rappel. Elle apparaîtra aussi dans votre Back office dans la colonne "Référence acheteur".

   Notez que l'API Makretplace crééra de son côté un uuid de la commande.

  Rien ne vous empêche d'utiliser plusieurs fois la même référence. Il est toutefois recommandé de créer une référence distincte pour chaque commande, même s'il s'agit d'un même acheteur souhaitant retenter son achat après un premier échec.

  Le champs textuel description est facultatif et pour votre propre information.

• Définition de la devise (currency)

  La commande est mono-devise.

  Indiquez la devise dans laquelle s'expriment les montants des articles, en reprenant la désignation des devises telles qu'indiquées dans votre objet marketplace : cf. Comprendre les informations de la marketplace.

• Définition du panier (items)

  Il est possible de créer une commande vide, c'est-à-dire sans aucun article. Mais dans ce cas, il ne sera pas possible d'aller jusqu'à l'affichage du formulaire sans une mise à jour. Une commande valide doit contenir au moins un article (item).

  Exemple d’un objet item

  {
      "seller": "52bc75e6-0bfa-4ccb-a35e-0c6e2d3dea36",
      "reference": "MKP_I1",
      "description": "Gâteau meringué",
      "type": "FOOD_AND_GROCERY",
      "amount": 1399
  }

• • Identification des vendeurs (seller)

    Pour identifier un vendeur, vous avec le choix entre :

    • l'uuid du vendeur, à utiliser avec la propriété seller;
    • ou bien le seller_external_refsi vous avez préalablement défini l'external_ref lors de l'étape de l'enrôlement (voir chapitre Détail de l'objet registration du guide Enrôlement des vendeurs).
  • Identification de l'article (reference & description)

    La référence de l'article est obligatoire. Elle apparaît dans votre Back Office ( Transactions > Panier) à la colonne Référence.

  • Définition du type de l'article (type)

    Le type de l'article est obligatoire. Utilisez la table des catégories d'articles suivante pour le renseigner.

    Valeur	Description
    FOOD_AND_GROCERY	Produits alimentaires et d'épicerie
    AUTOMOTIVE	Automobile / Moto
    ENTERTAINMENT	Divertissement / Culture
    HOME_AND_GARDEN	Maison / Jardin
    HOME_APPLIANCE	Equipement de la maison
    AUCTION_AND_GROUP_BUYING	Ventes aux enchères / Achats groupés
    FLOWERS_AND_GIFTS	Fleurs / Cadeaux
    COMPUTER_AND_SOFTWARE	Ordinateurs / Logiciels
    HEALTH_AND_BEAUTY	Santé / Beauté
    SERVICE_FOR_INDIVIDUAL	Services à la personne
    SERVICE_FOR_BUSINESS	Services aux entreprises
    SPORTS	Sports
    CLOTHING_AND_ACCESSORIES	Vêtements / Accessoires
    TRAVEL	Voyage
    HOME_AUDIO_PHOTO_VIDEO	Son / Image / Vidéo
    TELEPHONY	Téléphonie

  • Définition du montant de l'article (amount)

    Les montants envoyés doivent être exprimés dans la plus petit unité possible de la devise indiquée par la propriété currency, et correspondent au panier après remise, déduction et calcul des commissions et de la TVA.

    Exemple : 2590 pour 25,90€

     Il n'est pas possible de définir un article au montant négatif.
     L'API ne calcule aucune commission ni de TVA pour la marketplace. Les seuls calculs concernent la vérification de la commission minimale dans le cas des prélèvements au fil de l'eau.

• Définition de la quantité de l'article (quantity)

  Optionnellement, vous pouvez renseigner le champs quantity .

  Notez que ce champs n'a qu'une valeur indicative: l'API n'effectue aucuncalcul sur la base de ce champs. En particulier, le montant de l'article et du panier n'est pas lié à la quantité d'articles.

• Définition de la commission

  Deux méthodes permettent de renseigner le montant de la commission :

  1. ajouter au panier un article "commission";
  2. définir le montant de la commission au niveau des articles du panier.

  Comission définie...	... au niveau de la commande	... au niveau de l'article
  Propriété utilisée suritem	[/concept/conbody/ul/li/p/table/tgroup/tbody/row/entry/pre {"- topic/pre "})is_commission: true (pre]	commission_amount: {montant de la commission}
  Contrainte sur le vendeur	Uniquement sur l'opérateur marketplace (seller avec is_marketplace_seller: true)	Aucune contrainte.
  Interprétation du montant	Le montant de la commission s'ajoute au montant des autres articles.	Le montant de la commission vient en déduction du montant de l'article.
  Exemple de payload	{ "currency": "EUR", ... "items": [ { "seller": "4d20a9d4-0526-4474-b452-e936dc25418d", "reference": "produit_vendeur", "description": "Produit", "amount": 10000 }, { "seller": "72ccc2ff-b455-4653-847e-deb6fee99f8d", "reference": "marketplace_commission", "description": "Commission", "amount": 1000, "is_commission": true } ], ... }	{ "currency": "EUR", ... "items": [ { "seller": "4d20a9d4-0526-4474-b452-e936dc25418d", "reference": "produit_vendeur", "description": "Produit", "amount": 10000 "commission_amount": 1000 } ], ... }
  Interprétation de l'exemple	Le montant total de la commande est de 100 + 10 = 110 €. Le vendeur reçoit 100€; La marketplace reçoit 10€ (*).	Le montant total de la commande est de 100€. Le vendeur reçoit 90€; La marketplace reçoit 10€ (*).

• Définition de la langue du formulaire (language)
  Vous devez obligatoirement renseigner la langue du formulaire, d'après la liste des langages ci-dessous.

  Langue	Codification ISO 639-1
  Allemand	de
  Anglais	en
  Chinois	zh
  Espagnol	es
  Français	fr
  Italien	it
  Japonais	ja
  Néerlandais	nl
  Polonais	pl
  Portugais	pt
  Russe	ru
  Suédois	sv
  Turc	tr

• Envoi des informations de l'acheteur (buyer)

  L'objet buyer est obligatoire mais ne présente pas de difficulté particulière.

  Valeurs possibles du paramètre type :

  • PRIVATE
  • COMPANY

  Exemple de représentation de l'objet buyer

  {
    ...
    "buyer": {
      "title": "",
      "first_name": "Louis",
      "last_name": "Goncalves",
      "email": "louis.goncalves@boyer.com",
      "phone_number": "+33 (0)2 82 90 07 18",
      "type": "PRIVATE",
      "reference": "613B4E7430E09",
      "address": {
        "street_number": "9",
        "street": "avenue Boulay",
        "zipcode": "13 947",
        "city": "GAUTHIER",
        "state": "FRANCE",
        "country": ""
      }
    },
    ...
  }

• Envoi des informations de livraison (shipping)

  L'objet shipping est également obligatoire.

  Le shipping_method peut prendre une des valeurs suivantes :

  • RECLAIM_IN_SHOP,
  • RELAY_POINT,
  • RECLAIM_IN_STATION,
  • RECLAIM_IN_STATION,
  • PACKAGE_DELIVERY_COMPANY,
  • PACKAGE_DELIVERY_COMPANY,
  • ou ETICKET

  Représentation minimale de l'objet Shipping

  {
    ...
    "shipping": {
      "shipping_method": "ETICKET",
      "delay": "2",
      "address": {
        "street_number": "9",
        "street": "avenue Boulay",
        "zipcode": "13947",
        "city": "GAUTHIER",
        "state": "FRANCE",
        "country": ""
      }
    },
    ...
  }

• Préparation du retour vers la marketplace
  Afin de rediriger l'acheteur vers la marketplace, plusieurs attributs de la ressource order peuvent être renseignés :

  • url_return est l'URL de retour par défaut. Vous pouvez n'utiliser que cet attribut si vous ne souhaitez pas différencier les cas de retour. Les attributs qui suivent surchargent sa valeur au cas par cas.
  • url_success est l'URL appelée si le paiement est un succès.
  • url_refused est l'URL appelée si le paiement est refusé.
  • url_cancel est l'URL appelée si le paiement est annulé.
  • url_error est l'URL appelée si le paiement est en erreur.

  Par défaut, les données du paiement sont envoyées à l'URL de retour sous la forme d'un formulaire HTTP GET (dans la « query string »), par exemple :

  https://mymarketplace.com/return_to_shop?ref=1234&customer=ABCD

  Ce comportement peut être surchargé via l'attribut return_mode qui peut prendre les valeurs suivantes :

  • NONE : aucun paramètre n'est envoyé à l'URL de retour.
  • POST : les paramètres sont envoyés à l'URL de retour sous la forme d'un formulaire HTTP POST (Si le retour boutique se fait sur un environnement non https alors le navigateur affichera un pop-up de sécurité à l'acheteur.)
  • GET (par défaut) : Les champs de retour sont transmis à l'URL de retour sous la forme d'un formulaire HTTP GET (dans la « query string »).

• Envoi de la commande
   

  N'oubliez pas les articles !

  Pour déclarer des articles dans votre commande, vous devez mentionner l'argument ?expand=items dans l'url (e.g. /marketplace/v1/orders?expand=items). Dans le cas contraire, la commande sera créée sans articles. Et lors de l'exécution de la commande vous rencontrerez une erreur 400 :

  {"amount":"The sum of item amounts cannot be zero or
      negative."}

  Exemples

  Requête

  POST/orders?expand=items

  {
    "description": "1 Gâteau meringué + 1 Crème caramel + 1 Frais de dossier",
    "payment_config": "SINGLE",
    "language": "fr",
    "currency": "EUR",
    "shipping": {
      "shipping_method": "ETICKET",
      "delay": "2",
      "address": {
        "street_number": "9",
        "street": "avenue Boulay",
        "zipcode": "13 947",
        "city": "GAUTHIER",
        "state": "FRANCE",
        "country": ""
      }
    },
    "buyer": {
      "title": "",
      "first_name": "Louis",
      "last_name": "Goncalves",
      "email": "louis.goncalves@boyer.com",
      "phone_number": "+33 (0)2 82 90 07 18",
      "type": "PRIVATE",
      "reference": "613B4E7430E09",
      "address": {
        "street_number": "9",
        "street": "avenue Boulay",
        "zipcode": "13 947",
        "city": "GAUTHIER",
        "state": "FRANCE",
        "country": ""
      }
    },
    "items": [
      {
        "seller": "52bc75e6-0bfa-4ccb-a35e-0c6e2d3dea36",
        "reference": "MKP_I1",
        "description": "Gâteau meringué",
        "type": "FOOD_AND_GROCERY",
        "quantity": 1,
        "amount": 1399,
        "is_commission": false
      },
      {
        "seller": "975b7c49-0e8e-4291-8d25-e50744718fc1",
        "reference": "M1I2",
        "description": "Crème caramel",
        "type": "FOOD_AND_GROCERY",
        "quantity": 1,
        "amount": 899,
        "is_commission": false,
        "commission_amount": 18,
        "vouchers": [
          {
            "contract_type": "CONECS",
            "eligible_amount": 899
          }
        ]
      },
      {
        "seller": "52bc75e6-0bfa-4ccb-a35e-0c6e2d3dea36",
        "reference": "FEES",
        "description": "Frais de dossier",
        "type": "FOOD_AND_GROCERY",
        "quantity": 1,
        "amount": 137,
        "is_commission": true
      }
    ],
    "url_return": "https://docs.lyra.com/fr/collect/marketplace/demo/server/views/paid/iframe.php?rid=613b4ea5c597f&buyerRef=613B4E7430E09",
    "marketplace": "57595c55-b096-41d8-9287-b98640de3f25",
    "reference": "3BE1B46A615EA"
  }

  Corps de réponse

  POST/orders?expand=items

  {
    "uuid": "f86f6cf6-18b3-448c-8659-5bb077099482",
    "href": "https://secure.lyra.com/marketplace-test/v1/orders/f86f6cf6-18b3-448c-8659-5bb077099482",
    "created_at": "2021-09-10T12:25:12.968773Z",
    "updated_at": "2021-09-10T12:25:12.968787Z",
    "marketplace": "57595c55-b096-41d8-9287-b98640de3f25",
    "reference": "3BE1B46A615EA",
    "description": "1 Gâteau meringué + 1 Crème caramel + 1 Frais de dossier",
    "language": "fr",
    "alias": null,
    "awaiting_validation": null,
    "buyer": [
      {
        "reference": "613B4E7430E09",
        "title": "",
        "type": "PRIVATE",
        "first_name": "Louis",
        "last_name": "Goncalves",
        "legal_name": null,
        "phone_number": "+33 (0)2 82 90 07 18",
        "email": "louis.goncalves@boyer.com",
        "address": {
          "street_number": "9",
          "street": "avenue Boulay",
          "district": null,
          "zipcode": "13 947",
          "city": "GAUTHIER",
          "state": "FRANCE",
          "country": ""
        }
      }
    ],
    "shipping": [
      {
        "shipping_method": "ETICKET",
        "delivery_company_name": null,
        "shipping_speed": null,
        "shipping_delay": null,
        "type": null,
        "first_name": null,
        "last_name": null,
        "legal_name": null,
        "phone_number": null,
        "address": {
          "street_number": "9",
          "street": "avenue Boulay",
          "district": null,
          "zipcode": "13 947",
          "city": "GAUTHIER",
          "state": "FRANCE",
          "country": ""
        }
      }
    ],
    "payment_config": "SINGLE",
    "amount": null,
    "initial_amount": null,
    "currency": "EUR",
    "status": "CREATED",
    "webhook_result": null,
    "url_return": "https://docs.lyra.com/fr/collect/marketplace/demo/server/views/paid/iframe.php?rid=613b4ea5c597f&buyerRef=613B4E7430E09",
    "url_success": null,
    "url_refused": null,
    "url_cancel": null,
    "url_error": null,
    "return_mode": null,
    "shop_url": null,
    "items": [
      {
        "uuid": "0fd9ed9b-c73d-4eb8-b7d4-7d168464177e",
        "href": "https://secure.lyra.com/marketplace-test/v1/items/0fd9ed9b-c73d-4eb8-b7d4-7d168464177e",
        "created_at": "2021-09-10T12:25:13.025797Z",
        "updated_at": "2021-09-10T12:25:13.025809Z",
        "seller": "52bc75e6-0bfa-4ccb-a35e-0c6e2d3dea36",
        "order": "f86f6cf6-18b3-448c-8659-5bb077099482",
        "reference": "FEES",
        "description": "Frais de dossier",
        "type": "FOOD_AND_GROCERY",
        "amount": 137,
        "quantity": 1,
        "transfers": [],
        "status": "CREATED",
        "links": {
          "transfers": {
            "href": "https://secure.lyra.com/marketplace-test/v1/items/0fd9ed9b-c73d-4eb8-b7d4-7d168464177e/transfers"
          }
        },
        "is_commission": true
      },
      {
        "uuid": "ca69772b-e130-4571-bbef-9ce8505e6d73",
        "href": "https://secure.lyra.com/marketplace-test/v1/items/ca69772b-e130-4571-bbef-9ce8505e6d73",
        "created_at": "2021-09-10T12:25:13.017715Z",
        "updated_at": "2021-09-10T12:25:13.017724Z",
        "seller": "975b7c49-0e8e-4291-8d25-e50744718fc1",
        "order": "f86f6cf6-18b3-448c-8659-5bb077099482",
        "reference": "M1I2",
        "description": "Crème caramel",
        "type": "FOOD_AND_GROCERY",
        "amount": 899,
        "quantity": 1,
        "transfers": [],
        "status": "CREATED",
        "links": {
          "transfers": {
            "href": "https://secure.lyra.com/marketplace-test/v1/items/ca69772b-e130-4571-bbef-9ce8505e6d73/transfers"
          }
        },
        "is_commission": false,
        "commission_amount": 18,
        "vouchers": [
          {
            "contract_type": "CONECS",
            "eligible_amount": 899
          }
        ]
      },
      {
        "uuid": "d2812abd-2e94-4ffb-a30f-1598779f523e",
        "href": "https://secure.lyra.com/marketplace-test/v1/items/d2812abd-2e94-4ffb-a30f-1598779f523e",
        "created_at": "2021-09-10T12:25:13.011881Z",
        "updated_at": "2021-09-10T12:25:13.011893Z",
        "seller": "52bc75e6-0bfa-4ccb-a35e-0c6e2d3dea36",
        "order": "f86f6cf6-18b3-448c-8659-5bb077099482",
        "reference": "MKP_I1",
        "description": "Gâteau meringué",
        "type": "FOOD_AND_GROCERY",
        "amount": 1399,
        "quantity": 1,
        "transfers": [],
        "status": "CREATED",
        "links": {
          "transfers": {
            "href": "https://secure.lyra.com/marketplace-test/v1/items/d2812abd-2e94-4ffb-a30f-1598779f523e/transfers"
          }
        },
        "is_commission": false,
        "commission_amount": 0
      }
    ],
    "links": {
      "items": {
        "href": "https://secure.lyra.com/marketplace-test/v1/orders/f86f6cf6-18b3-448c-8659-5bb077099482/items"
      },
      "transactions": {
        "href": "https://secure.lyra.com/marketplace-test/v1/orders/f86f6cf6-18b3-448c-8659-5bb077099482/transactions"
      },
      "refunds": {
        "href": "https://secure.lyra.com/marketplace-test/v1/orders/f86f6cf6-18b3-448c-8659-5bb077099482/refunds"
      },
      "execute": {
        "href": "https://secure.lyra.com/marketplace-test/v1/orders/f86f6cf6-18b3-448c-8659-5bb077099482/execute"
      },
      "execute-embedded": {
        "href": "https://secure.lyra.com/marketplace-test/v1/orders/f86f6cf6-18b3-448c-8659-5bb077099482/execute-embedded"
      },
      "persist": {
        "href": "https://secure.lyra.com/marketplace-test/v1/orders/f86f6cf6-18b3-448c-8659-5bb077099482/persist"
      }
    },
    "vads_transaction_id": 0,
    "vads_transaction_date": null,
    "expected_capture_date": null,
    "capture_delay": null,
    "persist_url": null,
    "expiry_date": null
  }