Skip to main content
These standards apply to every endpoint under https://api.quidkey.com/v1. An endpoint that departs from one says so in its reference, and why.
  • One shape per resource. A resource is represented the same way by every endpoint that returns it.
  • One document shape. Every successful JSON response has the same structure, whether it holds one resource or a hundred.
  • Invalid input is refused. An unknown field, an ambiguous value or an amount we can’t represent answers an error. It’s never guessed at, rounded or dropped.
  • Changes. We add to the API without notice, and change or remove what’s published only as Versioning describes.

Representations and Views

Each resource has a full representation, and some also have a summary, with the fields needed to display or choose between resources. The view a response holds is in its _view field. A single read takes ?view= to choose any view the resource documents, and a list returns its documented view.
  • A summary is a strict subset of the full representation, with the same names, types and meanings.
  • A representation looks the same wherever it appears: from a list, a read, a create, an update or an action.
  • A representation doesn’t vary by caller. If you can read a resource, you see what anyone else who can read it sees.
  • Every field is always present. An empty value is null, and an empty collection is []. The one exception is a one-time value, such as a secret, which appears only in the response that issues it. See Idempotency.
  • Sensitive values, such as bank account numbers, aren’t returned in full.
Every resource carries these fields: Fields starting with an underscore belong to the protocol. All other fields belong to the resource. A relationship is always a link object, never a bare ID, with the same shape for every resource:
Anything else in a link object describes the relationship, not the target, such as is_default on a country’s payment scheme. A link gives no access of its own. A response can link to a resource you can’t read, and fetching it answers 403 or 404.

URIs

A resource has exactly one canonical URI, flat wherever its ID is unique, such as /transactions/tx_1. A sub-collection such as /merchants/m_1/transactions returns resources carrying those canonical URIs. URIs are relative to the version root and don’t contain /v1, so resolve one against your base URL, https://api.quidkey.com/v1. A URI never changes for the life of the resource.

Response Documents

A successful response has three parts:
  • result holds what you asked for: one resource, or an array for a list.
  • entities holds linked resources, keyed by URI: those the endpoint includes by default, and those you ask for with include.
  • not_included lists the links that should have been included but couldn’t be.
Reading a refund, with ?view=summary to keep it short:
The same read with ?include=merchant leaves result unchanged and fills entities, so a client finds a linked resource the same way every time:
A list is an array of the same representation in result, with pagination beside it. See Collections.

Including Linked Resources

  • include takes a comma-separated list of link fields, one level deep: ?include=merchant,customer_details. An unknown field answers 400. Each endpoint’s reference lists what it can include.
  • Sending include replaces the endpoint’s default inclusions, so ?include= with no value includes nothing.
  • Including an array of links hydrates each one. A collection link can’t be included: follow it instead.
  • Each URI appears once in entities, however many links point to it. An included resource is in entities even when it’s also in result.
  • A representation is identical in result, in entities and when you fetch its _uri with the same view.
  • A direct read and the response to a write are authoritative. A resource in a list can be slightly older than a direct read.
A resource that should be included but can’t be read is left out of entities and listed in not_included, with its link and a reason. result stays the same.
A link you didn’t include has no entity. Fetch its URI if you need it.

Formats

Money

Money is always an object, with an integer value in the currency’s ISO 4217 minor units and its currency code:
  • GBP 45.00 is 4500. Each amount carries its own currency, so two amounts in one resource can differ.
  • The same form is used in requests and responses. Two places write money otherwise: a file writes an amount as a decimal in major units, and an event’s earlier fields write it in their own forms, such as a string of minor units with its currency beside it.
  • A decimal value is refused, not rounded, and so is a currency we can’t process.

Rates

A rate is a decimal string holding a fraction: "0.0500" means 5%. Parse it as a decimal, and don’t assume a number of places: it has at most 8, and trailing zeros aren’t significant. A field holding a percentage is named *_percent, such as ownership_percent.

Points

Reward points, as in extra_rewards and total_rewards, are a decimal string, not money: "12.50". A response gives exactly 2 decimal places, and a request takes at most 2.

Dates and Times

A timestamp means what its name says: sent_at is when a payout was sent, never when its record last changed.

Other Values

Input is parsed and output is canonical, so a time sent with +00:00 comes back with Z. A value we can’t represent is refused, never dropped.

Names

  • Fields and parameters are snake_case, and path segments are kebab-case.
  • An action is named in lowerCamelCase, after a colon: :issueCheckout.
  • Collections are plural and singletons are singular, as in /merchants/m_1/onboarding.
  • Booleans read as predicates: is_test, has_more, can_refund.
  • Enum values are lowercase snake_case. We spell cancelled with two Ls.
  • A resource that reports why something failed carries failure, an object with at least code and message, or null.