Capturia mesure ses publicités et la fréquentation du site avec le pixel Meta et Google Analytics. Tu peux refuser en tout temps. En savoir plus

EN

Payments

2 points d'accès

get/v1/payments

Lister les paiements encaissés et leurs pièces

Retourne la liste paginée (curseur v2) des paiements encaissés par le compte de la clé, de toutes leurs sources : soumissions et propositions, funnels, paiements notés à la main, paiements Stripe directs, adhésions à un Espace. Chaque paiement porte ses pièces : son reçu en vigueur et les notes de crédit de ses remboursements, dont le PDF se lit par GET /v1/payment-documents/{id}.

Tri stable paid_at DESC, id DESC : le plus récent encaissé d'abord. Avec updated_after ou updated_before, la liste se trie par updated_at croissant : un paiement revient quand il est inscrit, remboursé ou rattaché à une fiche, ou quand une de ses pièces est émise ou annulée.

Filtres

  • ?contact_id (uuid) — les paiements d'une fiche du compte. Une valeur qui n'est pas un UUID répond 400 invalid_request (details.field = contact_id).

Les paiements en attente ou échoués n'y sont pas : l'événement payment_failed les annonce. Un paiement d'un autre compte n'y paraît jamais.

Scopes requis : payments:read

Paramètres de requête

NomTypeObligatoireDescription
cursorstring | nulloptionnelCurseur opaque de pagination : passe la valeur de pagination.next_cursor de la page précédente.
limitintegeroptionnelNombre max de résultats par page (défaut 20, max 100). Au-delà → 400 invalid_request.
updated_afterstringoptionnelFiltre : uniquement les ressources modifiées après cette date (inclusive). Avec une borne updated_*, la liste se trie par updated_at croissant (la plus ancienne modification d'abord), départagée par id. Repars de l'updated_at de la dernière ressource lue, moins 2 minutes : une écriture longue peut porter une date un peu plus ancienne que la fin de ta lecture. Écarte les doublons par id. Un curseur d'un autre tri est refusé (cursor_field_mismatch). Une liste qui écarte les ressources archivées (rendez-vous, soumissions) les rend dans cette lecture avec leur archived_at : c'est ainsi qu'un retrait se lit.
updated_beforestringoptionnelFiltre : uniquement les ressources modifiées avant cette date (inclusive). Trie la liste comme updated_after.
contact_idstringoptionnelUniquement les paiements de cette fiche.

Réponses

StatutDescription
200

Liste paginée des paiements encaissés.

400

Requête invalide. code distingue les refus que l'opération rend sous ce statut, et chaque exemple en montre un.

invalid_requestlimit · exceeds_max
{
  "error": {
    "type": "validation_error",
    "code": "invalid_request",
    "message": "Le format de la requête est invalide.",
    "hint": "Vérifie que les headers, le body et l'encodage JSON respectent le contrat documenté dans l'API Reference.",
    "doc_url": "https://capturia.io/fr/developers/api/v1/errors#invalid_request",
    "request_id": "req_01J9X8Z3F4K2M5N7P9Q1R3S5T7",
    "details": {
      "field": "limit",
      "reason": "exceeds_max",
      "max": 100
    }
  }
}
invalid_requestupdated_after · invalid_value
{
  "error": {
    "type": "validation_error",
    "code": "invalid_request",
    "message": "Le format de la requête est invalide.",
    "hint": "Vérifie que les headers, le body et l'encodage JSON respectent le contrat documenté dans l'API Reference.",
    "doc_url": "https://capturia.io/fr/developers/api/v1/errors#invalid_request",
    "request_id": "req_01J9X8Z3F4K2M5N7P9Q1R3S5T7",
    "details": {
      "field": "updated_after",
      "reason": "invalid_value"
    }
  }
}
invalid_requestcursor · cursor_field_mismatch
{
  "error": {
    "type": "validation_error",
    "code": "invalid_request",
    "message": "Le format de la requête est invalide.",
    "hint": "Vérifie que les headers, le body et l'encodage JSON respectent le contrat documenté dans l'API Reference.",
    "doc_url": "https://capturia.io/fr/developers/api/v1/errors#invalid_request",
    "request_id": "req_01J9X8Z3F4K2M5N7P9Q1R3S5T7",
    "details": {
      "field": "cursor",
      "reason": "cursor_field_mismatch"
    }
  }
}
invalid_requestcontact_id · invalid_format
{
  "error": {
    "type": "validation_error",
    "code": "invalid_request",
    "message": "Le format de la requête est invalide.",
    "hint": "Vérifie que les headers, le body et l'encodage JSON respectent le contrat documenté dans l'API Reference.",
    "doc_url": "https://capturia.io/fr/developers/api/v1/errors#invalid_request",
    "request_id": "req_01J9X8Z3F4K2M5N7P9Q1R3S5T7",
    "details": {
      "field": "contact_id",
      "reason": "invalid_format"
    }
  }
}
401

La clé API manque, est inconnue ou a expiré. code distingue les trois causes : missing_api_key (aucun en-tête Authorization: Bearer), invalid_api_key (clé inconnue, révoquée ou de format invalide) et expired_api_key (date d'expiration dépassée).

missing_api_key
{
  "error": {
    "type": "authentication_error",
    "code": "missing_api_key",
    "message": "Aucune clé API n'a été fournie.",
    "hint": "Ajoute un header Authorization sous la forme : Bearer cap_live_<ta_clé>",
    "doc_url": "https://capturia.io/fr/developers/api/v1/authentication#missing_api_key",
    "request_id": "req_01J9X8Z3F4K2M5N7P9Q1R3S5T7"
  }
}
invalid_api_key
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "La clé API est invalide ou a été révoquée.",
    "hint": "Vérifie la clé dans ton dashboard ou génère-en une nouvelle.",
    "doc_url": "https://capturia.io/fr/developers/api/v1/authentication#invalid_api_key",
    "request_id": "req_01J9X8Z3F4K2M5N7P9Q1R3S5T7"
  }
}
expired_api_key
{
  "error": {
    "type": "authentication_error",
    "code": "expired_api_key",
    "message": "La clé API a expiré.",
    "hint": "Roule la clé depuis le dashboard pour en générer une nouvelle valide.",
    "doc_url": "https://capturia.io/fr/developers/api/v1/authentication#expired_api_key",
    "request_id": "req_01J9X8Z3F4K2M5N7P9Q1R3S5T7"
  }
}
403

