đł
API Paiements & Séquestre Escrow
Référentiel complet des Endpoints, RÎles et Payloads
Débit direct standard immédiat
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.
En-tĂȘtes HTTP Requis (HMAC-SHA256)
En-tĂȘte Valeur / Exemple
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)
Structure du Payload (Corps JSON)
Champ Type Obligatoire ? Description
amount
float
OUI
Montant à prélever (ex: 150.00)
currency
string
Optionnel
Devise ISO 4217 (défaut : "EUR")
payment_method_token
string
OUI
Token PCI-DSS (ex: "pm_card_visa_debit", ou tokens de simulation)
statement_descriptor
string
Optionnel
Libellé apparaissant sur le relevé bancaire du client
customer
object
Optionnel
Coordonnées de l'acheteur (ex: {"name": "Jean Dupont", "email": "jean@example.com"})
Exemple de RequĂȘte JSON
đ Copier
{
"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"
}
}
Réponse SuccÚs (HTTP 200)
đ Copier
{
"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"
}
Réponse Erreur Type
{
"success": false,
"error_code": "insufficient_funds",
"error_message": "Fonds insuffisants sur la carte de l'acheteur.",
"is_functional_decline": true,
"http_code": 402
}
SĂ©questre Ătape 1 : Blocage des fonds (Hold)
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).
En-tĂȘtes HTTP Requis (HMAC-SHA256)
En-tĂȘte Valeur / Exemple
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
Structure du Payload (Corps JSON)
Champ Type Obligatoire ? Description
amount
float
OUI
Montant total de la commande sous séquestre
currency
string
Optionnel
Devise ISO (défaut: "EUR")
payment_method_token
string
OUI
Token de paiement fourni par l'acheteur
submerchant_id
string
OUI
Identifiant du vendeur sous-marchand bénéficiaire final (ex: "acct_seller_pierre_883")
release_condition
string
Optionnel
Condition contractuelle de libération (ex: "delivery_confirmed_by_buyer")
customer
object
Optionnel
Informations client {"name": "...", "email": "..."}
Exemple de RequĂȘte JSON
đ Copier
{
"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"
}
}
Réponse SuccÚs (HTTP 200)
đ Copier
{
"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."
}
Réponse Erreur Type
{
"success": false,
"error_message": "Le sous-marchand acct_inconnu est invalide ou non activé.",
"http_code": 422
}
SĂ©questre Ătape 2 : LibĂ©ration des fonds au vendeur
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.
En-tĂȘtes HTTP Requis (HMAC-SHA256)
En-tĂȘte Valeur / Exemple
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
Structure du Payload (Corps JSON)
Champ Type Obligatoire ? Description
transaction_id
string
OUI
Référence tx_xxx de la transaction sous séquestre
amount
float
Optionnel
Montant à libérer (par défaut: montant intégral restant)
Exemple de RequĂȘte JSON
đ Copier
{
"transaction_id": "tx_88a91c2d3e4f",
"amount": 420
}
Réponse SuccÚs (HTTP 200)
đ Copier
{
"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."
}
Réponse Erreur Type
{
"success": false,
"error_message": "Impossible de libérer : La transaction est en litige ou déjà libérée.",
"http_code": 409
}
SĂ©questre Ătape 3 : DĂ©claration de litige & gel
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.
En-tĂȘtes HTTP Requis (HMAC-SHA256)
En-tĂȘte Valeur / Exemple
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
Structure du Payload (Corps JSON)
Champ Type Obligatoire ? Description
transaction_id
string
OUI
Référence tx_xxx de la transaction
reason
string
OUI
Motif détaillé du litige (ex: "Produit non conforme ou colis endommagé")
Exemple de RequĂȘte JSON
đ Copier
{
"transaction_id": "tx_88a91c2d3e4f",
"reason": "Colis reçu endommagé avec articles manquants."
}
Réponse SuccÚs (HTTP 200)
đ Copier
{
"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."
}
Réponse Erreur Type
{
"success": false,
"error_message": "Transaction introuvable ou statut incompatible avec un litige.",
"http_code": 400
}
SĂ©questre Ătape 3 : Remboursement de l'acheteur
Annule le séquestre et recrédite l'acheteur sur son moyen de paiement d'origine (intégral ou partiel).
En-tĂȘtes HTTP Requis (HMAC-SHA256)
En-tĂȘte Valeur / Exemple
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
Structure du Payload (Corps JSON)
Champ Type Obligatoire ? Description
transaction_id
string
OUI
Référence tx_xxx de la transaction à rembourser
reason
string
Optionnel
Motif du remboursement (ex: "Accord amiable de résiliation")
amount
float
Optionnel
Montant à rembourser (défaut : solde restant total)
Exemple de RequĂȘte JSON
đ Copier
{
"transaction_id": "tx_88a91c2d3e4f",
"reason": "Retour marchandise validé par le vendeur.",
"amount": 420
}
Réponse SuccÚs (HTTP 200)
đ Copier
{
"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."
}
Réponse Erreur Type
{
"success": false,
"error_message": "Montant demandé supérieur au solde disponible.",
"http_code": 422
}
Consultation de transaction & grand livre comptable
Retourne la fiche complÚte d'une transaction, son état de séquestre ainsi que toutes les écritures comptables immuables (double-entrée logique).
En-tĂȘtes HTTP Requis (HMAC-SHA256)
En-tĂȘte Valeur / Exemple
X-Api-Key
pay_live_pub_demo_marketplace
X-Timestamp
1774198200
X-Nonce
nonce_64_bits_unique_random_hex
X-Signature
HMAC-SHA256 signature
Structure du Payload (ParamĂštres d'URL)
Champ Type Obligatoire ? Description
id
string (query param)
OUI
Identifiant unique tx_xxx de la transaction
Exemple de RequĂȘte JSON
đ Copier
{
"query_params": "?id=tx_88a91c2d3e4f"
}
Réponse SuccÚs (HTTP 200)
đ Copier
{
"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"
}
]
}
Réponse Erreur Type
{
"success": false,
"error_message": "Transaction introuvable pour ce compte tenant.",
"http_code": 404
}