Cobre pelo seu sistema. Que paguem com Toki.

• 1. Seu sistema chama POST /v1/cobros com o valor.
• 2. A Toki responde com uma cobrança e uma url_checkout.
• 3. Você manda seu cliente para lá, ou incorpora na sua própria página.
• 4. Ele paga com o app da Toki e o devolvemos para a sua url_retorno.
• 5. Avisamos por webhook (ou você consulta o status da cobrança).

Cada chamada leva sua credencial no header Authorization. O token tem a forma <key_id>.<segredo>; você o recebe inteiro ao criar a credencial no seu painel, e só nessa vez.

Authorization: Bearer tk_9f2c8ab1de4057.9d31...c0

No painel você também pode restringir de quais IPs a credencial é aceita. Se configurar, uma chamada de outro endereço é recusada mesmo com o segredo certo. É a diferença entre uma chave vazada que funciona de qualquer lugar e uma que não serve fora do seu servidor.

Limite: 120 chamadas por minuto por credencial, e 600 por minuto a partir de um mesmo IP (contadas antes de verificar a chave, para frear quem tenta adivinhar segredos). Passar disso responde 429 com reintentar_en_s.

Cada credencial carrega uma lista de escopos, e cada rota exige o seu. Servem para você entregar uma chave a um integrador externo sem entregar o seu caixa: uma chave feita para montar pedidos não deveria conseguir devolver o dinheiro de uma cobrança.

Duas rotas ficam fora da tabela de propósito: GET /v1/comercio não exige escopo —é «quem sou eu», e não diz nada que a credencial já não represente— e GET /v1/cobros/{id}/qr não pede credencial, porque vai impressa num recibo.

A moeda de tudo o que você cobra é a da sua carteira Toki. Não se escolhe por cobrança: um comércio cobra em uma moeda, a dele.

Os valores vão sempre na menor unidade dessa moeda, o padrão de qualquer gateway. O peso chileno não se subdivide, então 15990 são quinze mil novecentos e noventa pesos. Numa moeda com centavos, 1599 são 15,99.

Diz em que moeda você cobra, o nome do seu comércio e se a credencial é de teste ou de produção. Use para validar sua configuração sem criar uma cobrança de mentira.

{ "comercio": { "nombre": "Minha Loja", "moneda": "CLP", "modo": "prueba" } }

curl -X POST https://api.toki.lat/v1/cobros \
  -H "Authorization: Bearer $TOKI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "monto": 15990,
    "concepto": "Boleta 4471",
    "referencia_externa": "b-4471",
    "url_retorno": "https://mitienda.cl/gracias",
    "url_cancelacion": "https://mitienda.cl/carro",
    "metadata": { "caja": "3" }
  }'

{
  "cobro": {
    "id": "9cd827ca-d10d-4768-8627-265d875f1cd2",
    "monto": 15990,
    "moneda": "CLP",
    "concepto": "Nota 4471",
    "estado": "pending",
    "reembolsado": 0,
    "es_prueba": false,
    "referencia_externa": "b-4471",
    "metadata": { "caixa": "3" },
    "expira_en": "2026-08-25T15:44:57Z",
    "creado_en": "2026-08-25T15:29:57Z",
    "pagado_en": null,
    "url_checkout": "https://toki.lat/pagar/9cd827ca...",
    "qr_svg": "https://toki.lat/api/v1/cobros/9cd827ca.../qr",
    "deeplink": "toki://pay/9cd827ca..."
  }
}

Use `url_checkout`: é a página de pagamento que hospedamos. qr_svg e deeplink ficam para quem quiser montar a própria tela — leia a seção seguinte antes de decidir isso.

Mandar seu cliente para a url_checkout é a forma recomendada de cobrar, e não só por comodidade.

Ela também acompanha o status sozinha, mostra quanto falta para a cobrança vencer, e devolve o cliente ao seu site quando termina. E como a página é nossa, podemos melhorar o fluxo ou acrescentar meios de pagamento sem que você publique nada de novo.

Incorporar no seu site