Refus d'autorisation. code distingue les refus que l'opération rend sous ce statut, et chaque exemple en montre un.

browser_not_allowed
{
  "error": {
    "type": "authorization_error",
    "code": "browser_not_allowed",
    "message": "Les clés API s'utilisent depuis un serveur, jamais depuis un navigateur.",
    "hint": "La requête porte un en-tête `Origin` : appelle l'API depuis ton serveur, où la clé reste secrète.",
    "doc_url": "https://capturia.io/fr/developers/api/v1/errors#browser_not_allowed",
    "request_id": "req_01J9X8Z3F4K2M5N7P9Q1R3S5T7"
  }
}
account_suspended
{
  "error": {
    "type": "authorization_error",
    "code": "account_suspended",
    "message": "L'accès à ce compte est suspendu par l'équipe Capturia.",
    "hint": "Le refus vient du compte, pas de la clé. Tant que la suspension dure, aucune requête n'est acceptée : contacte l'équipe Capturia.",
    "doc_url": "https://capturia.io/fr/developers/api/v1/authentication#account_suspended",
    "request_id": "req_01J9X8Z3F4K2M5N7P9Q1R3S5T7"
  }
}
feature_not_available
{
  "error": {
    "type": "authorization_error",
    "code": "feature_not_available",
    "message": "Cette fonctionnalité n'est pas incluse dans ton forfait.",
    "hint": "Le refus vient du forfait du compte, pas de la clé. Contacte ton conseiller Capturia pour en parler.",
    "doc_url": "https://capturia.io/fr/developers/api/v1/authentication#plan",
    "request_id": "req_01J9X8Z3F4K2M5N7P9Q1R3S5T7",
    "details": {
      "feature": "public_api"
    }
  }
}
insufficient_scope
{
  "error": {
    "type": "authorization_error",
    "code": "insufficient_scope",
    "message": "Cette clé API ne contient pas le scope requis pour ce point d'accès.",
    "hint": "Cette clé n'a pas le scope `payments:read`. Crée une nouvelle clé avec le preset « Lecture seule » ou ajoute le scope via le dashboard.",
    "doc_url": "https://capturia.io/fr/developers/api/v1/authentication#scopes",
    "dashboard_url": "https://capturia.io/platform/dashboard/admin/integrations/api-keys/6f1e2d3c-4b5a-4c6d-8e7f-9a0b1c2d3e4f?tab=permissions",
    "request_id": "req_01J9X8Z3F4K2M5N7P9Q1R3S5T7",
    "details": {
      "required_scope": "payments:read",
      "current_scopes": [
        "leads:capture"
      ],
      "suggested_preset": "read_only",
      "required_permission": "stripeConnect.view"
    }
  }
}
429

