Faire régler une somme

Demander un paiement dans un parcours, par un lien envoyé à une personne ou à l'envoi d'un formulaire, puis suivre son règlement.

6 min de lecture Mise à jour le 11 novembre 2026

Un modèle de paiement porte le compte qui encaisse, la devise, le montant et le libellé ; un paiement en est tiré pour chaque règlement. Le payeur règle sur une page de l'application, puis chez le prestataire du compte — Stripe, PayPal ou Adyen : Docage ne voit jamais une carte. Seul le prestataire confirme qu'un paiement est réglé : le retour du payeur sur la page n'en est pas une preuve.

1Le compte et le modèle

GET https://staging-api.docage.com/PaymentAccounts/Usable
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9…

curl "https://staging-api.docage.com/PaymentAccounts/Usable" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9…"

using HttpClient client = new();
using HttpRequestMessage request = new(HttpMethod.Get, "https://staging-api.docage.com/PaymentAccounts/Usable");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);
using HttpResponseMessage response = await client.SendAsync(request);
string result = await response.Content.ReadAsStringAsync();
if (!response.IsSuccessStatusCode)
    throw new HttpRequestException(result);

const response = await fetch("https://staging-api.docage.com/PaymentAccounts/Usable", {
  headers: {
    Authorization: `Bearer ${token}`
  }
});
const text = await response.text();
if (!response.ok) throw new Error(text);
const result = text ? JSON.parse(text) : null;

JSON

[{ "Id": "99999999-0000-4000-8000-000000000009", "Name": "Stripe — Atelier Lumière", "Provider": 1, "IsLive": true, "IsDefault": true }]

Les comptes de paiement de votre organisation que le payeur peut utiliser — actifs, leurs identifiants enregistrés et vérifiés —, le compte par défaut en tête. Provider : 1 Stripe, 2 PayPal, 3 Adyen. IsLive à false : un compte d'essai, dont les paiements sont des paiements d'essai. Sans compte utilisable, personne ne peut régler.

Le modèle, une fois pour toutes :

POST https://staging-api.docage.com/Payments
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9…
Content-Type: application/json

{
  "Name": "Acompte de formation",
  "IsTemplate": true,
  "PaymentAccountId": "99999999-0000-4000-8000-000000000009",
  "Currency": "EUR",
  "AmountText": "450",
  "Description": "Acompte — formation Excel du 12 décembre"
}

curl -X POST "https://staging-api.docage.com/Payments" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "Content-Type: application/json" \
  -d '{
    "Name": "Acompte de formation",
    "IsTemplate": true,
    "PaymentAccountId": "99999999-0000-4000-8000-000000000009",
    "Currency": "EUR",
    "AmountText": "450",
    "Description": "Acompte — formation Excel du 12 décembre"
  }'

using HttpClient client = new();
using HttpRequestMessage request = new(HttpMethod.Post, "https://staging-api.docage.com/Payments");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);
request.Content = new StringContent("""
    {
      "Name": "Acompte de formation",
      "IsTemplate": true,
      "PaymentAccountId": "99999999-0000-4000-8000-000000000009",
      "Currency": "EUR",
      "AmountText": "450",
      "Description": "Acompte — formation Excel du 12 décembre"
    }
    """, Encoding.UTF8, "application/json");
using HttpResponseMessage response = await client.SendAsync(request);
string result = await response.Content.ReadAsStringAsync();
if (!response.IsSuccessStatusCode)
    throw new HttpRequestException(result);

const response = await fetch("https://staging-api.docage.com/Payments", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "Name": "Acompte de formation",
    "IsTemplate": true,
    "PaymentAccountId": "99999999-0000-4000-8000-000000000009",
    "Currency": "EUR",
    "AmountText": "450",
    "Description": "Acompte — formation Excel du 12 décembre"
  })
});
const text = await response.text();
if (!response.ok) throw new Error(text);
const result = text ? JSON.parse(text) : null;

AmountText : le montant, au point décimal (450, 1250.50), strictement positif — ou un champ de fusion ({{…}}), remplacé quand le paiement est tiré du modèle.
Currency : le code ISO 4217 de la devise, EUR d'office.
Description : le libellé montré au payeur ; Reference : votre référence (une facture, un devis), transmise au prestataire.

