{
    "module": "Paiements & Escrow Multi-Tenant (Paiement)",
    "base_url": "https://notif.compareb2b.com/public/paiement",
    "endpoints": [
        {
            "id": "charge",
            "method": "POST",
            "path": "/v1/payments/charge.php",
            "title": "Débit direct standard immédiat",
            "summary": "Encaisse immédiatement un paiement carte via token PCI-DSS sans séquestre. Bascule automatique sur passerelle de secours en cas de panne d'infrastructure (HTTP 502/504), mais retour immédiat 402 en cas de refus bancaire.",
            "headers": {
                "Content-Type": "application/json",
                "X-Api-Key": "pay_live_pub_demo_marketplace",
                "X-Timestamp": "1774198200 (Timestamp UNIX actuel, tolérance ±300s)",
                "X-Nonce": "nonce_64_bits_unique_random_hex",
                "X-Signature": "HMAC-SHA256(METHOD\\nPATH\\nTIMESTAMP\\nNONCE\\nSHA256(BODY), SECRET)"
            },
            "payload": {
                "amount": {
                    "type": "float",
                    "required": true,
                    "description": "Montant à prélever (ex: 150.00)"
                },
                "currency": {
                    "type": "string",
                    "required": false,
                    "description": "Devise ISO 4217 (défaut : \"EUR\")"
                },
                "payment_method_token": {
                    "type": "string",
                    "required": true,
                    "description": "Token PCI-DSS (ex: \"pm_card_visa_debit\", ou tokens de simulation)"
                },
                "statement_descriptor": {
                    "type": "string",
                    "required": false,
                    "description": "Libellé apparaissant sur le relevé bancaire du client"
                },
                "customer": {
                    "type": "object",
                    "required": false,
                    "description": "Coordonnées de l'acheteur (ex: {\"name\": \"Jean Dupont\", \"email\": \"jean@example.com\"})"
                }
            },
            "request_example": {
                "amount": 150,
                "currency": "EUR",
                "payment_method_token": "pm_card_visa_debit",
                "statement_descriptor": "DEMO SHOP PARIS",
                "customer": {
                    "name": "Jean Dupont",
                    "email": "jean.dupont@example.com"
                }
            },
            "response_success": {
                "success": true,
                "transaction_id": "tx_66f01a2b3c4d5e6f",
                "amount": 150,
                "currency": "EUR",
                "status": "captured",
                "gateway_used": "Stripe Payments",
                "auth_code": "AUTH_99824",
                "created_at": "2026-09-22 01:20:00"
            },
            "response_error": {
                "success": false,
                "error_code": "insufficient_funds",
                "error_message": "Fonds insuffisants sur la carte de l'acheteur.",
                "is_functional_decline": true,
                "http_code": 402
            }
        },
        {
            "id": "escrow_hold",
            "method": "POST",
            "path": "/v1/escrow/hold.php",
            "title": "Séquestre Étape 1 : Blocage des fonds (Hold)",
            "summary": "Prélève l'acheteur et immobilise les fonds sur un compte de transit sécurisé en attendant la satisfaction d'une condition métier (ex: livraison confirmée).",
            "headers": {
                "Content-Type": "application/json",
                "X-Api-Key": "pay_live_pub_demo_marketplace",
                "X-Timestamp": "1774198200",
                "X-Nonce": "nonce_64_bits_unique_random_hex",
                "X-Signature": "HMAC-SHA256 signature"
            },
            "payload": {
                "amount": {
                    "type": "float",
                    "required": true,
                    "description": "Montant total de la commande sous séquestre"
                },
                "currency": {
                    "type": "string",
                    "required": false,
                    "description": "Devise ISO (défaut: \"EUR\")"
                },
                "payment_method_token": {
                    "type": "string",
                    "required": true,
                    "description": "Token de paiement fourni par l'acheteur"
                },
                "submerchant_id": {
                    "type": "string",
                    "required": true,
                    "description": "Identifiant du vendeur sous-marchand bénéficiaire final (ex: \"acct_seller_pierre_883\")"
                },
                "release_condition": {
                    "type": "string",
                    "required": false,
                    "description": "Condition contractuelle de libération (ex: \"delivery_confirmed_by_buyer\")"
                },
                "customer": {
                    "type": "object",
                    "required": false,
                    "description": "Informations client {\"name\": \"...\", \"email\": \"...\"}"
                }
            },
            "request_example": {
                "amount": 420,
                "currency": "EUR",
                "payment_method_token": "pm_card_mastercard",
                "submerchant_id": "acct_seller_pierre_883",
                "release_condition": "delivery_confirmed_by_buyer",
                "customer": {
                    "name": "Claire Delattre",
                    "email": "claire@example.com"
                }
            },
            "response_success": {
                "success": true,
                "transaction_id": "tx_88a91c2d3e4f",
                "escrow_id": 19,
                "amount": 420,
                "currency": "EUR",
                "status": "escrowed",
                "submerchant_id": "acct_seller_pierre_883",
                "release_condition": "delivery_confirmed_by_buyer",
                "message": "Fonds capturés et immobilisés sous séquestre avec succès."
            },
            "response_error": {
                "success": false,
                "error_message": "Le sous-marchand acct_inconnu est invalide ou non activé.",
                "http_code": 422
            }
        },
        {
            "id": "escrow_release",
            "method": "POST",
            "path": "/v1/escrow/release.php",
            "title": "Séquestre Étape 2 : Libération des fonds au vendeur",
            "summary": "Débloque les fonds séquestrés et déclenche le transfert irréversible vers le compte bancaire du sous-marchand après validation de la commande.",
            "headers": {
                "Content-Type": "application/json",
                "X-Api-Key": "pay_live_pub_demo_marketplace",
                "X-Timestamp": "1774198200",
                "X-Nonce": "nonce_64_bits_unique_random_hex",
                "X-Signature": "HMAC-SHA256 signature"
            },
            "payload": {
                "transaction_id": {
                    "type": "string",
                    "required": true,
                    "description": "Référence tx_xxx de la transaction sous séquestre"
                },
                "amount": {
                    "type": "float",
                    "required": false,
                    "description": "Montant à libérer (par défaut: montant intégral restant)"
                }
            },
            "request_example": {
                "transaction_id": "tx_88a91c2d3e4f",
                "amount": 420
            },
            "response_success": {
                "success": true,
                "transaction_id": "tx_88a91c2d3e4f",
                "status": "released",
                "amount_released": 420,
                "submerchant_id": "acct_seller_pierre_883",
                "released_at": "2026-09-22 01:25:00",
                "message": "Fonds libérés avec succès au sous-marchand."
            },
            "response_error": {
                "success": false,
                "error_message": "Impossible de libérer : La transaction est en litige ou déjà libérée.",
                "http_code": 409
            }
        },
        {
            "id": "escrow_dispute",
            "method": "POST",
            "path": "/v1/escrow/dispute.php",
            "title": "Séquestre Étape 3 : Déclaration de litige & gel",
            "summary": "Gèle conservatoirement les fonds d'une transaction sous séquestre suite à une réclamation acheteur ou incident de livraison, bloquant tout transfert au vendeur.",
            "headers": {
                "Content-Type": "application/json",
                "X-Api-Key": "pay_live_pub_demo_marketplace",
                "X-Timestamp": "1774198200",
                "X-Nonce": "nonce_64_bits_unique_random_hex",
                "X-Signature": "HMAC-SHA256 signature"
            },
            "payload": {
                "transaction_id": {
                    "type": "string",
                    "required": true,
                    "description": "Référence tx_xxx de la transaction"
                },
                "reason": {
                    "type": "string",
                    "required": true,
                    "description": "Motif détaillé du litige (ex: \"Produit non conforme ou colis endommagé\")"
                }
            },
            "request_example": {
                "transaction_id": "tx_88a91c2d3e4f",
                "reason": "Colis reçu endommagé avec articles manquants."
            },
            "response_success": {
                "success": true,
                "transaction_id": "tx_88a91c2d3e4f",
                "status": "disputed",
                "frozen_amount": 420,
                "disputed_at": "2026-09-22 01:26:00",
                "message": "Litige enregistré : Les fonds sont gelés à titre conservatoire."
            },
            "response_error": {
                "success": false,
                "error_message": "Transaction introuvable ou statut incompatible avec un litige.",
                "http_code": 400
            }
        },
        {
            "id": "escrow_refund",
            "method": "POST",
            "path": "/v1/escrow/refund.php",
            "title": "Séquestre Étape 3 : Remboursement de l'acheteur",
            "summary": "Annule le séquestre et recrédite l'acheteur sur son moyen de paiement d'origine (intégral ou partiel).",
            "headers": {
                "Content-Type": "application/json",
                "X-Api-Key": "pay_live_pub_demo_marketplace",
                "X-Timestamp": "1774198200",
                "X-Nonce": "nonce_64_bits_unique_random_hex",
                "X-Signature": "HMAC-SHA256 signature"
            },
            "payload": {
                "transaction_id": {
                    "type": "string",
                    "required": true,
                    "description": "Référence tx_xxx de la transaction à rembourser"
                },
                "reason": {
                    "type": "string",
                    "required": false,
                    "description": "Motif du remboursement (ex: \"Accord amiable de résiliation\")"
                },
                "amount": {
                    "type": "float",
                    "required": false,
                    "description": "Montant à rembourser (défaut : solde restant total)"
                }
            },
            "request_example": {
                "transaction_id": "tx_88a91c2d3e4f",
                "reason": "Retour marchandise validé par le vendeur.",
                "amount": 420
            },
            "response_success": {
                "success": true,
                "transaction_id": "tx_88a91c2d3e4f",
                "status": "refunded",
                "amount_refunded": 420,
                "refunded_at": "2026-09-22 01:28:00",
                "message": "Remboursement intégral effectué à l'acheteur."
            },
            "response_error": {
                "success": false,
                "error_message": "Montant demandé supérieur au solde disponible.",
                "http_code": 422
            }
        },
        {
            "id": "status",
            "method": "GET",
            "path": "/v1/payments/status.php",
            "title": "Consultation de transaction & grand livre comptable",
            "summary": "Retourne la fiche complète d'une transaction, son état de séquestre ainsi que toutes les écritures comptables immuables (double-entrée logique).",
            "headers": {
                "X-Api-Key": "pay_live_pub_demo_marketplace",
                "X-Timestamp": "1774198200",
                "X-Nonce": "nonce_64_bits_unique_random_hex",
                "X-Signature": "HMAC-SHA256 signature"
            },
            "payload": {
                "id": {
                    "type": "string (query param)",
                    "required": true,
                    "description": "Identifiant unique tx_xxx de la transaction"
                }
            },
            "request_example": {
                "query_params": "?id=tx_88a91c2d3e4f"
            },
            "response_success": {
                "success": true,
                "transaction": {
                    "id": "tx_88a91c2d3e4f",
                    "amount": 420,
                    "currency": "EUR",
                    "status": "escrowed",
                    "gateway_used": "Adyen MarketPay",
                    "created_at": "2026-09-22 01:20:00"
                },
                "escrow": {
                    "submerchant_id": "acct_seller_pierre_883",
                    "condition": "delivery_confirmed_by_buyer",
                    "is_frozen": false
                },
                "audit_entries": [
                    {
                        "entry_type": "DEBIT_CUSTOMER",
                        "amount": 420,
                        "source_account": "customer_card",
                        "destination_account": "escrow_transit_vault",
                        "timestamp": "2026-09-22 01:20:00"
                    }
                ]
            },
            "response_error": {
                "success": false,
                "error_message": "Transaction introuvable pour ce compte tenant.",
                "http_code": 404
            }
        }
    ]
}