Limite de débit atteinte. rate_limit_exceeded : le quota horaire de la clé est épuisé. too_many_attempts : trop de clés invalides présentées depuis cette adresse IP (protection contre la force brute). Dans les deux cas, Retry-After donne le délai en secondes.

rate_limit_exceeded
{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Limite de requêtes atteinte.",
    "hint": "Réessaie après le nombre de secondes indiqué dans retry_after_seconds, et envisage d'implémenter un backoff exponentiel.",
    "doc_url": "https://capturia.io/fr/developers/api/v1/rate-limits",
    "request_id": "req_01J9X8Z3F4K2M5N7P9Q1R3S5T7",
    "details": {
      "limit": 100,
      "count": 100,
      "limit_type": "per_key",
      "retry_after_seconds": 42
    }
  }
}
too_many_attempts
{
  "error": {
    "type": "rate_limit_error",
    "code": "too_many_attempts",
    "message": "Trop de tentatives d'authentification invalides depuis cette IP.",
    "hint": "Attends la période indiquée par retry_after_seconds avant de réessayer.",
    "doc_url": "https://capturia.io/fr/developers/api/v1/authentication#brute-force",
    "request_id": "req_01J9X8Z3F4K2M5N7P9Q1R3S5T7",
    "details": {
      "limit_type": "brute_force",
      "retry_after_seconds": 300
    }
  }
}
500

Erreur serveur inattendue. Toujours fournir le request_id au support.

internal_error
{
  "error": {
    "type": "server_error",
    "code": "internal_error",
    "message": "Erreur serveur. L'équipe Capturia a été notifiée.",
    "hint": "Si le problème persiste, contacte le support en incluant le request_id de cette réponse.",
    "doc_url": "https://capturia.io/fr/developers/api/v1/errors#internal_error",
    "request_id": "req_01J9X8Z3F4K2M5N7P9Q1R3S5T7"
  }
}
501

Les clés de test (cap_test_) ne sont pas encore servies : seules les clés cap_live_ sont acceptées.

not_implemented
{
  "error": {
    "type": "server_error",
    "code": "not_implemented",
    "message": "Cette fonctionnalité n'est pas encore implémentée.",
    "hint": "Consulte la documentation API pour les fonctionnalités disponibles et le changelog pour les prochaines versions.",
    "doc_url": "https://capturia.io/fr/developers/api/v1/errors#not_implemented",
    "request_id": "req_01J9X8Z3F4K2M5N7P9Q1R3S5T7"
  }
}
503

Un service dont la requête dépend n'a pas répondu (lecture de la clé, du compte ou du forfait). La même requête passera quand il reviendra : réessaie après le délai de Retry-After.

service_unavailable
{
  "error": {
    "type": "server_error",
    "code": "service_unavailable",
    "message": "Service temporairement indisponible.",
    "hint": "Réessaie après la période indiquée par Retry-After.",
    "doc_url": "https://capturia.io/fr/developers/api/v1/errors#service_unavailable",
    "request_id": "req_01J9X8Z3F4K2M5N7P9Q1R3S5T7"
  }
}

Exemple de requête

curl -X GET 'https://api.capturia.io/v1/payments' \
  -H 'Authorization: Bearer cap_live_<your-key>' \
  -H 'Content-Type: application/json'
get/v1/payment-documents/{id}

Lire un reçu ou une note de crédit, avec son PDF

Retourne une pièce d'un paiement du compte : un reçu, ou la note de crédit d'un remboursement, avec le détail de ses taxes et un lien de son PDF valable 15 minutes. C'est la lecture qui suit un événement receipt_issued ou credit_note_issued, dont data.resource_id est l'identifiant de la pièce.

Un reçu réémis au bon nom nomme celui qu'il remplace (replaces_document_id), et le reçu remplacé porte replaced_at.

