Capturia measures its ads and site traffic with the Meta pixel and Google Analytics. You can decline at any time. Learn more

FR

Payments

2 endpoints

get/v1/payments

List collected payments and their documents

Returns the paginated list (v2 cursor) of payments collected by the key's account, from all their sources: quotes and proposals, funnels, manually recorded payments, direct Stripe payments, Space memberships. Each payment carries its documents: its current receipt and the credit notes of its refunds, whose PDF is read through GET /v1/payment-documents/{id}.

Stable sort paid_at DESC, id DESC: the most recently collected first. With updated_after or updated_before, the list is sorted by ascending updated_at: a payment comes back when it is recorded, refunded or linked to a contact, or when one of its documents is issued or voided.

Filters

  • ?contact_id (uuid) — the payments of one of the account's contacts. A value that isn't a UUID returns 400 invalid_request (details.field = contact_id).

Pending or failed payments aren't listed: the payment_failed event announces them. A payment of another account never appears.

Required scopes: payments:read

Query parameters

NameTypeRequiredDescription
cursorstring | nulloptionalOpaque pagination cursor: pass the pagination.next_cursor value from the previous page.
limitintegeroptionalMaximum number of results per page (default 20, max 100). Above that → 400 invalid_request.
updated_afterstringoptionalFilter: only resources modified after this date (inclusive). With an updated_* bound, the list is sorted by ascending updated_at (oldest change first), tie-broken by id. Restart from the updated_at of the last resource you read, minus 2 minutes: a long write can carry a date slightly earlier than the end of your read. Drop duplicates by id. A cursor from another sort is refused (cursor_field_mismatch). A list that leaves archived resources out (bookings, quotes) returns them in this read with their archived_at: that is how a withdrawal is read.
updated_beforestringoptionalFilter: only resources modified before this date (inclusive). Sorts the list like updated_after.
contact_idstringoptionalOnly payments for this contact.

Responses

StatusDescription
200

Paginated list of collected payments.

400

Invalid request. code tells apart the refusals the operation returns under this status, and each example shows one.

invalid_requestlimit · exceeds_max
{
  "error": {
    "type": "validation_error",
    "code": "invalid_request",
    "message": "Request format is invalid.",
    "hint": "Check that headers, body and JSON encoding match the API contract documented in the API Reference.",
    "doc_url": "https://capturia.io/en/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": "Request format is invalid.",
    "hint": "Check that headers, body and JSON encoding match the API contract documented in the API Reference.",
    "doc_url": "https://capturia.io/en/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": "Request format is invalid.",
    "hint": "Check that headers, body and JSON encoding match the API contract documented in the API Reference.",
    "doc_url": "https://capturia.io/en/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": "Request format is invalid.",
    "hint": "Check that headers, body and JSON encoding match the API contract documented in the API Reference.",
    "doc_url": "https://capturia.io/en/developers/api/v1/errors#invalid_request",
    "request_id": "req_01J9X8Z3F4K2M5N7P9Q1R3S5T7",
    "details": {
      "field": "contact_id",
      "reason": "invalid_format"
    }
  }
}
401

The API key is missing, unknown or expired. code tells the three causes apart: missing_api_key (no Authorization: Bearer header), invalid_api_key (unknown or revoked key, or invalid format) and expired_api_key (expiration date has passed).

