Changelog

Every change to the public API is recorded here, dated, whether or not it breaks anything. Deprecations and sunsets are announced here in addition to the Deprecation and Sunset headers — see Versioning & deprecation.

Dates are the date of the change, in YYYY-MM-DD.

2026-09-25 — Webhooks: checkout_link.completed is delivered

Added

• When a donation on a checkout link is approved, Vaki now POSTs checkout_link.completed to the link’s callback_url (or your client’s webhookUrl), signed with your per-client secret (Vaki-Signature: t=<iso8601>,v1=<hmac-sha256>), at-least-once, with six retries over ~20 hours. Ask Vaki for your signing secret; without one nothing is delivered. Contract and reference verifier: Webhook endpoints.
• GET /v1/checkout_links?external_reference=… lists every link you minted with that reference, newest first, with live statuses — the read half of traceability.
• callback_delivery on GET /v1/checkout_links/{id}: where the delivery stands (pending / delivered / failed, attempts, last status code).
• latest_attempt on both link reads (since 2026-09-24): the newest bank-rail attempt on an open link and whether the bank is still deciding or said no.

2026-08-25 — Fees documented as they actually work

Changed (documentation only — no API behaviour changed)

• The Fees page now documents the two fee models the API has always exposed: plus_gateway_costs — the platform default, Vaki’s commission (5% for API-created causes) plus the gateway’s own cost, both deducted from the cause — and all_inclusive, a single flat rate by agreement under which Vaki absorbs the gateway’s cost.
• The previous claim that the 5% commission absorbed gateway costs was wrong and is corrected below. What the donor pays never changed: exactly the donation amount, with no surcharge at checkout.

2026-08-17 — v1 and these docs

The first public version of the Vaki API.

Rollout in progress

/v1 is routed and its contracts are final. A route whose implementation has not landed yet answers 501 with not_implemented instead of pretending to work. This entry will be amended with the date each route began serving in production — until then, treat a 501 as “not yet”, not as a bug in your integration.

Added

• POST /v1/checkout_links — mint a hosted checkout URL for a cause. Accepts vaki, amount, currency as required fields, plus email, external_reference, callback_url, success_url, cancel_url, anonymous and metadata. Returns url, which you redirect the donor to.
• GET /v1/checkout_links/{id} — read a link’s status: open, completed, expired or cancelled. This is how a donation is confirmed until webhook delivery ships.
• POST /v1/vakis — create a cause in draft. The owner must already be a registered Vaki account.
• GET /v1/vakis/{key} — read a cause.
• Idempotency-Key on both POST routes, with replay semantics documented in Idempotency.
• RFC 9457 problem documents with stable machine codes on every error, a full code table in Errors, and a page per code at developers.vaki.co/errors/{code} — the type member of an error response is a URL you can open.
• A second server in the OpenAPI document: a sandbox base URL, public-api-staging.vaki.co, running the same /v1 code on Vaki’s staging deployment with its own keys and its own data. Read Sandbox before you rely on it — it is shared infrastructure we deploy to constantly, so its data may be reset and it can be briefly unavailable. Test-mode keys (vk_test_) against production uptime remain the durable plan.
• The published intent for US giving through the Vaki USA Foundation, an IRS-approved 501(c)(3): an entity-scoped API key, where a Foundation key mints checkout links that collect into the Foundation’s own Stripe account and the entity is recorded on the link and the payment. Being built, not issuable yet, and there is a governance constraint that matters more than the plumbing — see US giving via the Vaki USA Foundation and Known limitations.
• This documentation site, with the API reference generated from the service’s own route definitions rather than maintained by hand, and an Examples switcher in the header that flips every code block — and the copy button’s clipboard text — between the production and sandbox base URLs.

Policy

• 5% flat on collected donations, with Vaki absorbing the gateway’s own cost. The donor is never charged a separate processing fee. See Fees. Corrected 2026-08-25: the commission does not absorb gateway costs — see the entry above.
• URL major versioning, additive changes without a version bump, a 12-month support window on a superseded prefix, and a 90-day minimum notice before any removal. See Versioning & deprecation.
• Cause state is exposed as stable English snake_case on this API, independently of how Vaki stores it internally.

Not included, deliberately

• Webhook delivery. callback_url is accepted, validated and stored, but nothing is delivered to it yet. Set the field now — your code will not change when delivery ships — and poll GET /v1/checkout_links/{id} meanwhile.
• Test mode. There is no vk_test_ key and no sandbox. Keys are live.
• List endpoints. Retrieval by id only. Persist the chl_… you get back.
• The other eight endpoints — webhook subscriptions, cause updates, finances, verification, bank accounts, provider and creator onboarding, withdrawals. Their intended contracts are published under Coming soon so you can design against them. They are not callable.

All of the above is spelled out in Known limitations.

Known issue

• A donor whose email already belongs to a registered Vaki account is asked to log in at checkout instead of paying as a guest. Test with fresh addresses. A fix is in flight.