Une pièce d'un autre compte est introuvable (404). Si le PDF ne peut pas être préparé à l'instant, la pièce répond 503 service_unavailable : relis-la après Retry-After.

Scopes requis : payments:read

Paramètres de chemin

NomTypeObligatoireDescription
idstringobligatoireUUID de la ressource.

Réponses

StatutDescription
200

La pièce et le lien de son PDF.

401

La clé API manque, est inconnue ou a expiré. code distingue les trois causes : missing_api_key (aucun en-tête Authorization: Bearer), invalid_api_key (clé inconnue, révoquée ou de format invalide) et expired_api_key (date d'expiration dépassée).

missing_api_key
{
  "error": {
    "type": "authentication_error",
    "code": "missing_api_key",
    "message": "Aucune clé API n'a été fournie.",
    "hint": "Ajoute un header Authorization sous la forme : Bearer cap_live_<ta_clé>",
    "doc_url": "https://capturia.io/fr/developers/api/v1/authentication#missing_api_key",
    "request_id": "req_01J9X8Z3F4K2M5N7P9Q1R3S5T7"
  }
}
invalid_api_key
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "La clé API est invalide ou a été révoquée.",
    "hint": "Vérifie la clé dans ton dashboard ou génère-en une nouvelle.",
    "doc_url": "https://capturia.io/fr/developers/api/v1/authentication#invalid_api_key",
    "request_id": "req_01J9X8Z3F4K2M5N7P9Q1R3S5T7"
  }
}
expired_api_key
{
  "error": {
    "type": "authentication_error",
    "code": "expired_api_key",
    "message": "La clé API a expiré.",
    "hint": "Roule la clé depuis le dashboard pour en générer une nouvelle valide.",
    "doc_url": "https://capturia.io/fr/developers/api/v1/authentication#expired_api_key",
    "request_id": "req_01J9X8Z3F4K2M5N7P9Q1R3S5T7"
  }
}
403

Refus d'autorisation. code distingue les refus que l'opération rend sous ce statut, et chaque exemple en montre un.

browser_not_allowed
{
  "error": {
    "type": "authorization_error",
    "code": "browser_not_allowed",
    "message": "Les clés API s'utilisent depuis un serveur, jamais depuis un navigateur.",
    "hint": "La requête porte un en-tête `Origin` : appelle l'API depuis ton serveur, où la clé reste secrète.",
    "doc_url": "https://capturia.io/fr/developers/api/v1/errors#browser_not_allowed",
    "request_id": "req_01J9X8Z3F4K2M5N7P9Q1R3S5T7"
  }
}
account_suspended
{
  "error": {
    "type": "authorization_error",
    "code": "account_suspended",
    "message": "L'accès à ce compte est suspendu par l'équipe Capturia.",
    "hint": "Le refus vient du compte, pas de la clé. Tant que la suspension dure, aucune requête n'est acceptée : contacte l'équipe Capturia.",
    "doc_url": "https://capturia.io/fr/developers/api/v1/authentication#account_suspended",
    "request_id": "req_01J9X8Z3F4K2M5N7P9Q1R3S5T7"
  }
}
feature_not_available
{
  "error": {
    "type": "authorization_error",
    "code": "feature_not_available",
    "message": "Cette fonctionnalité n'est pas incluse dans ton forfait.",
    "hint": "Le refus vient du forfait du compte, pas de la clé. Contacte ton conseiller Capturia pour en parler.",
    "doc_url": "https://capturia.io/fr/developers/api/v1/authentication#plan",
    "request_id": "req_01J9X8Z3F4K2M5N7P9Q1R3S5T7",
    "details": {
      "feature": "public_api"
    }
  }
}
insufficient_scope
{
  "error": {
    "type": "authorization_error",
    "code": "insufficient_scope",
    "message": "Cette clé API ne contient pas le scope requis pour ce point d'accès.",
    "hint": "Cette clé n'a pas le scope `payments:read`. Crée une nouvelle clé avec le preset « Lecture seule » ou ajoute le scope via le dashboard.",
    "doc_url": "https://capturia.io/fr/developers/api/v1/authentication#scopes",
    "dashboard_url": "https://capturia.io/platform/dashboard/admin/integrations/api-keys/6f1e2d3c-4b5a-4c6d-8e7f-9a0b1c2d3e4f?tab=permissions",
    "request_id": "req_01J9X8Z3F4K2M5N7P9Q1R3S5T7",
    "details": {
      "required_scope": "payments:read",
      "current_scopes": [
        "leads:capture"
      ],
      "suggested_preset": "read_only",
      "required_permission": "stripeConnect.view"
    }
  }
}
404