missing_api_key
{
  "error": {
    "type": "authentication_error",
    "code": "missing_api_key",
    "message": "No API key was provided.",
    "hint": "Add an Authorization header in the form: Bearer cap_live_<your_key>",
    "doc_url": "https://capturia.io/en/developers/api/v1/authentication#missing_api_key",
    "request_id": "req_01J9X8Z3F4K2M5N7P9Q1R3S5T7"
  }
}
invalid_api_key
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "API key is invalid or has been revoked.",
    "hint": "Verify the key in your dashboard or generate a new one.",
    "doc_url": "https://capturia.io/en/developers/api/v1/authentication#invalid_api_key",
    "request_id": "req_01J9X8Z3F4K2M5N7P9Q1R3S5T7"
  }
}
expired_api_key
{
  "error": {
    "type": "authentication_error",
    "code": "expired_api_key",
    "message": "API key has expired.",
    "hint": "Roll the key from the dashboard to generate a new valid one.",
    "doc_url": "https://capturia.io/en/developers/api/v1/authentication#expired_api_key",
    "request_id": "req_01J9X8Z3F4K2M5N7P9Q1R3S5T7"
  }
}
403

Authorization refused. code tells apart the refusals the operation returns under this status, and each example shows one.

browser_not_allowed
{
  "error": {
    "type": "authorization_error",
    "code": "browser_not_allowed",
    "message": "API keys must be used from a server, never from a browser.",
    "hint": "The request carries an `Origin` header: call the API from your server, where the key stays secret.",
    "doc_url": "https://capturia.io/en/developers/api/v1/errors#browser_not_allowed",
    "request_id": "req_01J9X8Z3F4K2M5N7P9Q1R3S5T7"
  }
}
account_suspended
{
  "error": {
    "type": "authorization_error",
    "code": "account_suspended",
    "message": "Access to this account is suspended by the Capturia team.",
    "hint": "The refusal comes from the account, not the key. While the suspension lasts, no request is accepted: contact the Capturia team.",
    "doc_url": "https://capturia.io/en/developers/api/v1/authentication#account_suspended",
    "request_id": "req_01J9X8Z3F4K2M5N7P9Q1R3S5T7"
  }
}
feature_not_available
{
  "error": {
    "type": "authorization_error",
    "code": "feature_not_available",
    "message": "This feature is not included in your plan.",
    "hint": "The rejection comes from the account's plan, not the key. Contact your Capturia advisor to talk it over.",
    "doc_url": "https://capturia.io/en/developers/api/v1/authentication#plan",
    "request_id": "req_01J9X8Z3F4K2M5N7P9Q1R3S5T7",
    "details": {
      "feature": "public_api"
    }
  }
}
insufficient_scope
{
  "error": {
    "type": "authorization_error",
    "code": "insufficient_scope",
    "message": "This API key does not contain the required scope for this endpoint.",
    "hint": "This key is missing the `payments:read` scope. Create a new key with the \"Read only\" preset or add the scope via the dashboard.",
    "doc_url": "https://capturia.io/en/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

Rate limit reached. rate_limit_exceeded: the key's hourly quota is used up. too_many_attempts: too many invalid keys presented from this IP address (brute-force protection). In both cases, Retry-After gives the delay in seconds.

rate_limit_exceeded
{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded.",
    "hint": "Retry after the number of seconds in retry_after_seconds, and consider implementing exponential backoff.",
    "doc_url": "https://capturia.io/en/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": "Too many invalid authentication attempts from this IP.",
    "hint": "Wait the period indicated by retry_after_seconds before trying again.",
    "doc_url": "https://capturia.io/en/developers/api/v1/authentication#brute-force",
    "request_id": "req_01J9X8Z3F4K2M5N7P9Q1R3S5T7",
    "details": {
      "limit_type": "brute_force",
      "retry_after_seconds": 300
    }
  }
}
500

Unexpected server error. Always include the request_id when contacting support.

internal_error
{
  "error": {
    "type": "server_error",
    "code": "internal_error",
    "message": "Server error. The Capturia team has been notified.",
    "hint": "If this persists, contact support and include the request_id from this response.",
    "doc_url": "https://capturia.io/en/developers/api/v1/errors#internal_error",
    "request_id": "req_01J9X8Z3F4K2M5N7P9Q1R3S5T7"
  }
}
501

Test keys (cap_test_) aren't served yet: only cap_live_ keys are accepted.

not_implemented
{
  "error": {
    "type": "server_error",
    "code": "not_implemented",
    "message": "This feature is not yet implemented.",
    "hint": "Check the API documentation for available features and the changelog for upcoming releases.",
    "doc_url": "https://capturia.io/en/developers/api/v1/errors#not_implemented",
    "request_id": "req_01J9X8Z3F4K2M5N7P9Q1R3S5T7"
  }
}
503

A service the request depends on didn't respond (reading the key, the account or the plan). The same request will go through once it's back: retry after the Retry-After delay.

service_unavailable
{
  "error": {
    "type": "server_error",
    "code": "service_unavailable",
    "message": "Service temporarily unavailable.",
    "hint": "Retry after the period indicated by Retry-After.",
    "doc_url": "https://capturia.io/en/developers/api/v1/errors#service_unavailable",
    "request_id": "req_01J9X8Z3F4K2M5N7P9Q1R3S5T7"
  }
}

Example request

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}