GET https://staging-api.docage.com/Payments/TemplatesIdAndName retrouve vos modèles.

2Dans un parcours

Le participant qui règle reçoit l'action « Paiement » (Type 4), dans un parcours en brouillon :

POST https://staging-api.docage.com/TransactionActions
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9…
Content-Type: application/json

{
  "TransactionMemberId": "dddddddd-0000-4000-8000-000000000004",
  "Type": 4,
  "PaymentId": "aaaaaaaa-0000-4000-8000-000000000041"
}

curl -X POST "https://staging-api.docage.com/TransactionActions" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "Content-Type: application/json" \
  -d '{
    "TransactionMemberId": "dddddddd-0000-4000-8000-000000000004",
    "Type": 4,
    "PaymentId": "aaaaaaaa-0000-4000-8000-000000000041"
  }'

using HttpClient client = new();
using HttpRequestMessage request = new(HttpMethod.Post, "https://staging-api.docage.com/TransactionActions");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);
request.Content = new StringContent("""
    {
      "TransactionMemberId": "dddddddd-0000-4000-8000-000000000004",
      "Type": 4,
      "PaymentId": "aaaaaaaa-0000-4000-8000-000000000041"
    }
    """, Encoding.UTF8, "application/json");
using HttpResponseMessage response = await client.SendAsync(request);
string result = await response.Content.ReadAsStringAsync();
if (!response.IsSuccessStatusCode)
    throw new HttpRequestException(result);

const response = await fetch("https://staging-api.docage.com/TransactionActions", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "TransactionMemberId": "dddddddd-0000-4000-8000-000000000004",
    "Type": 4,
    "PaymentId": "aaaaaaaa-0000-4000-8000-000000000041"
  })
});
const text = await response.text();
if (!response.ok) throw new Error(text);
const result = text ? JSON.parse(text) : null;

PaymentId désigne un modèle de paiement de votre organisation. Quand vient le tour du paiement, le serveur en tire le paiement du participant, rempli des données du parcours ; sans payeur au modèle, l'email du participant le devient. Le participant reçoit son invitation, et règle sur sa page.
D'office, le paiement passe après la validation et la signature.
Un modèle de parcours qui porte déjà l'action la transmet aux parcours qu'on en tire : voir Créer un parcours à partir d'un modèle.

Le lancement (POST https://staging-api.docage.com/Transactions/LaunchTransaction/{id}) est refusé (400) quand l'action n'a pas de modèle (« … doit régler un paiement mais n'a aucun modèle de paiement associé »), quand le compte du modèle n'est pas utilisable (« Aucun compte de paiement vérifié n'est associé à ce paiement : le payeur ne pourrait pas le régler… », suivi du nom du payeur), et quand le parcours n'a aucun document à signer — il en faut un, même pour un parcours qui ne fait que régler.

Pendant le parcours, GET https://staging-api.docage.com/Transactions/GetTransactionMembers/{id} donne le PaymentStatus de chaque participant : 1 en attente de son tour, 2 à faire, 4 commencé, 5 terminé. Le participant peut aussi refuser de payer, en donnant un motif : le parcours est alors refusé. Le paiement lui-même se lit comme à l'étape 5, et se retrouve par le filtre TransactionId de QUERY https://staging-api.docage.com/Payments.

3Par un lien

Créez le paiement de la personne :

POST https://staging-api.docage.com/Payments
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9…
Content-Type: application/json

{
  "Name": "Acompte — Camille Martin",
  "TemplateId": "aaaaaaaa-0000-4000-8000-000000000041",
  "PaymentAccountId": "99999999-0000-4000-8000-000000000009",
  "Currency": "EUR",
  "AmountText": "450",
  "Description": "Acompte — formation Excel du 12 décembre",
  "PayerName": "Camille Martin",
  "PayerEmail": "camille.martin@example.com"
}

curl -X POST "https://staging-api.docage.com/Payments" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "Content-Type: application/json" \
  -d '{
    "Name": "Acompte — Camille Martin",
    "TemplateId": "aaaaaaaa-0000-4000-8000-000000000041",
    "PaymentAccountId": "99999999-0000-4000-8000-000000000009",
    "Currency": "EUR",
    "AmountText": "450",
    "Description": "Acompte — formation Excel du 12 décembre",
    "PayerName": "Camille Martin",
    "PayerEmail": "camille.martin@example.com"
  }'