Ressource introuvable. code distingue les refus que l'opération rend sous ce statut, et chaque exemple en montre un.

not_found
{
  "error": {
    "type": "not_found_error",
    "code": "not_found",
    "message": "La ressource demandée est introuvable.",
    "hint": "`details.resource` nomme la ressource cherchée. Vérifie son identifiant : elle a peut-être été supprimée, ou elle appartient à un autre compte.",
    "doc_url": "https://capturia.io/fr/developers/api/v1/errors#not_found",
    "request_id": "req_01J9X8Z3F4K2M5N7P9Q1R3S5T7",
    "details": {
      "resource": "payment_document"
    }
  }
}
429

Limite de débit atteinte. rate_limit_exceeded : le quota horaire de la clé est épuisé. too_many_attempts : trop de clés invalides présentées depuis cette adresse IP (protection contre la force brute). Dans les deux cas, Retry-After donne le délai en secondes.

rate_limit_exceeded
{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Limite de requêtes atteinte.",
    "hint": "Réessaie après le nombre de secondes indiqué dans retry_after_seconds, et envisage d'implémenter un backoff exponentiel.",
    "doc_url": "https://capturia.io/fr/developers/api/v1/rate-limits",
    "request_id": "req_01J9X8Z3F4K2M5N7P9Q1R3S5T7",
    "details": {
      "limit": 100,
      "count": 100,
      "limit_type": "per_key",
      "retry_after_seconds": 42
    }
  }
}
too_many_attempts
{
  "error": {
    "type": "rate_limit_error",
    "code": "too_many_attempts",
    "message": "Trop de tentatives d'authentification invalides depuis cette IP.",
    "hint": "Attends la période indiquée par retry_after_seconds avant de réessayer.",
    "doc_url": "https://capturia.io/fr/developers/api/v1/authentication#brute-force",
    "request_id": "req_01J9X8Z3F4K2M5N7P9Q1R3S5T7",
    "details": {
      "limit_type": "brute_force",
      "retry_after_seconds": 300
    }
  }
}
500

Erreur serveur inattendue. Toujours fournir le request_id au support.

internal_error
{
  "error": {
    "type": "server_error",
    "code": "internal_error",
    "message": "Erreur serveur. L'équipe Capturia a été notifiée.",
    "hint": "Si le problème persiste, contacte le support en incluant le request_id de cette réponse.",
    "doc_url": "https://capturia.io/fr/developers/api/v1/errors#internal_error",
    "request_id": "req_01J9X8Z3F4K2M5N7P9Q1R3S5T7"
  }
}
501

Les clés de test (cap_test_) ne sont pas encore servies : seules les clés cap_live_ sont acceptées.

not_implemented
{
  "error": {
    "type": "server_error",
    "code": "not_implemented",
    "message": "Cette fonctionnalité n'est pas encore implémentée.",
    "hint": "Consulte la documentation API pour les fonctionnalités disponibles et le changelog pour les prochaines versions.",
    "doc_url": "https://capturia.io/fr/developers/api/v1/errors#not_implemented",
    "request_id": "req_01J9X8Z3F4K2M5N7P9Q1R3S5T7"
  }
}
503

Un service dont la requête dépend n'a pas répondu (lecture de la clé, du compte ou du forfait). La même requête passera quand il reviendra : réessaie après le délai de Retry-After.

service_unavailable
{
  "error": {
    "type": "server_error",
    "code": "service_unavailable",
    "message": "Service temporairement indisponible.",
    "hint": "Réessaie après la période indiquée par Retry-After.",
    "doc_url": "https://capturia.io/fr/developers/api/v1/errors#service_unavailable",
    "request_id": "req_01J9X8Z3F4K2M5N7P9Q1R3S5T7"
  }
}

Exemple de requête

curl -X GET 'https://api.capturia.io/v1/payment-documents/{id}' \
  -H 'Authorization: Bearer cap_live_<your-key>' \
  -H 'Content-Type: application/json'