Panier

Créer un panier et initier le paiement

L’endpoint présenté ici vous permet de créer un panier et d’initier le processus de paiement. La réponse de l’endpoint vous fournit l’URL vers laquelle vous devez rediriger l’utilisateur pour qu’il procède au paiement.

Voyons tout cela en détail.

La requête

Pour créer un panier et initier son paiement, vous devez effectuer une requête POST vers l’endpoint indiqué ci-dessous, ajouter la clé API dans les headers et fournir une payload au format décrit.

Endpoint

POST https://api.maketou.net/api/v1/stores/cart/checkout

Header

Nom	Type	Requis	Description
Authorization	string préfixé de Bearer	Oui	Votre clé API

Body (payload)

Paramètre	Type	Requis	Description
productDocumentId	string	Oui	Identifiant public du produit
email	string	Oui	Adresse email du client pour la confirmation de commande
firstName	string	Oui	Prénom du client
lastName	string	Oui	Nom du client
phone	string	Non	Numéro de téléphone du client
redirectURL	string	Non	URL de retour après paiement
meta	object	Non	Objet contenant des métadonnées personnalisées à associer au panier (clé/valeur)

Comment obtenir le productDocumentId

Notre API, pour le moment, ne supporte qu’un seul produit par panier. La propriété productDocumentId correspond à l’ID du produit dans votre espace Maketou. Pour le retrouver :

1. Connectez-vous à votre compte Maketou.
2. Accédez à l’espace de votre boutique.
3. Ouvrez la page détail du produit souhaité.
4. Cliquez sur le bouton Partager.
5. Dans le drawer, copiez l’Identifiant public du produit.

À propos de la redirectURL

La redirect URL est l'URL vers laquelle l'utilisateur sera redirigé une fois son paiement effectué. Elle n'est pas obligatoire : si elle n'est pas définie, l'utilisateur sera redirigé vers la page de post-paiement par défaut de Maketou.

À propos de la propriété meta

La propriété meta vous permet d'associer des métadonnées personnalisées à votre panier sous forme d'objet clé/valeur. Ces données seront stockées avec le panier et pourront être récupérées ultérieurement lors de la consultation du panier.

Cas d'usage :

• Associer un identifiant utilisateur de votre système
• Tracer la source de la commande (site web, application mobile, etc.)
• Stocker des informations de tracking ou de campagne marketing
• Ajouter toute donnée contextuelle utile pour votre application

Les métadonnées sont totalement flexibles et vous permettent d'injecter les informations personnalisées dont vous avez besoin.

Exemples de création de panier

Exemple de payload

{
  "productDocumentId": "550e8400-e29b-41d4-a716-446655440000",
  "email": "client@example.com",
  "firstName": "Jean",
  "lastName": "Dupont",
  "phone": "+33612345678",
  "redirectURL": "https://monsite.com/ma-page-de-confirmation",
  "meta": {
    "userId": "12345",
    "source": "website"
  }
}

Réponse

Succès (201)

{
  "cart": {
    "id": "fd2d91d7-20d2-4b86-b067-d474fb0d1e60",
    "createdAt": "2025-11-28T14:27:00.805Z",
    "updatedAt": "2025-11-28T14:27:00.805Z",
    "status": "waiting_payment",
    "customerInfo": {
      "firstName": "John",
      "lastName": "Doe",
      "email": "customer@example.com",
      "phone": "+33612345678",
      "lang": "fr-FR"
    }
  },
  "redirectUrl": "https://checkout.moneroo.io/py_mj2m7m6gfro8"
}

Erreurs possibles

Code	Description
400	Identifiant de produit invalide ou produit non disponible — Code : INVALID_PRODUCT
401	Clé API invalide ou manquante — Code : INVALID_API_KEY
422	Erreur de validation : le format attendu pour la payload n’est pas respecté

Les statuts des paniers

• waiting_payment : Le panier est en attente de paiement
• completed : Le panier est complété et le paiement est effectué
• abandoned : Le panier est abandonné
• payment_failed : Le paiement a échoué

Récupérer le statut d’un panier

Vous pouvez également récupérer un panier ultérieurement afin de vérifier son statut.

Requête

GET /api/v1/stores/cart/{cartId}

Headers

Nom	Type	Requis	Description
Authorization	string	Oui	Votre clé API

Paramètres d’URL

Paramètre	Type	Description
cartId	string (UUID)	Identifiant du panier

Exemple de requête

GET /api/v1/stores/cart/550e8400-e29b-41d4-a716-446655440000

Réponse

Succès (200)

{
  "id": "fd2d91d7-20d2-4b86-b067-d474fb0d1e60",
  "createdAt": "2025-11-28T14:27:00.805Z",
  "updatedAt": "2025-11-28T14:27:00.805Z",
  "paymentId": "4d729bf5-ef1e-4f7f-bf10-e63bd3db9b04",
  "status": "waiting_payment",
  "customerInfo": {
    "lang": "fr-FR",
    "email": "customer@example.com",
    "phone": "+33612345678",
    "lastName": "Doe",
    "firstName": "John"
  },
  "meta": {
    "userId": "ok"
  }
}

Erreurs

Code	Description
401	Clé API invalide ou manquante
404	Panier non trouvé

Réponse de l’API en cas d’erreur

{
  "code": "INVALID_PRODUCT",
  "message": "The product is not available or does not belong to this store"
}

Utilisation du prix libre au niveau de l’API

La fonctionnalité de prix libre permet à vos clients de définir le prix auquel ils souhaitent acheter le produit.

Dans le cadre de l’utilisation de notre API, vous pouvez préciser le prix renseigné par le client dans la payload de création de panier via la propriété customerPrice.

Voici un exemple de payload de création de panier avec l’utilisation du prix libre :

{
  "productDocumentId": "7b63442b-200f-445c-89c6-cd4b3b001bf7",
  "email": "customer@example.com",
  "firstName": "John",
  "lastName": "Doe",
  "phone": "+33612345678",
  "redirectURL": "https://my.app/post-paiement",
  "customerPrice": 2000
}

Note : La requête est effectuée sur la même route de création de panier mentionnée un peu plus haut sur cette page.

Note : Pour que cela fonctionne, votre produit doit avoir un pricing de type Prix libre. Vous pouvez configurer cela dans votre dashboard Maketou en éditant le produit.