Read a receipt or a credit note, with its PDF

Returns one document of a payment of the account: a receipt, or the credit note of a refund, with its tax breakdown and a link to its PDF valid for 15 minutes. This is the read that follows a receipt_issued or credit_note_issued event, whose data.resource_id is the document's identifier.

A receipt reissued under the right name names the one it replaces (replaces_document_id), and the replaced receipt carries replaced_at.

A document of another account is not found (404). If the PDF can't be prepared right now, the document returns 503 service_unavailable: read it again after Retry-After.

Required scopes: payments:read

Path parameters

NameTypeRequiredDescription
idstringrequiredUUID of the resource.

Responses

StatusDescription
200

The document and the link to its PDF.

401

The API key is missing, unknown or expired. code tells the three causes apart: missing_api_key (no Authorization: Bearer header), invalid_api_key (unknown or revoked key, or invalid format) and expired_api_key (expiration date has passed).

missing_api_key
{
  "error": {
    "type": "authentication_error",
    "code": "missing_api_key",
    "message": "No API key was provided.",
    "hint": "Add an Authorization header in the form: Bearer cap_live_<your_key>",
    "doc_url": "https://capturia.io/en/developers/api/v1/authentication#missing_api_key",
    "request_id": "req_01J9X8Z3F4K2M5N7P9Q1R3S5T7"
  }
}
invalid_api_key
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "API key is invalid or has been revoked.",
    "hint": "Verify the key in your dashboard or generate a new one.",
    "doc_url": "https://capturia.io/en/developers/api/v1/authentication#invalid_api_key",
    "request_id": "req_01J9X8Z3F4K2M5N7P9Q1R3S5T7"
  }
}
expired_api_key
{
  "error": {
    "type": "authentication_error",
    "code": "expired_api_key",
    "message": "API key has expired.",
    "hint": "Roll the key from the dashboard to generate a new valid one.",
    "doc_url": "https://capturia.io/en/developers/api/v1/authentication#expired_api_key",
    "request_id": "req_01J9X8Z3F4K2M5N7P9Q1R3S5T7"
  }
}
403

Authorization refused. code tells apart the refusals the operation returns under this status, and each example shows one.

