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.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.

No test mode or sandbox

There is no vk_test_ key and no sandbox environment yet. Keys are live keys against production data.

Until test mode exists, the safest way to exercise the API end to end:

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

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

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

The url you get back today is a vaki.co/checkout/… URL. A dedicated, country-aware checkout at checkout.vaki.co is planned. When it ships, the value of url changes and nothing else does — provided you treat url as opaque and redirect to it rather than constructing it from the vaki key and the amount.

If you have built URL construction anywhere, that is the one thing on this page that will break you later. Undo it.

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.