Intégration d’un moyen de paiement personnalisé sur Kreezalid

L’ajout d’un mode de paiement personnalisé sur votre marketplace Kreezalid suit un processus en deux étapes :

**1. Activation par Kreezalid (à faire avant tout développement)**

Avant toute intégration, vous devez contacter notre équipe pour que nous enregistrions votre mode de paiement dans le back-office.
Merci de nous fournir les éléments suivants :

Élément requis	Détail
Nom du mode de paiement	Ex. : Paypal, Bons cadeaux, Paiement par chèque
URL de redirection	L’URL vers laquelle l’acheteur sera redirigé au checkout
Icône	Format .svg ou .png, idéalement carré (~100x100 px)
Description courte	Une phrase qui sera affichée au moment du choix du paiement dans le panier (ex. : “Vous serez redirigé vers CarloApp pour finaliser votre paiement”)

**2. Intégration technique du paiement**

 Redirection HTTP POST
Lorsqu’un acheteur choisit ce moyen de paiement au checkout, Kreezalid envoie une requête HTTP POST vers l’URL que vous avez fournie.
Par défaut, le payload POST contient :

{
  "order_ids": "1234,5678",
  "return_url": "https://votre-site.com/.../success",
  "cancel_url": "https://votre-site.com/.../checkout/payment"
}

```
order_ids est une chaîne de valeurs séparées par virgule (ex: "1234,5678"), à parser en tableau.

Il est possible de transmettre d’autres paramètres personnalisés à la demande (ex. : secret_key, token, identifiant utilisateur, etc.). Contactez notre support pour cela.

###  **Traitement du paiement (à votre charge)**

#### **Ce que vous devez gérer :**


1. **Afficher une page de validation/attente** : comme pour une authentification 3D Secure, prévoyez un écran de chargement pendant que l’acheteur valide son paiement (ex. dans une app externe).
2. **Vérifier le paiement via votre fournisseur tiers**
3. **Mettre à jour la commande** en appelant l’API REST de Kreezalid

#### **En cas de paiement réussi :**
Appelez notre API pour chaque commande concernée avec :

{
"status": "new",
"financial_status": "paid", // ou "partially_paid"
"checkout_at": "2025-06-26T09:12:45Z" // Format ISO 8601 en UTC
}

#### **En cas d’échec ou d’abandon :**


* Laisser status à "draft" pour permettre une nouvelle tentative
*  Si vous passez status à "failed", la commande devient non payable (aucune relance possible)




###  **Redirection finale**
Une fois la commande mise à jour :

* Redirigez l’acheteur vers return_url en cas de succès
* Redirigez vers cancel_url en cas d’échec ou d’annulation
La page à return_url est la page de confirmation de commande. Elle est **personnalisable** via le **Theme Editor** (checkout/order-confirmation.liquid). Vous pouvez y adapter l’affichage selon le order.status.



##  **Schéma du flux**

sequenceDiagram
participant Acheteur
participant Kreezalid
participant VotreScript
participant Fournisseur Paiement

Acheteur->>Kreezalid: Sélectionne le moyen de paiement
Kreezalid->>VotreScript: POST (order_ids, return_url, cancel_url)
VotreScript->>Fournisseur Paiement: Initie la transaction
Fournisseur Paiement-->>VotreScript: Résultat paiement
VotreScript->>Kreezalid API: Met à jour la commande
VotreScript->>Acheteur: Redirection vers return_url ou cancel_url
```

**Récapitulatif développeur**

Élément	Obligatoire	Format / Détail
Nom du moyen de paiement		Chaîne
URL de redirection		HTTPS recommandé
Icône		.svg ou .png
Description		Phrase courte
Réception POST		order_ids, return_url, cancel_url (autres sur demande)
MAJ commande via API		status, financial_status, checkout_at
Redirection finale		Vers return_url ou cancel_url

Mis à jour le : 26/06/2025