Quickstart

One HTTP call gets you a hosted checkout URL that collects a donation — PSE or a card in Colombia, PayPal in Mexico, a card from anywhere else. This page is that call, plus how to know it worked.

/v1 is rolling out

The contracts on this page are final, but a route whose implementation has not landed yet answers 501 with not_implemented. If a call on this page returns 501, check the changelog before debugging your own code.

Production or sandbox

Every base URL on this page follows the Examples switcher in the header. Leave it on Production to work against live money, or set it to Sandbox to run the same commands — and the same copied clipboard text — against our staging environment.

You need two things: an API key with the checkout_links:write permission, and the key of the vaki you are collecting for — the slug in its public URL. If https://vaki.co/clinicalaliga is the cause, the key is clinicalaliga. If you do not have a cause yet, create one first.

1. Put your key in the environment

Never commit it, never put it in a query string, never ship it to a browser.

export VAKI_API_KEY="…the key Vaki issued you…"

2. Mint a checkout link

curl https://api.vaki.cohttps://public-api-staging.vaki.co/v1/checkout_links \
  -H "Authorization: Bearer $VAKI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: quickstart-$(date +%s)" \
  -d '{
    "vaki": "clinicalaliga",
    "amount": 50000,
    "currency": "COP",
    "email": "donante@example.com",
    "external_reference": "DON_59LPC74YV",
    "callback_url": "https://tu-sitio.example.com/api/vaki/callback"
  }'

201 Created:

{
  "id": "chl_01J9Z4M2K7QF3B",
  "object": "checkout_link",
  "url": "https://vaki.co/checkout/clinicalaliga?value=50000&currency=COP&ref=chl_01J9Z4M2K7QF3B",
  "status": "open",
  "amount": 50000,
  "currency": "COP",
  "fee_percent": 5,
  "external_reference": "DON_59LPC74YV",
  "expires_at": "2026-08-18T14:00:00Z",
  "created_at": "2026-08-17T14:00:00Z"
}

Only vaki, amount and currency are required. Everything else is convenience: email prefills the donor’s address, external_reference is your own id coming back to you, callback_url is stored for when webhook delivery ships, and success_url / cancel_url control where the donor lands afterwards.

amount is an integer with no minor unit in COP

50000 means COP 50.000, not COP 500. Send 50000.00 and you get a 400. For USD, the minor unit does apply: 5000 is USD 50.00.

currency must be the currency the cause itself collects in — anything else is a 422 with currency_not_supported, because we will not pick an exchange rate for you. Read it from GET /v1/vakis/{key} (finance_data.currency) rather than assuming COP; see a cause collects in exactly one currency.

3. Send the donor to url

open "https://vaki.co/checkout/clinicalaliga?value=50000&currency=COP&ref=chl_01J9Z4M2K7QF3B"

That is the whole integration. Redirect, do not embed.

url is opaque — store it and redirect to it

Treat the value of url as a string with no structure: never construct it, never parse it, and never depend on its host or its query parameters. Anything you need from a checkout link, read from the object we returned — the chl_… id, amount, status — not from its URL.

The host you see above is vaki.co/checkout/… today, and it is changing to a dedicated checkout.vaki.co. That migration is designed to be completely invisible to you — no version bump, no new field, nothing to deploy — because you stored the URL we handed you instead of rebuilding it. Partners who pattern match on the host are the only ones it can break. See Known limitations.

Use a fresh email the first time

If the email you enter already belongs to a registered Vaki account, checkout currently asks that person to log in instead of paying as a guest. For your own first test, use an address that has never donated on Vaki. This is a real limitation and it is being fixed — see Known limitations.

4. Confirm the donation

Poll the link. status moves from open to completed once the payment is approved.

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

{
  "id": "chl_01J9Z4M2K7QF3B",
  "object": "checkout_link",
  "status": "completed",
  "amount": 50000,
  "currency": "COP",
  "fee_percent": 5,
  "external_reference": "DON_59LPC74YV",
  "expires_at": "2026-08-18T14:00:00Z",
  "created_at": "2026-08-17T14:00:00Z"
}

status is one of:

Status	Meaning
open	Minted, not paid yet. Still usable.
completed	The donation was approved. Terminal.
expired	Passed expires_at without being paid. Mint a new one.
cancelled	Voided before payment. Terminal.

A sensible polling shape: poll when the donor returns to your success_url, and then once a minute for a few minutes, backing off. Do not poll a link that has reached a terminal status, and do not poll every link you have ever minted on a cron — that is what the rate limit is there to stop.

Why polling, for now

callback_url is accepted, validated and stored today, but Vaki does not deliver to it yet. Write your integration with the field set — nothing will change when delivery ships — and poll in the meantime.

The same thing in Node

const res = await fetch('https://api.vaki.cohttps://public-api-staging.vaki.co/v1/checkout_links', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.VAKI_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': `donation-${orderId}`
  },
  body: JSON.stringify({
    vaki: 'clinicalaliga',
    amount: 50000,
    currency: 'COP',
    email: 'donante@example.com',
    external_reference: orderId
  })
});

if (!res.ok) {
  // Problem documents are application/problem+json — branch on `code`.
  const problem = await res.json();
  throw new Error(`${problem.code}: ${problem.detail ?? problem.title}`);
}

const link = await res.json();
// Persist link.id against your own order before redirecting.
return link.url;

The same thing in Python

import os
import requests

res = requests.post(
    "https://api.vaki.cohttps://public-api-staging.vaki.co/v1/checkout_links",
    headers={
        "Authorization": f"Bearer {os.environ['VAKI_API_KEY']}",
        "Content-Type": "application/json",
        "Idempotency-Key": f"donation-{order_id}",
    },
    json={
        "vaki": "clinicalaliga",
        "amount": 50000,
        "currency": "COP",
        "email": "donante@example.com",
        "external_reference": order_id,
    },
    timeout=15,
)

if res.status_code != 201:
    problem = res.json()
    raise RuntimeError(f"{problem['code']}: {problem.get('detail', problem['title'])}")

link = res.json()
checkout_url = link["url"]

Optional: create the cause first

If the cause does not exist yet, create it. The owner must already be a registered Vaki account — pass their email and we resolve it.

curl https://api.vaki.cohttps://public-api-staging.vaki.co/v1/vakis \
  -H "Authorization: Bearer $VAKI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: vaki-N_2QFBQFJTY" \
  -d '{
    "title": "Ayuda para el Hospital San Jorge",
    "description": "Dotación de la sala de urgencias del Hospital San Jorge.",
    "goal": { "amount": 50000000, "currency": "COP" },
    "category": "no-profit",
    "country": "CO",
    "owner": { "name": "Nombre del responsable", "email": "responsable@example.org" },
    "external_reference": "N_2QFBQFJTY",
    "state": "draft"
  }'

201 Created returns the vaki, including the key you pass to POST /v1/checkout_links:

{
  "key": "ayuda-hospital-san-jorge",
  "slug": "ayuda-hospital-san-jorge",
  "url": "https://vaki.co/ayuda-hospital-san-jorge",
  "title": "Ayuda para el Hospital San Jorge",
  "state": "draft",
  "goal": { "amount": 50000000, "currency": "COP" },
  "finance_data": { "currency": "COP", "fee_percent": 5 },
  "owners": [{ "name": "Nombre del responsable", "email": "responsable@example.org" }],
  "created_at": "2026-08-17T13:58:11Z"
}

A cause created in draft is not publicly visible. Publish it from the Vaki dashboard, or pass "state": "published" if you want it live immediately.

state is English here, Spanish inside

This API speaks stable English snake_case — draft, created, published, in_verification, verified. Vaki stores state in Spanish internally and maps at the boundary. Never depend on an internal value leaking through; if you ever see one, that is a bug worth reporting.

If the owner email does not resolve to an existing Vaki account you get a 422 with code: "owner_not_found". Creating an account on the owner’s behalf is coming soon.

Next

• Authentication — key handling, rotation, IP allowlisting
• Accept a donation from your own site — the whole integration as a change to one route
• Errors — the codes you will hit first
• Fees — what 5% covers