Se preferir que seu cliente não saia da sua página, carregue-a em um iframe. Avisamos o resultado com postMessage, então você não precisa consultar nada pelo navegador.

<iframe
  src="https://toki.lat/pagar/9cd827ca..."
  style="width:100%;max-width:420px;height:620px;border:0"
  allow="clipboard-write"></iframe>

<script>
  window.addEventListener('message', (e) => {
    if (e.origin !== 'https://toki.lat') return;      // verifique SEMPRE a origem
    if (e.data?.fuente !== 'toki') return;
    if (e.data.evento === 'cobro.paid') {
      // Confirme contra o SEU servidor antes de entregar: uma mensagem do
      // navegador qualquer um pode forjar. Isto serve para reagir na tela.
      mostrarObrigado();
    }
  });
</script>

Devolve o código em SVG, para ficar nítido tanto em uma bobina térmica quanto em uma tela de caixa. É a única rota que não pede credencial: ela vai impressa em notas, onde não há onde colocar um header. O que expõe é o mesmo id que já vai dentro do código, e com esse id só dá para pagar.

Use quando o pagamento acontece na sua frente — um caixa, uma nota impressa — onde seu cliente tem o próprio celular para escanear. Para cobrar pela internet, use a página de pagamento.

<img src="https://api.toki.lat/v1/cobros/{id}/qr" alt="Pague com Toki" />

Devolve a cobrança com seu estado: pending, paid, cancelled ou expired. É o caminho reserva se você não puder receber webhooks — um caixa atrás de uma rede fechada integra só com isto.

curl https://api.toki.lat/v1/cobros/9cd827ca-d10d-4768-8627-265d875f1cd2 \
  -H "Authorization: Bearer $TOKI_API_KEY"

Só enquanto estiver pending. Uma cobrança já paga não se cancela por aqui: devolver dinheiro é um reembolso, com fluxo próprio. Cancelar uma cobrança paga deixaria a contabilidade dizendo uma coisa e a cobrança outra.

Se você configurar uma URL https no painel, avisamos ali quando a cobrança muda de estado: cobro.paid, cobro.cancelled ou cobro.expired. O corpo traz o evento (também no header X-Toki-Evento) e a cobrança completa.

{
  "id": "5b1e0c4a...",
  "evento": "cobro.paid",
  "cobro": { "id": "9cd827ca...", "estado": "paid", "monto": 15990, ... }
}

Cada entrega vai assinada no header X-Toki-Firma, na forma t=<epoch>,v1=<hmac>. O HMAC é SHA-256 sobre ${t}.${corpo} com o segredo de webhook da sua credencial. Verifique sempre: sem isso, qualquer um que conheça sua URL pode dizer que pagou.

import { createHmac, timingSafeEqual } from 'node:crypto';

function verificar(corpo, cabecalho, segredo) {
  const p = Object.fromEntries(cabecalho.split(',').map((x) => x.split('=', 2)));
  const t = Number(p.t);
  // O timestamp vai DENTRO do que é assinado: senão, dá para reenviar um
  // webhook antigo com um t novo e a assinatura continuaria válida.
  if (Math.abs(Date.now() / 1000 - t) > 300) return false;
  const esperado = createHmac('sha256', segredo).update(`${t}.${corpo}`).digest('hex');
  const a = Buffer.from(esperado, 'hex');
  const b = Buffer.from(p.v1 ?? '', 'hex');
  return a.length === b.length && timingSafeEqual(a, b);
}

Tratamos qualquer 2xx como entregue. Se seu servidor falhar, tentamos de novo após 5, 25, 125 e 625 minutos (cinco tentativas no total, umas dez horas), e então desistimos: o último erro fica visível no seu painel. Webhooks podem chegar repetidos, então use o `id` do aviso (também no header `X-Toki-Evento-Id`) para descartar os repetidos: é o mesmo em cada nova tentativa. E faça seu processamento idempotente sobre o id da cobrança.

Devolve o dinheiro de uma cobrança paga. Sem monto, devolve tudo o que resta; com monto, devolve essa parte, e você pode chamar de novo até completar.

