Known limitations

Everything on this page is a real constraint in the current release. We would rather you read it here than discover it in production.

`/v1` is rolling out, and an unimplemented route says so

The four /v1 routes are routed and their contracts are final. A route whose implementation has not landed answers 501 with not_implemented and a detail naming the route — rather than a 404, a 500, or worse, a plausible-looking empty object.

The changelog is the record of what is actually serving in production. Check it first when a call returns 501. And do not retry a 501: it will not start working on the next attempt.

Webhook delivery is not live

callback_url on POST /v1/checkout_links is accepted, validated and stored — but nothing is delivered to it yet. There is no outbound webhook system in production today.

Set the field anyway. Your integration code will not change when delivery ships; you will simply start receiving what you are currently polling for.

In the meantime, poll:

curl https://api.vaki.cohttps://public-api-staging.vaki.co/v1/checkout_links/chl_01J9Z4M2K7QF3B \
  -H "Authorization: Bearer $VAKI_API_KEY"

status moves open → completed. Poll when the donor returns to your success_url, then every 30–60 seconds for a few minutes, backing off, and stop at a terminal status. Do not poll every link you have ever minted.

Webhook infrastructure — subscriptions, HMAC signing, a delivery worker with backoff, a delivery log and replay — is the next slice of work, and POST /v1/webhook_endpoints is its published contract. See Webhook endpoints. We are not putting a date on it here; the changelog will say when it lands.

A donor whose email is already a Vaki account is asked to log in

If the email entered at checkout already belongs to a registered Vaki user, the current checkout renders a “log in to continue” step instead of letting them pay as a guest. They can still donate — they just have to authenticate first, and some of them will abandon instead.

What this means for you:

Test with fresh email addresses. Your own address is almost certainly already a Vaki account, so your first test will hit the login gate and look like a broken integration. It is not.
Do not demo with a known address. Use a throwaway.
Real-world impact depends on your audience. If your donors are mostly new to Vaki, most of them never see it.

A fix that lets a recognised donor pay without logging in is already in flight outside the API. This page will lose this section when it lands.

There is no test mode yet

There is no vk_test_ key. Every key we issue is a live key, and a call against api.vaki.co creates real objects.

There is a sandbox — the same /v1 code on our staging deployment, with its own keys and its own data. Use it to develop against. Do not build anything durable on it: it is shared infrastructure we deploy to constantly, its data may be reset, and it can be briefly unavailable. It is not somewhere to point CI.

When you do exercise the live API end to end, this is the least invasive way:

POST /v1/vakis with "state": "draft" — a draft cause is not publicly listed.
Mint a checkout link against it with a small amount.
Pay it with a fresh email.
Poll GET /v1/checkout_links/{id} to completed.

Treat anything you create in production as real, because it is. There is no reset button.

Test-mode keys against production uptime — vk_test_ objects living in the same environment as live ones, just marked as test — are the durable answer and are what we intend to ship. The sandbox page says where that stands.

`RateLimit-*` headers are not something to build on yet

The documented limits are the numbers we operate to, and they are attached to your key. Standard RateLimit-Limit / RateLimit-Remaining / RateLimit-Reset response headers are part of the contract we are rolling out, but do not build a scheduler that depends on parsing them today — treat a 429 as the signal and back off exponentially. See Rate limits.

Checkout links point at `vaki.co`, not `checkout.vaki.co`

url is opaque: store the string we return and redirect to it. Never construct it, never parse it, and never depend on its host. That rule is part of the contract, not advice — see the quickstart.

The reason it is on this page is that the host is changing. Today url is a vaki.co/checkout/… URL. A dedicated, country-aware checkout at checkout.vaki.co is planned, and when it ships the value of url changes and nothing else does — no version bump, no new field, no migration on your side — precisely because you redirected to what we returned.

If you have built URL construction anywhere, or you are matching on the host, that is the one thing on this page that will break you later. Undo it now, while it is a five-minute change.

US giving through the Vaki USA Foundation is not wired to this API

Vaki USA Foundation is an IRS-approved 501(c)(3), with its own legal entity and its own Stripe account, and the routing into it is being built — an entity-scoped API key, so a Foundation key mints checkout links that collect into the Foundation and the receiving entity follows from the credential rather than from a per-request flag someone can forget. The mechanism, and what a partner gets from it, are on US giving via the Vaki USA Foundation.

What is not available:

Foundation-scoped keys are not issuable yet. There is nothing you can call today.
Vaki does not issue US donor acknowledgments. There is no contemporaneous written acknowledgment — the receipt a US donor needs to substantiate a gift. Vaki issues a Colombian certificado de donación for ESAL causes; that is a different instrument under a different tax system and it does not substitute.
The harder constraint is governance, not paperwork. For a US donor’s gift to count as a gift to the Foundation, the Foundation has to exercise discretion and control over the funds — if a donor earmarks a gift for one specific beneficiary abroad and the money is merely passed through, that gift can be treated as made to the foreign beneficiary instead, and a gift to a foreign beneficiary is not a gift to a US charity. Money landing in a 501(c)(3) account is necessary and not sufficient. The full explanation is on that page.

So do not tell your donors what their gift will do for their taxes on Vaki’s behalf. That claim is regulated in the United States, the substance of the arrangement decides it, and we are not going to publish a promise here that we cannot yet help you keep.

If you are planning a campaign aimed at US donors, write to soporte@vaki.co before you launch and we will tell you exactly where this stands. The homepage notice and the Foundation page carry the same constraint; all three change together.

Cause owners must already exist on Vaki

POST /v1/vakis requires owner.email to resolve to an existing Vaki account. If it does not, you get a 422 with code: "owner_not_found", and you have to get that person to sign up first.

Creating a claimable pending owner is part of creator onboarding.

Partner-created causes and Vaki’s own emails

Creating a cause triggers Vaki’s existing founder-onboarding notifications to the owner. If you are creating causes on behalf of an organisation that manages them through your product, tell us when your key is issued so the notifications are suppressed for your client. Otherwise your users get an email from Vaki telling them how to do something you already did for them.

No list endpoints, no pagination yet

There is no GET /v1/checkout_links or GET /v1/vakis collection endpoint in this release — only retrieval by id. Persist the chl_… id against your own order at creation time; it is the only handle you get back later.

When list endpoints arrive they will be cursor-paginated (starting_after, limit), never offset-paginated.

Amount and currency coverage

COP and USD only. COP has no minor unit in Vaki’s domain and USD does — see Overview. If you need another currency, ask before you build.

Reporting something that is not on this page

Mail soporte@vaki.co with the request, the response, and the instance value from the problem document if you got one. instance is the request id and it is how we find your call in the logs.