generated: '2026-07-21'
method: searched
source: https://docs.tiptop.com/
description: >-
  Cross-cutting request/response conventions of the Tiptop Direct integration,
  captured from docs.tiptop.com and the first-party Magento gateway source.
  Tiptop's API surface is small — a browser checkout flow (tiptop.js) plus
  three server-side order-management endpoints — so several conventions common
  to larger APIs (pagination, field expansion, idempotency keys) are simply not
  part of the published contract.
base_url: https://api.tiptop.com/ (production host; documented staging default is https://api-stage.tiptop.com/)
api_style: REST over HTTPS, JSON requests and responses
versioning:
  scheme: uri-path
  current: v1
  evidence: All documented endpoints are under /v1/ (e.g. /v1/direct/order/capture-request).
authentication:
  scheme: API key in the api-key request header (server) / public_api_key in tiptop.js config (browser)
  detail: authentication/tiptop-authentication.yml
idempotency:
  supported: false
  notes: >-
    No idempotency-key mechanism is documented anywhere on docs.tiptop.com or
    in the first-party gateway code. Capture/void/refund requests are keyed to
    the partner-generated orderID, but replay semantics are not documented.
pagination:
  supported: false
  notes: No list endpoints are documented; the published API surface has no pagination contract.
amounts:
  convention: integer cents
  evidence: >-
    totalCost, taxCost, shippingCost, item amount, and discountAmount are all
    documented as amounts in cents (e.g. $100 = 10000); currency is an ISO
    code string (i.e. USD).
identifiers:
  orderID: >-
    Partner-generated order identifier — "the one generated by your
    integration" — used to address orders on capture/void/refund. The checkout
    success callback returns a checkout_id used for checkout authorization.
error_envelope:
  style: HTTP status codes only (201/400/401/403/422/500); no documented error body schema
  detail: errors/tiptop-problem-types.yml
request_tracing:
  supported: false
  notes: No request-id header is documented.
rate_limits:
  documented: false
partial_operations:
  notes: >-
    Void and refund accept an optional amount field for partial cancellation /
    partial refund; the amount must be less than the order total.
cross_links:
  authentication: authentication/tiptop-authentication.yml
  errors: errors/tiptop-problem-types.yml
  lifecycle: lifecycle/tiptop-lifecycle.yml
  sandbox: sandbox/tiptop-sandbox.yml