Vale planejar: para devolver uma venda você precisa ter o valor completo disponível, não só o que recebeu por ela. Se já sacou e não cobre, o reembolso falha com um erro dizendo quanto falta — preferimos isso a deixar um saldo negativo que alguém terá de perseguir depois.

curl -X POST https://api.toki.lat/v1/cobros/{id}/reembolsar \
  -H "Authorization: Bearer $TOKI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "monto": 5000 }'

A resposta traz reembolsado, o total devolvido até agora. E avisamos por webhook: cobro.partially_refunded enquanto sobrar algo, cobro.refunded quando tudo voltou.

De cada cobrança, a Toki desconta sua comissão e liquida o resto na hora. A API não devolve isso como número fixo porque não é: depende do tipo de cobrança, do seu plano, e de qualquer tarifa acordada com você, que prevalece sobre as demais.

Vale saber: cobrar pela API paga a tarifa de venda presencial, a mais baixa do catálogo — porque você está trazendo seu próprio sistema e a Toki só entra com o meio de pagamento. Vender pelo marketplace da Toki, com catálogo e entrega, custa bem mais. As assinaturas têm tarifas próprias, e cobram a adesão diferente das renovações.

A sua, já com tudo aplicado, está no seu painel: Empresa → Dinheiro, junto ao detalhe de cada liquidação.

Um serviço é algo que as pessoas assinam: um plano, uma associação, uma mensalidade. Você publica pela API e gera um link para alguém assinar. Dali em diante, a cobrança se repete sozinha.

Publicar um serviço

Os campos que não correspondem à unidade escolhida são recusados, não ignorados: mandar dia_de_semana em um plano mensal devolve 400, para você não ficar achando que configurou algo.

curl -X POST https://api.toki.lat/v1/servicios \
  -H "Authorization: Bearer $TOKI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "nombre": "Plano mensal",
    "precio": 19990,
    "cada": 1,
    "unidad": "month",
    "dia_de_cobro": 1,
    "referencia_externa": "plano-mensal"
  }'

{
  "servicio": {
    "id": "b97c3820-b9ea-4352-aba4-a459aaa02015",
    "nombre": "Plano mensal",
    "descripcion": null,
    "precio": 19990,
    "moneda": "CLP",
    "recurrente": true,
    "cada": 1,
    "unidad": "month",
    "dia_de_cobro": 1,
    "dia_de_semana": null,
    "politica_mes_corto": null,
    "activo": true,
    "referencia_externa": "plano-mensal",
    "creado_en": "2026-08-25T15:50:15Z"
  }
}

Listar e editar

Lista todo o catálogo do comércio — inclusive o publicado pelo app, não só o criado pela API.

Gerar o link de assinatura

curl -X POST https://api.toki.lat/v1/suscripciones \
  -H "Authorization: Bearer $TOKI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "servicio_id": "…", "referencia_externa": "socio-118" }'

A resposta tem a mesma forma de uma cobrança —mesma url_checkout, mesmos estados— mais o servicio_id. Você consulta o status com GET /v1/cobros/{id} e recebe o webhook cobro.paid quando a pessoa confirma.

Deixe que as pessoas entrem no seu site com a conta Toki. Elas aprovam pelo telefone com o rosto, e você recebe apenas os dados que autorizaram.

É OAuth 2.0 padrão (authorization code + PKCE), não um fluxo inventado. Use a biblioteca que você já conhece, as propriedades de segurança já foram estudadas, e quem nunca ouviu falar do Toki consegue integrar sem confiar na nossa criptografia.

Registre a sua aplicação

No painel da sua empresa, em Desenvolvedores, você registra o app e recebe um client_id e um client_secret. O segredo aparece uma única vez: guardamos só o hash, então não é que não queiramos mostrá-lo depois — nós não o temos.

