Paiement
Générer le lien de paiement, suivre l'encaissement, renvoyer ou annuler un lien.
Comment ça marche
Le paiement d'une proposition (ou d'un avenant payant) passe par un lien de paiement :
l'API crée une intention de paiement, renvoie une URL, et l'avenant passe en PENDING_PAYMENT. Quand
le client paie, la plateforme confirme le règlement, émet le contrat et produit
l'attestation. Votre logiciel n'a qu'à initier le paiement puis suivre son statut.
Initier le paiement d'une proposition — POST /provider/contracts/{contractId}/pay
Sans corps. Prérequis : un avenant affaire nouvelle en QUOTE avec une prime (créé automatiquement à
la création de la proposition ou par …/tarification/{contractId}/calculate).
{
"endorsementId": "c0261ae8-feee-4ee4-827d-9df4ceb4af4f",
"premiumId": "35ef3da7-9945-4051-a13a-7a72a39af200",
"amount": 52190.00,
"paymentUrl": "https://paiement.pooltpv.app/pay/...",
"paymentReference": "pi_91cb5dddcb204a959396ab0f",
"expiresAt": null,
"endorsement": { "id": "c0261ae8-…", "status": "PENDING_PAYMENT", "reference": "AV-AFFAIRE_NOUVELLE-1791274717947" }
}| Champ | Description |
|---|---|
endorsementId | Avenant payé (affaire nouvelle) |
premiumId | Prime concernée |
amount | Montant TTC à régler |
paymentUrl | Page de paiement vers laquelle rediriger le client |
paymentReference | Référence de paiement (pi_…), reprise sur les états |
expiresAt | Expiration du lien, si définie |
endorsement | Avenant imbriqué |
Erreurs : CONTRACT_NOT_FOUND (hors périmètre), ENDORSEMENT_NOT_FOUND (aucun avenant QUOTE).
Payer un avenant — POST /provider/endorsements/{endorsementId}/payment/init
Même réponse (EndorsementPaymentLink), pour un avenant coté dont la prime est positive.
Suivre le paiement
| Endpoint | Réponse |
|---|---|
GET /provider/contracts/{contractId}/payments/status | { "status": true } si le dernier règlement du contrat est confirmé |
GET /provider/contracts/{contractId}/payments | Règlements du contrat (ContractPayment[], paginé) |
GET /provider/endorsements/{endorsementId}/payments | Règlements d'un avenant |
Objet ContractPayment :
| Champ | Description |
|---|---|
paymentReference | Référence de paiement |
paymentLink | URL du lien |
externalTransactionId | Identifiant de la transaction de paiement |
amountDue, amountPaid | Dû et encaissé |
paymentMethod | Mode (mobile money, carte…) |
status | PENDING, PARTIAL, CONFIRMED, FAILED, REFUNDED |
paymentDate, dueDate, confirmedDate | Dates de règlement, d'échéance et de confirmation |
failureReason | Motif d'échec |
endorsementId, installmentId, installmentNumber, numberOfInstallments | Rattachements |
Ne considérez jamais un contrat comme émis sur la seule foi d'une redirection après paiement.
Attendez payments/status = true ou un règlement CONFIRMED, puis relisez le contrat (ACTIVE,
policyNumber).
Renvoyer le lien — POST /provider/endorsements/{endorsementId}/payment/resend
{ "channels": ["EMAIL", "SMS"], "email": "client@example.com", "phone": "+2250700000000" }| Champ | Obligatoire | Description |
|---|---|---|
channels | oui | EMAIL, SMS, WHATSAPP |
email | non | Destinataire, sinon l'e-mail du souscripteur |
phone | non | Téléphone, sinon le mobile du souscripteur |
Réponse : ActionResponse dont data est un tableau de NotificationResult
(channel, recipient, sent, error, sentAt).
Annuler les liens en attente — POST /provider/endorsements/{contractId}/payment/cancel
Sans corps. Annule les liens de paiement en attente du contrat ; les avenants concernés redeviennent
modifiables. Réponse : ActionResponse dont data est la liste des ContractEndorsement libérés.
À utiliser avant de modifier une proposition verrouillée (PROPOSAL_LOCKED_FOR_PAYMENT).
Après l'encaissement
Une fois le règlement confirmé, la plateforme enchaîne automatiquement : émission de l'avenant
(ISSUED), numéro de police, attestation numérique, documents (reçu, facture, attestation), répartition
de la prime entre compagnies et écritures comptables. Ces étapes sont asynchrones et prennent
généralement quelques secondes. Les documents sont disponibles via
GET /provider/contracts/{contractId}/documents.