browser_not_allowed
{
  "error": {
    "type": "authorization_error",
    "code": "browser_not_allowed",
    "message": "API keys must be used from a server, never from a browser.",
    "hint": "The request carries an `Origin` header: call the API from your server, where the key stays secret.",
    "doc_url": "https://capturia.io/en/developers/api/v1/errors#browser_not_allowed",
    "request_id": "req_01J9X8Z3F4K2M5N7P9Q1R3S5T7"
  }
}
account_suspended
{
  "error": {
    "type": "authorization_error",
    "code": "account_suspended",
    "message": "Access to this account is suspended by the Capturia team.",
    "hint": "The refusal comes from the account, not the key. While the suspension lasts, no request is accepted: contact the Capturia team.",
    "doc_url": "https://capturia.io/en/developers/api/v1/authentication#account_suspended",
    "request_id": "req_01J9X8Z3F4K2M5N7P9Q1R3S5T7"
  }
}
feature_not_available
{
  "error": {
    "type": "authorization_error",
    "code": "feature_not_available",
    "message": "This feature is not included in your plan.",
    "hint": "The rejection comes from the account's plan, not the key. Contact your Capturia advisor to talk it over.",
    "doc_url": "https://capturia.io/en/developers/api/v1/authentication#plan",
    "request_id": "req_01J9X8Z3F4K2M5N7P9Q1R3S5T7",
    "details": {
      "feature": "public_api"
    }
  }
}
insufficient_scope
{
  "error": {
    "type": "authorization_error",
    "code": "insufficient_scope",
    "message": "This API key does not contain the required scope for this endpoint.",
    "hint": "This key is missing the `payments:read` scope. Create a new key with the \"Read only\" preset or add the scope via the dashboard.",
    "doc_url": "https://capturia.io/en/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

Resource not found. code tells apart the refusals the operation returns under this status, and each example shows one.

not_found
{
  "error": {
    "type": "not_found_error",
    "code": "not_found",
    "message": "The requested resource was not found.",
    "hint": "`details.resource` names the resource looked up. Check its ID: it may have been deleted, or it belongs to another account.",
    "doc_url": "https://capturia.io/en/developers/api/v1/errors#not_found",
    "request_id": "req_01J9X8Z3F4K2M5N7P9Q1R3S5T7",
    "details": {
      "resource": "payment_document"
    }
  }
}
429

Rate limit reached. rate_limit_exceeded: the key's hourly quota is used up. too_many_attempts: too many invalid keys presented from this IP address (brute-force protection). In both cases, Retry-After gives the delay in seconds.

rate_limit_exceeded
{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded.",
    "hint": "Retry after the number of seconds in retry_after_seconds, and consider implementing exponential backoff.",
    "doc_url": "https://capturia.io/en/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": "Too many invalid authentication attempts from this IP.",
    "hint": "Wait the period indicated by retry_after_seconds before trying again.",
    "doc_url": "https://capturia.io/en/developers/api/v1/authentication#brute-force",
    "request_id": "req_01J9X8Z3F4K2M5N7P9Q1R3S5T7",
    "details": {
      "limit_type": "brute_force",
      "retry_after_seconds": 300
    }
  }
}
500

Unexpected server error. Always include the request_id when contacting support.

internal_error
{
  "error": {
    "type": "server_error",
    "code": "internal_error",
    "message": "Server error. The Capturia team has been notified.",
    "hint": "If this persists, contact support and include the request_id from this response.",
    "doc_url": "https://capturia.io/en/developers/api/v1/errors#internal_error",
    "request_id": "req_01J9X8Z3F4K2M5N7P9Q1R3S5T7"
  }
}
501

Test keys (cap_test_) aren't served yet: only cap_live_ keys are accepted.

not_implemented
{
  "error": {
    "type": "server_error",
    "code": "not_implemented",
    "message": "This feature is not yet implemented.",
    "hint": "Check the API documentation for available features and the changelog for upcoming releases.",
    "doc_url": "https://capturia.io/en/developers/api/v1/errors#not_implemented",
    "request_id": "req_01J9X8Z3F4K2M5N7P9Q1R3S5T7"
  }
}
503

A service the request depends on didn't respond (reading the key, the account or the plan). The same request will go through once it's back: retry after the Retry-After delay.

service_unavailable
{
  "error": {
    "type": "server_error",
    "code": "service_unavailable",
    "message": "Service temporarily unavailable.",
    "hint": "Retry after the period indicated by Retry-After.",
    "doc_url": "https://capturia.io/en/developers/api/v1/errors#service_unavailable",
    "request_id": "req_01J9X8Z3F4K2M5N7P9Q1R3S5T7"
  }
}

Example request

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