Você pode integrar já com as permissões não sensíveis. Para o documento de identidade, telefone, empresas ou autorizar operações revisamos o app antes: nome, logo e responsável declarado. Um app chamado "Toki Pagamentos" com o nosso logo transformaria a tela de consentimento — justamente onde a pessoa confia — numa ferramenta de phishing.

Você manda a pessoa para a tela de consentimento, ela volta com um código, e o seu servidor troca esse código por um token.

https://toki.lat/autorizar
  ?client_id=seu_client_id
  &redirect_uri=https://seusite.com/oauth/callback
  &response_type=code
  &scope=perfil+email
  &state=<valor aleatório seu>
  &code_challenge=<SHA-256 do verifier, base64url>
  &code_challenge_method=S256

A pessoa vê o seu nome, o domínio real do seu site, quem responde por ele, e cada dado que você pede em linguagem humana. Se aprovar, volta ao seu redirect_uri com code e o seu state intacto.

grant_type=authorization_code
code=<o codigo>
redirect_uri=https://seusite.com/oauth/callback
client_id=seu_client_id
client_secret=seu_segredo
code_verifier=<o verifier original>

Devolve access_token (vale uma hora), refresh_token (30 dias), expires_in e o scope realmente concedido — que pode ser menor do que você pediu. Leia: é a única forma de saber quais dados você tem de verdade.

Com Authorization: Bearer <access_token>. Cada campo só é devolvido se a permissão estiver no token. sub vem sempre: é o identificador estável da pessoa.

Para encerrar a sessão do seu lado. Responde 200 sempre, mesmo para um token que nunca existiu: distingui-los transformaria esta rota num jeito de adivinhar tokens válidos.

Peça o mínimo. Cada permissão extra é mais uma pergunta que a pessoa precisa responder antes de aprovar, e mais um motivo para não aprovar.

• — Use PKCE, e só com S256: plain é rejeitado. Sem PKCE a troca só é aceita com o client_secret.
• — O redirect_uri é comparado exatamente com os que você registrou. Sem curingas: aceitá-los deixaria o código chegar a um destino que você não controla.
• — O código dura um minuto e é de uso único. Se for trocado duas vezes, assumimos que vazou e revogamos tudo o que foi emitido para essa pessoa no seu app.
• — Os refresh_token rotacionam: cada troca devolve um novo e invalida o anterior. Reutilizar um antigo é tratado como roubo e encerra a sessão.
• — O client_secret nunca vai para o navegador. Se o seu app não puder guardá-lo, a troca do código funciona mesmo assim com PKCE, mas renovar exige o segredo: grant_type=refresh_token sem ele responde invalid_client. Pode ir no corpo ou em Authorization: Basic.
• — A pessoa pode retirar o acesso quando quiser pela conta dela, e os tokens vivos são cortados junto. A sua integração tem que sobreviver a isso sem quebrar.

Uma mini app é um site seu que abre em tela cheia dentro do Toki, com acesso a uma ponte que deixa ela pedir coisas ao app: quem é a pessoa, a localização dela, abrir um pagamento. Você não instala nenhum SDK —a pessoa sim instala seu app pela loja da Toki, veja *Sua ficha na loja*—: o Toki injeta window.toki na sua página antes de ela carregar.

Seu app roda na própria origem e só conversa com o Toki por mensagens. Nada é injetado nele: nem token, nem identificador da pessoa, nem os dados dela. Tudo o que quiser saber precisa pedir, e cada pedido passa por dois filtros — o que você declarou no manifesto e o que a pessoa autorizou.

Cada app se registra com um manifesto. O que importa: a clave (minúsculas e hifens, é o seu identificador estável), a url de início — https obrigatório — e as capacidades que você vai pedir.

As capacidades do manifesto são a lista completa do que o seu app pode chegar a fazer, e a pessoa a vê antes de entrar. Uma capacidade que você não declarou não pode ser pedida: a ponte responde sin_capacidad sem perguntar a ninguém. Declare o mínimo — cada permissão a mais é um motivo para não abrir o seu app.

Um app passa por borrador → en_revision → publicada. Só publicada aparece fora da sua equipe, e pode voltar para rechazada ou suspendida.