using HttpClient client = new();
using HttpRequestMessage request = new(HttpMethod.Post, "https://staging-api.docage.com/Payments");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);
request.Content = new StringContent("""
    {
      "Name": "Acompte — Camille Martin",
      "TemplateId": "aaaaaaaa-0000-4000-8000-000000000041",
      "PaymentAccountId": "99999999-0000-4000-8000-000000000009",
      "Currency": "EUR",
      "AmountText": "450",
      "Description": "Acompte — formation Excel du 12 décembre",
      "PayerName": "Camille Martin",
      "PayerEmail": "camille.martin@example.com"
    }
    """, Encoding.UTF8, "application/json");
using HttpResponseMessage response = await client.SendAsync(request);
string result = await response.Content.ReadAsStringAsync();
if (!response.IsSuccessStatusCode)
    throw new HttpRequestException(result);

const response = await fetch("https://staging-api.docage.com/Payments", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "Name": "Acompte — Camille Martin",
    "TemplateId": "aaaaaaaa-0000-4000-8000-000000000041",
    "PaymentAccountId": "99999999-0000-4000-8000-000000000009",
    "Currency": "EUR",
    "AmountText": "450",
    "Description": "Acompte — formation Excel du 12 décembre",
    "PayerName": "Camille Martin",
    "PayerEmail": "camille.martin@example.com"
  })
});
const text = await response.text();
if (!response.ok) throw new Error(text);
const result = text ? JSON.parse(text) : null;

La création ne recopie pas les réglages du modèle : donnez le compte, la devise et le montant. Pour partir du modèle, GET https://staging-api.docage.com/Payments/CreateEntityFromTemplate/{templateid}/false compose le paiement d'après lui ; retouchez-le, puis envoyez-le par ce POST.

Calculez ensuite son montant :

POST https://staging-api.docage.com/Payments/eeeeeeee-0000-4000-8000-000000000042/Resolve
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9…

curl -X POST "https://staging-api.docage.com/Payments/eeeeeeee-0000-4000-8000-000000000042/Resolve" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9…"

using HttpClient client = new();
using HttpRequestMessage request = new(HttpMethod.Post, "https://staging-api.docage.com/Payments/eeeeeeee-0000-4000-8000-000000000042/Resolve");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);
using HttpResponseMessage response = await client.SendAsync(request);
string result = await response.Content.ReadAsStringAsync();
if (!response.IsSuccessStatusCode)
    throw new HttpRequestException(result);