O app é registrado por você, no seu painel em Minha empresa → Micro apps. Ali você escreve o manifesto, salva como rascunho quantas vezes quiser e envia para revisão quando estiver pronto. Nós revisamos; não redigimos.

Cada capacidade marcada leva uma frase sua dizendo para que você precisa dela (200 caracteres). Não substitui a nossa explicação da permissão: completa. «Localização» não dá para responder com informação; «para calcular o frete até seu endereço» dá. Sem essa frase o app não entra em revisão — uma capacidade sem motivo só pode ser rejeitada.

Cada método é uma função que recebe um objeto e devolve uma promessa. O objeto está congelado: não dá para substituir nem estender.

// window.toki já existe ao carregar; não há o que esperar.
const { id } = await toki.identidad();

try {
await toki.pagar({ cobroId });
} catch (e) {
if (e.codigo === 'cancelado') return;   // a pessoa disse que não
throw e;
}

Os erros chegam como Error com um codigo estável: sin_capacidad (você não declarou), sin_permiso (a pessoa disse que não), cancelado, params, metodo_desconocido, mal_formado, interno.

toki.identidad() não devolve o identificador real da pessoa no Toki, e sim um derivado do par (pessoa, app). É estável para você e diferente em cada app: duas mini apps não conseguem cruzar suas bases e descobrir que falam com a mesma pessoa.

Nome e foto são outra coisa: vão por toki.perfil() e pedem confirmação toda vez, porque de dentro do app não dá para saber se o pedido nasceu de um botão que a pessoa apertou ou de um laço. Um "não" vale para a sessão inteira; insistir não abre outro diálogo.

O que o seu app nunca vai poder ler: conversas, contatos, pedidos, saldo, meios de pagamento, a sessão da pessoa nem o endereço dela. Também não pode rodar em segundo plano nem mandar notificações.

Uma cobrança serve para cobrar um valor. Um pedido serve para vender algo que precisa ser entregue: seu app declara as linhas e a Toki coloca o checkout — a lista de endereços da pessoa, a cotação do courier, o total e a confirmação. Precisa da capacidade comprar.

Você manda linhas, nunca um total. O total é calculado por nós: subtotal menos desconto mais entrega. Se o total viajasse no corpo, quem compra poderia confirmar o pedido com frete zero.

O preço do catálogo nem sempre está no item. Se o item declara o valor dele, é esse que manda e nada mais é consultado. Se ficar vazio e o item pender de um serviço do seu catálogo de Mercado, o preço do catálogo é o desse serviço — e só enquanto o serviço estiver ativo: um arquivado não empresta o dele. Se não houver nenhum dos dois, o item não tem preço e a linha responde precio_no_coincide seja qual for o número enviado; não é «preço a combinar», é um item que não pode ser vendido.

curl https://api.toki.lat/v1/pedidos \
-H "Authorization: Bearer $TOKI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "app": "foto-trama",
  "items": [{ "nombre": "10 cópias 10x15", "cantidad": 1, "precio_unitario": 6990, "clave": "copias-10x15" }],
  "entrega": { "tipo": "despacho", "origen_comuna": "PROV", "bulto": { "peso_g": 400 } },
  "referencia_externa": "pedido-1042"
}'

As três formas de entregar

Para retiro você precisa de pelo menos um depósito com retirada habilitada em Minha empresa → Depósitos. É de lá que sai o custo da retirada: não vai no corpo, igual ao frete.

Se você aceita mais de uma, não pergunte você. Envie entrega.tipos: ["despacho", "retiro"] e a folha da Toki pergunta à pessoa como ela quer receber, mostrando o frete estimado e o custo da retirada de cada opção. entrega.tipo passa a ser a proposta primeiro. Perguntar na sua página é fazer checkout à mão: você precisaria conhecer depósitos e custos, e criar um pedido diferente por resposta. digital não se combina com as outras —seria deixar quem paga escolher o trilho de cobrança—, e se você oferecer despacho, origen_comuna continua obrigatório.

E depois, no telefone

Com o id que devolvemos, sua página abre o checkout da Toki: await toki.pedido({ pedidoId: id }). Ali a pessoa escolhe endereço ou depósito, vê o total já cotado e paga. O valor não viaja nessa chamada — o pedido já tem preço. Se o pedido venceu, não está mais pendente ou é de outro app, responde params com um detalle que diz isso (pedido_vencido, pedido_pagado, pedido_de_otra_app…).

Esta é a sua fonte de verdade, não o que a ponte devolve: aquilo é o seu próprio código contando como foi, num aparelho que você não controla. Aqui vêm o estado, o despacho cotado, o total e —se for retirada— entrega.retiro com nome, endereço e comuna do lugar onde a pessoa vai, para você poder avisar.

O que você nunca vai receber é o endereço de quem compra. Ela escolhe na nossa folha e ele serve para enviar; se a Toki retira no seu depósito e envia, você não precisa dele. É esse o ponto.

O aviso chega como pedido.paid com o id do pedido —não o da cobrança, que você nunca viu. Também existem pedido.cancelled, pedido.expired, pedido.refunded e pedido.partially_refunded. São assinados como os de cobranças.

• — Um pedido vive 30 minutos por padrão (expira_minutos). Depois disso fica expirado e é preciso criar outro.
• — referencia_externa é a sua idempotência: a mesma referência com a mesma credencial devolve o pedido já criado, não um novo. Se aquele pedido já venceu, mande uma referência nova.
• — A clave de cada linha (obrigatória, ver acima) é também o que baixa o estoque e liga o pedido ao item declarado. Sem estoque suficiente, responde 409 estado_invalido.
• — Um pedido é de um só vendedor. Um carrinho com dois micro apps é outro problema e ainda não existe.

Resgatar um pedido pago

Se o que você vende custa dinheiro para gerar —uma imagem de um modelo, um relatório, um minuto de vídeo— você precisa saber que aquele pedido não foi resgatado antes. Manter essa conta do seu lado é mais difícil do que parece: em memória não serve (duas instâncias não se veem) e no seu banco é um contador que precisa ficar consistente com o que outro cobrou. Como quem cobrou foi a Toki, a conta é da Toki.

Responde ok só se o pedido estiver pago e ainda tiver um uso, e o desconta na mesma chamada. A referencia do corpo é sua e torna o resgate idempotente: se a resposta se perder depois de contarmos o uso, repetir com a mesma referência devolve o mesmo —com repetido: true— em vez de gastar outro. Sem isso, um timeout cobra duas vezes de quem comprou uma.

curl https://api.toki.lat/v1/pedidos/$PEDIDO/consumir \
  -H "Authorization: Bearer $TOKI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "referencia": "geracao-1" }'

• — 404 — o pedido não existe, ou não é seu.
• — 409 — ainda não está pago (a mensagem diz em que estado), ou já usou todos os resgates.
• — Um pedido concede um resgate por padrão.

Usos por comprador

O de cima conta os resgates de UM pedido. Se você vende pacotes —1 foto por $790, 10 por $4.990— o que a pessoa precisa é outra coisa: usos DELA. Compra dois pacotes de 10, tem 20, e gasta quando quiser sem lembrar com qual pedido pagou qual. Isso não vai pela API: quem declara é o seu catálogo, com usos_por_compra no item, e a Toki credita sozinha quando o pedido fica pago. Um item sem usos_por_compra —um quadro impresso— não deixa usos.

curl https://api.toki.lat/v1/apps/usos/consumir \
  -H "Authorization: Bearer $TOKI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "x-toki-identidad: $TOKI_IDENTIDAD" \
  -d '{ "comprador": "'$COMPRADOR'", "item": "fotos-10", "referencia": "foto-9f3ac1-v1", "entregable": { "url": "https://…" } }'