const response = await fetch("https://staging-api.docage.com/Payments/eeeeeeee-0000-4000-8000-000000000042/Resolve", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${token}`
  }
});
const text = await response.text();
if (!response.ok) throw new Error(text);
const result = text ? JSON.parse(text) : null;

JSON

{ "Amount": 450, "Currency": "EUR", "Description": "Acompte — formation Excel du 12 décembre", "Reference": null }

Resolve remplace les champs de fusion de ses textes, puis calcule Amount d'après AmountText. Sans lui, Amount reste à 0 — et la page de paiement comme l'email du lien l'affichent ainsi — jusqu'à ce que le payeur commence à régler. 400 : le montant est vide ou ne se lit pas.

4Envoyer le lien

POST https://staging-api.docage.com/Payments/eeeeeeee-0000-4000-8000-000000000042/SendLinkByMail
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9…
Content-Type: application/json

{ "Message": "Merci de régler l'acompte avant le 1er décembre." }

curl -X POST "https://staging-api.docage.com/Payments/eeeeeeee-0000-4000-8000-000000000042/SendLinkByMail" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "Content-Type: application/json" \
  -d '{
    "Message": "Merci de régler l'\''acompte avant le 1er décembre."
  }'

using HttpClient client = new();
using HttpRequestMessage request = new(HttpMethod.Post, "https://staging-api.docage.com/Payments/eeeeeeee-0000-4000-8000-000000000042/SendLinkByMail");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);
request.Content = new StringContent("""
    {
      "Message": "Merci de régler l'acompte avant le 1er décembre."
    }
    """, Encoding.UTF8, "application/json");
using HttpResponseMessage response = await client.SendAsync(request);
string result = await response.Content.ReadAsStringAsync();
if (!response.IsSuccessStatusCode)
    throw new HttpRequestException(result);

const response = await fetch("https://staging-api.docage.com/Payments/eeeeeeee-0000-4000-8000-000000000042/SendLinkByMail", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "Message": "Merci de régler l'acompte avant le 1er décembre."
  })
});
const text = await response.text();
if (!response.ok) throw new Error(text);
const result = text ? JSON.parse(text) : null;

L'email porte le montant, le libellé et un bouton pour payer ; il part à Email s'il est donné, sinon à l'email du payeur (PayerEmail), et reste attaché au paiement.

Code	Ce qu'il dit
`400`	Le paiement est un modèle, aucun compte vérifié ne lui est associé, aucune adresse n'est connue, ou l'envoi a échoué.
`403`	Vous n'avez pas le droit de modifier le paiement.
`404`	Le paiement est introuvable, ou vous ne le voyez pas.
`409`	Le paiement est déjà réglé, remboursé ou annulé.

Par SMS : POST https://staging-api.docage.com/Payments/{id}/SendLinkBySms, avec PhoneNumber (obligatoire : un paiement ne porte pas de téléphone), au format international (+33612345678) ; un numéro national se lit dans le pays de l'organisation du paiement, et un numéro qui ne se lit pas est refusé (400). Le SMS est facturé comme tout SMS, et refusé à une organisation qui n'est pas encore en production.
Ou transmettez le lien vous-même : Link, dans GET https://staging-api.docage.com/Payments/{id}, est l'adresse de la page de paiement.

5Suivre le paiement

GET https://staging-api.docage.com/Payments/{id} :

`Status`	Statut
`0`	Brouillon
`1`	En attente
`2`	Commencé : le payeur est chez le prestataire.
`3`	Réussi
`4`	Échoué
`5`	Annulé
`6`	Expiré
`7`	Remboursé
`-100`	Erreur

StatusDetails donne le motif d'un échec, en termes neutres ; PaidAtUtc, l'instant du règlement ; PaymentMethod, le moyen employé, tel que le prestataire le rend.

GET https://staging-api.docage.com/Payments/{id}/Events : la chronologie du paiement — rappels du prestataire et relectures —, du plus récent au plus ancien.
QUERY https://staging-api.docage.com/Payments : la liste, filtrée par TransactionId, PayerEmail ou Status — voir Lire des listes.
POST https://staging-api.docage.com/Payments/{id}/Cancel annule un paiement qui n'est pas réglé ; son paramètre reason est le motif montré au payeur s'il revient sur le lien.

À l'envoi d'un formulaire web

Un champ « Paiement » fait régler une somme à chaque envoi d'un formulaire web — voir Créer un formulaire web :

JSON

{ "Type": "payment", "Name": "Reglement", "Label": "Règlement", "PaymentTemplateId": "aaaaaaaa-0000-4000-8000-000000000041", "AmountFieldName": "Montant" }

Le serveur tire le paiement du modèle, le rattache à la réponse, et conduit le visiteur à la page de paiement. Le montant est la saisie du champ numérique que nomme AmountFieldName, sinon AmountText du champ, sinon celui du modèle ; le payeur est le premier champ email rempli. Le modèle doit être de l'organisation du formulaire, et seul le premier champ « Paiement » compte.

Les pièges

Seul le prestataire confirme un règlement : Status passe à 3 quand il le dit — par son rappel, ou quand Docage relit le paiement chez lui, ce que déclenche le retour du payeur sur la page de paiement. Ce retour, à lui seul, n'est pas une preuve.
L'API n'a pas de route publique pour relire un paiement chez le prestataire : un rappel perdu se rattrape quand le payeur revient sur la page de paiement, ou depuis la fiche du paiement dans l'application. GET https://staging-api.docage.com/Payments/{id} rend ce que Docage sait.
Un paiement réussi est facturé à l'organisation, au tarif d'un paiement.
Dans un parcours, un montant vide, illisible ou nul ne se découvre qu'au début de l'étape du paiement : vérifiez AmountText du modèle avant d'envoyer.
Un modèle ne se paie pas : seul le lien d'un paiement tiré de lui sert.
L'API n'a pas de route de remboursement.