comprador é o pseudônimo que você já conhece: o mesmo que chega com a capacidade identidad e em pedido.comprador. Você nunca vai receber quem é a pessoa. O GET serve para pintar «restam 7» antes de ela apertar o botão, mas NÃO é um controle: entre ler e entregar ela pode gastar de outro celular. Quem decide é o POST, que desconta e responde na mesma chamada. Ele desconta unidades (de 1 a 1000, padrão 1), e com uma credencial de teste não gasta nada: responde com simulado: true.

• — 404 — essa pessoa não tem usos desse item, ou o item não é da sua credencial.
• — 409 `sin_usos` — não restam suficientes. A resposta traz disponibles.
• — 400 `referencia_debil` — sua referência é uma constante óbvia, tem menos de 8 caracteres ou começa com pedido: ou reembolso:, que a Toki usa.
• — Reembolsar o pedido devolve os usos dele. Se a pessoa já gastou algum, o reembolso não sai sozinho: vocês dois resolvem.

Identidade assinada

O comprador é a sua própria página que te passa, então sozinho ele não prova nada: quem souber o pseudônimo de outra pessoa queimaria os usos dela. Por isso toki.identidad() te devolve, junto com o pseudônimo, um token assinado pela Toki. Você reenvia igualzinho no cabeçalho x-toki-identidad e nós verificamos que aquele pseudônimo é de quem diz ser. O pseudônimo continua sendo a chave do saldo: o token prova de quem é, não o substitui.

const { id, token, expira_en } = await toki.identidad();
// id     → o pseudônimo (64 hex). É a chave do saldo dela.
// token  → credencial de 15 min. Mande ao SEU backend, nunca numa URL.
await fetch('/meu-backend/trabalho', {
method: 'POST',
headers: { 'content-type': 'application/json' },
body: JSON.stringify({ persona: id, identidad: token }),
});

• — Está amarrado ao seu app. É assinado com uma chave que só existe para o seu app: um token de outro mini app não valida aqui, nem o seu lá.
• — Não leva o uid da pessoa nem nada que permita cruzá-la com outro app. Só o pseudônimo que você já conhecia.
• — Vive 15 minutos. Chamar toki.identidad() de novo te dá outro sem perguntar nada à pessoa. Peça antes de cada trabalho longo.
• — 401 `identidad_vencida` — venceu no meio. Renove e repita com a mesma `referencia`: é idempotente, então não gasta um uso a mais nem te faz gerar de novo.
• — 401 `identidad_requerida` — seu app já fechou o modo antigo e você não mandou token. 401 `identidad_no_coincide` — esse token é de outra pessoa, não a do comprador. 401 `identidad_invalida` — o resto.
• — Enquanto o seu app não exigir, é opcional —mas se mandar, é verificado do mesmo jeito—. A resposta traz consumo.identidad_firmada para você ver em que modo está. Se token vier null, essa pessoa está numa versão da Toki anterior a isto.

As pessoas descobrem seu app numa ficha e o instalam antes de abrir. Você monta a ficha em Minha empresa → Micro apps, com estes campos além do manifesto (nenhum é obrigatório para publicar, mas uma ficha sem capa nem capturas convence pouco):

As imagens ficam na Toki, como o ícone: você as envia pelo painel (ou cola uma URL e a Toki a copia uma vez), elas são validadas pelos bytes —PNG, JPEG ou WEBP, nada de SVG, até 4 MB— e recortadas ao centro numa medida fixa. Uma URL do seu servidor nunca é guardada: se o seu servidor cair, sua ficha continua inteira.

A ficha também mostra, sem você escrever mais nada: sua empresa e se está verificada, quais permissões seu app pede e quando, quais dados usa —derivado das suas capacidades e da frase que você escreveu para cada uma— e o que você vende com o preço.

• — Essenciais, ao instalar. As capacidades que você marca como essenciais (só identidad e ubicacion) são aceitas com um toque ao instalar, listadas com a sua frase. Sem elas seu app não abre.
• — O resto, no contexto. O restante é pedido na primeira vez que seu app usa, e pagamentos, compras, compartilhar e abrir outro app são confirmados cada vez. Continua valendo não pedir permissões ao abrir.
• — Se você adicionar uma essencial numa versão nova, quem já instalou é perguntado antes de abrir: nunca é concedida em silêncio. Adicione só se seu app realmente não funciona sem ela.

A mesma ficha em JSON, sem credencial: serve para mostrar no seu site como as pessoas veem você na Toki. Traz nombre, portada, capturas, desarrollador (com verificado), permisos (com esencial, sensible, momento e a sua declaracion), datos, compras (com precio_clp), version_publica, novedades e soporte. Só apps publicados: o resto é 404. Fica em cache por 5 minutos.

• — Não peça permissões ao abrir. A Toki mostra a folha no momento em que seu app usa a capacidade, então chamar toki.identidad() no arranque pede que a pessoa decida sobre algo que ainda não fez — e a resposta razoável a isso é «não». Peça na ação que precisa. Na revisão isso é olhado.
• — Só `https`, e só a sua origem. Um link para outro site abre no navegador do sistema, fora do Toki; um iframe de outro domínio não carrega. Se carregasse, aquele quadro teria as permissões do seu app.
• — O valor nunca viaja pela ponte. A cobrança é criada pelo seu backend contra a API com a sua credencial, e toki.pagar só abre uma que já existe com o preço dela. Um preço que chega da página é um preço que se edita com o console aberto.
• — Você só pode abrir cobranças suas. toki.pagar verifica que a cobrança pertence ao perfil comercial dono do app. A cobrança de outro comércio responde params.
• — Os cookies de terceiros estão cortados dentro do contêiner. A sua página mantém os dela; o que deixa de funcionar é o pixel de um terceiro seguindo a pessoa entre mini apps.
• — O Toki não passa para a sua página os cookies nem a sessão dele, e a sua página não acessa file:// nem pode abrir janelas sem um gesto.

Se sua loja é WooCommerce, você não precisa escrever código: existe um plugin que faz tudo isso por você.

• 1. Instale em Plugins → Adicionar novo → Enviar plugin.
• 2. Vá em WooCommerce → Configurações → Pagamentos → Toki.
• 3. Cole sua credencial de teste e deixe o modo de teste ligado.
• 4. Copie a "URL para avisos" que aparece ali e cole na sua credencial da Toki, junto com o segredo de assinatura.
• 5. Faça um pedido completo. POST /v1/cobros/{id}/simular-pago dá como pago sem movimentar dinheiro.
• 6. Quando funcionar, cole a credencial de produção e desligue o modo de teste.

Faz cobranças, reembolsos totais e parciais pelo próprio pedido, e verifica a assinatura de cada aviso. O pedido é marcado como pago pelo webhook, nunca porque o cliente voltou à loja — voltar não prova que pagou.

Crie uma credencial em modo teste no seu painel e desenvolva com ela sem movimentar um centavo. A chave é diferente —começa com tk_test_— para não se confundir com a de produção, nem num log nem num arquivo de configuração.

Dar uma cobrança de teste como paga

Marca a cobrança como paga e dispara seu webhook, sem escrever um único lançamento contábil. É assim que você testa sua tela de obrigado e seu tratamento do evento antes de cobrar de alguém.

curl -X POST https://api.toki.lat/v1/cobros/{id}/simular-pago \
  -H "Authorization: Bearer $TOKI_TEST_KEY"

Cobranças de teste vêm com es_prueba: true na resposta. Se sua integração as vê em produção, você subiu a credencial errada.

Todos os erros têm a mesma forma. O code é estável e pensado para você comparar no seu código; a mensaje é para você ler.

{ "error": { "code": "credencial_invalida", "mensaje": "..." } }

• — Guarde o segredo onde guarda os outros segredos, nunca no código nem no front.
• — Configure a lista de IPs. É o cadeado que continua servindo se o segredo vazar.
• — Mande sempre referencia_externa: é o que impede cobrar duas vezes quando a rede falha no meio.
• — Verifique a assinatura de cada webhook, e não decida nada com um postMessage.
• — Tenha um plano para quando o webhook não chegar: consulte o status antes de entregar.