Documentação da API · Kontino Connect

Kontino Connect API

Recebimentos locais no México, na Argentina e no Brasil, liquidados em dólar, pagamentos para cinco trilhos e contas para cada cliente seu. REST, JSON e códigos HTTP comuns.

Valores em centavos da moeda, sempre inteiros. MX$ 125.000,00 = 12500000.
Moedas ISO 4217, países ISO 3166 (2 letras) e datas ISO 8601 em UTC.
Todo objeto tem id com prefixo (col_, po_, acct_, evt_) e mode.

URL base

https://api.kontino.co/v1

Início rápido

1Peça acesso. A triagem responde na hora e o sandbox abre junto.
2Crie uma chave de teste. Em Desenvolvedores › Chaves. Guarde no servidor.
3Cadastre um webhook. Receba collection.paid assinado no seu servidor.
4Crie e pague uma cobrança. POST /collections e depois POST /test/collections/:id/pay.
5Vá para produção. Depois do go-live, troque sk_test_ por sk_live_. O código é o mesmo.

Primeira cobrança · cURL

curl -X POST https://api.kontino.co/v1/collections \
  -H "Authorization: Bearer sk_test_…" \
  -H "Idempotency-Key: pedido-48213" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "spei",
    "amount": 12500000,
    "payer": {
      "name": "Comercial del Norte"
    },
    "metadata": {
      "order_id": "48213"
    }
  }'

Autenticação

Envie a chave em Authorization: Bearer. A chave aparece inteira uma vez só, ao ser criada, e o Kontino guarda apenas o hash. Revogue no painel e ela para na hora.

Permissão	Pode
Tudo	Todas as rotas (padrão)
collections	Cobranças, contas conectadas e leitura
payouts	Pagamentos e leitura
read	Só leitura

Nunca use a chave no navegador ou no aplicativo do celular: chame a API do seu servidor.

Cabeçalho

Authorization: Bearer sk_test_4eC39HqLyjWDarjtT1zdp7dc

Teste e produção

Os dois modos usam a mesma URL e o mesmo código; a chave decide. O sandbox segue as regras da produção, para nada mudar no go-live.

	Teste (sk_test_)	Produção (sk_live_)
Dinheiro	Simulado	Real, na conta Kontino da sua empresa
Disponível	Desde a triagem	Depois do go-live
Câmbio	Fixo (reprodutível)	Cotação do momento
Pagar a cobrança	POST /test/collections/:id/pay	O comprador paga no banco
Verificar conta conectada	Tela simulada ou POST /test/accounts/:id/verify	Documentos de verdade
Faixa, prazo e CUIT	Iguais	Iguais

Erros

Todo erro tem o mesmo formato. Use code no seu código (é estável) e mostre message para a pessoa. param aponta o campo.

code	HTTP	Quando
invalid_api_key	401	Chave ausente, com formato errado ou revogada.
account_not_enabled	403	Sua conta Connect não está liberada para este modo.
insufficient_scope	403	A chave não tem a permissão da rota.
parameter_missing	400	Falta um parâmetro obrigatório (veja param).
parameter_invalid	400	Valor com formato inválido (CLABE, CUIT, IBAN…).
currency_mismatch	400	A moeda não é a do método ou do trilho.
amount_out_of_range	400	Cobrança fora da faixa de US$ 10 a US$ 10.000.
limit_exceeded	400	Acima do seu limite por operação.
balance_insufficient	400	Saldo menor que valor + taxa.
account_not_active	400	A conta conectada ainda não foi aprovada.
account_not_ready	403	Produção: a conta Kontino da sua empresa ainda não foi aprovada.
email_in_use	409	Produção: o e-mail já tem conta no Kontino.
resource_already_exists	409	external_id já usado em outra conta.
idempotency_key_reused	409	Mesma Idempotency-Key com outro corpo.
resource_missing	404	O id não existe neste modo.
test_mode_only	400	Rota de sandbox chamada com chave de produção.
rate_limited	429	Mais de 100 requisições em 10 s com a mesma chave. Respeite Retry-After.
provider_*	400	Produção: o banco parceiro recusou (a message explica).

400

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_invalid",
    "message": "CUIT/CUIL inválido em payer.tax_id.",
    "param": "payer.tax_id"
  }
}

Idempotência

Mande Idempotency-Key (até 200 caracteres) em toda criação. Repetir com a mesma chave e o mesmo corpo devolve o mesmo objeto, sem criar outro; com outro corpo, 409 idempotency_key_reused. Use o id do seu pedido ou um UUID novo por operação.

Cabeçalho

Idempotency-Key: pedido-48213

Paginação

Listas devolvem { object: "list", data, has_more }, do mais novo para o mais antigo. Use limit (1 a 100) e starting_after com o id do último item enquanto has_more for true.

GET

GET /v1/collections?limit=100&starting_after=col_j3QxtZIS4bqB8f7E

Limites

Limite	Valor
Por cobrança	Equivalente a US$ 10 até US$ 10.000 (regra dos bancos parceiros)
Prazo da cobrança	30 minutos para o depósito
Por operação, dia e mês	Os da sua proposta; sobem em 30, 60 e 90 dias
Requisições	100 a cada 10 segundos por chave (429 com Retry-After)
Webhooks	Até 5 endpoints por modo; resposta em 10 s
Chaves	Até 10 ativas por modo
metadata	20 pares; chave até 40 e valor até 500 caracteres

Versões e mudanças

A versão está na URL (/v1). Dentro dela só entram mudanças compatíveis: campos e eventos novos, valores novos em enums. Trate campos desconhecidos como opcionais. Mudanças que quebram saem numa /v2, com aviso de 6 meses.

Data	Mudança
10/11/2026	Contas conectadas, ACH e SEPA em produção, account em cobranças, pagamentos e saldo
09/11/2026	Produção (sk_live_), eventos e webhooks assinados

Receber eventos

Cadastre o endereço https em Desenvolvedores › Webhooks. Enviamos POST JSON e esperamos 2xx em até 10 s. Responda rápido e processe depois.

Falhou? Tentamos de novo em 1 min, 5 min, 30 min, 2 h, 6 h e 12 h. Dá para reenviar pelo painel.
O mesmo evento pode chegar mais de uma vez: guarde o id (também em Kontino-Event-Id) e ignore repetidos.
A ordem não é garantida. Use o status do objeto, não a ordem de chegada.

Entrega

POST /seu/endpoint
Content-Type: application/json
User-Agent: Kontino-Webhooks/1.0
Kontino-Event-Id: evt_Qm3Lz8VnR2pX0tYa
Kontino-Signature: t=1794268442,v1=5257a869e7ec…

{
  "id": "evt_Qm3Lz8VnR2pX0tYa",
  "object": "event",
  "type": "collection.paid",
  "mode": "live",
  "created": "2026-11-10T14:03:47.000Z",
  "data": { "object": { "id": "col_…", "status": "paid", … } }
}

Conferir a assinatura

v1 é o HMAC-SHA256 em hexadecimal de <t>.<corpo bruto>, com o segredo do endpoint (whsec_…). Compare em tempo constante e recuse t com mais de 5 minutos. Use o corpo bruto, antes de qualquer parse.

Node.js

import { createHmac, timingSafeEqual } from "node:crypto"

export function webhookValido(corpoBruto, cabecalho, segredo) {
  const partes = Object.fromEntries(cabecalho.split(",").map((p) => p.split("=")))
  const esperado = createHmac("sha256", segredo)
    .update(`${partes.t}.${corpoBruto}`)
    .digest("hex")
  const recente = Math.abs(Date.now() / 1000 - Number(partes.t)) < 300
  return recente && esperado.length === partes.v1.length
    && timingSafeEqual(Buffer.from(esperado), Buffer.from(partes.v1))
}

Catálogo de eventos

Tipo	Quando
collection.created	Cobrança criada.
collection.paid	O depósito chegou; settlement traz o líquido em dólar.
collection.expired	30 minutos sem depósito.
payout.created	Pagamento criado e valor reservado.
payout.paid	O dinheiro chegou ao destino.
payout.failed	O destino recusou; o valor voltou ao saldo.
balance.updated	O saldo disponível mudou (com account quando é de uma conta conectada).
account.created	Conta conectada criada.
account.updated	A verificação terminou: status active ou rejected.

Cobranças

Uma cobrança gera a instrução para o comprador pagar no trilho local (CLABE no SPEI, CVU nas Transferencias, Pix copia e cola). Quando o depósito chega, o valor é convertido para dólar, a taxa é descontada e o líquido entra no saldo do parceiro ou da conta conectada.

O objeto

idtexto: Prefixo col_.
statusenum: pending → paid. Ou expired (30 min sem depósito) e canceled (o banco recusou).
methodenum: spei · transfers_ar · pix
amountinteiro: Centavos da moeda do método.
currencytexto: MXN, ARS ou BRL.
accounttexto | null: Conta conectada que recebe. null = o seu saldo.
instructionsobjeto: clabe, cvu ou copy_paste, e a reference para o comprador conferir.
settlementobjeto | null: Quando paga: gross, fee e net em centavos de dólar, e fx_rate.
expires_atdata: Prazo para o depósito chegar.
metadataobjeto: Seus pares chave/valor (até 20).

Objeto

{
  "id": "col_j3QxtZIS4bqB8f7E",
  "object": "collection",
  "mode": "test",
  "method": "spei",
  "status": "pending",
  "account": null,
  "amount": 12500000,
  "currency": "MXN",
  "reference": "KT7Q2M9XA",
  "instructions": {
    "type": "clabe",
    "clabe": "646180153982493432",
    "reference": "KT7Q2M9XA"
  },
  "payer": {
    "name": "Comercial del Norte"
  },
  "metadata": {
    "order_id": "48213"
  },
  "settlement": null,
  "expires_at": "2026-11-10T14:32:00.000Z",
  "paid_at": null,
  "created": "2026-11-10T14:02:00.000Z"
}

POST/v1/collections

Criar cobrança

Cria a cobrança e devolve as instruções de pagamento. Mande Idempotency-Key.

Corpo

methodenumobrigatório: spei · transfers_ar · pix
amountinteiroobrigatório: Centavos da moeda do método. Equivalente a US$ 10 até US$ 10.000.
currencytexto: Opcional; se vier, precisa bater com o método.
accounttexto: acct_… de uma conta conectada ativa. Sem ele, cai no seu saldo.
payer.nametexto: Nome de quem paga.
payer.emailtexto: E-mail de quem paga.
payer.tax_idtexto: Obrigatório em transfers_ar: CUIT/CUIL de quem paga (só ele consegue pagar a CVU).
referencetexto: Sua referência (4 a 30 letras, números ou hífen). Gerada se não vier.
metadataobjeto: Até 20 pares chave/valor.

cURL

curl -X POST https://api.kontino.co/v1/collections \
  -H "Authorization: Bearer sk_test_…" \
  -H "Idempotency-Key: pedido-48213" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "spei",
    "amount": 12500000,
    "payer": {
      "name": "Comercial del Norte"
    },
    "metadata": {
      "order_id": "48213"
    }
  }'

Resposta

{
  "id": "col_j3QxtZIS4bqB8f7E",
  "object": "collection",
  "mode": "test",
  "method": "spei",
  "status": "pending",
  "account": null,
  "amount": 12500000,
  "currency": "MXN",
  "reference": "KT7Q2M9XA",
  "instructions": {
    "type": "clabe",
    "clabe": "646180153982493432",
    "reference": "KT7Q2M9XA"
  },
  "payer": {
    "name": "Comercial del Norte"
  },
  "metadata": {
    "order_id": "48213"
  },
  "settlement": null,
  "expires_at": "2026-11-10T14:32:00.000Z",
  "paid_at": null,
  "created": "2026-11-10T14:02:00.000Z"
}

GET/v1/collections/:id

Buscar cobrança

Na produção, consulta o banco parceiro se a cobrança ainda estiver pendente.

cURL

curl https://api.kontino.co/v1/collections/col_j3QxtZIS4bqB8f7E \
  -H "Authorization: Bearer sk_test_…"

Resposta

{
  "id": "col_j3QxtZIS4bqB8f7E",
  "object": "collection",
  "mode": "test",
  "method": "spei",
  "status": "paid",
  "account": null,
  "amount": 12500000,
  "currency": "MXN",
  "reference": "KT7Q2M9XA",
  "instructions": {
    "type": "clabe",
    "clabe": "646180153982493432",
    "reference": "KT7Q2M9XA"
  },
  "payer": {
    "name": "Comercial del Norte"
  },
  "metadata": {
    "order_id": "48213"
  },
  "settlement": {
    "currency": "USD",
    "gross": 681199,
    "fee": 6191,
    "net": 675008,
    "fx_rate": 18.35
  },
  "expires_at": "2026-11-10T14:32:00.000Z",
  "paid_at": "2026-11-10T14:03:47.000Z",
  "created": "2026-11-10T14:02:00.000Z"
}

GET/v1/collections

Listar cobranças

Da mais nova para a mais antiga.

Parâmetros da URL

limitinteiro: 1 a 100. Padrão 20.
starting_aftertexto: id do último item da página anterior.
statusenum: pending · paid · expired · canceled
accounttexto: Só as de uma conta conectada.

cURL

curl https://api.kontino.co/v1/collections \
  -H "Authorization: Bearer sk_test_…"

Resposta

{
  "object": "list",
  "data": [
    {
      "id": "col_j3QxtZIS4bqB8f7E",
      "object": "collection",
      "mode": "test",
      "method": "spei",
      "status": "pending",
      "account": null,
      "amount": 12500000,
      "currency": "MXN",
      "reference": "KT7Q2M9XA",
      "instructions": {
        "type": "clabe",
        "clabe": "646180153982493432",
        "reference": "KT7Q2M9XA"
      },
      "payer": {
        "name": "Comercial del Norte"
      },
      "metadata": {
        "order_id": "48213"
      },
      "settlement": null,
      "expires_at": "2026-11-10T14:32:00.000Z",
      "paid_at": null,
      "created": "2026-11-10T14:02:00.000Z"
    }
  ],
  "has_more": false
}

POST/v1/test/collections/:id/pay

Simular pagamento

Sandbox: o comprador paga. Liquida em dólar com a taxa do seu plano.

Só no sandbox (chave sk_test_).

cURL

curl -X POST https://api.kontino.co/v1/test/collections/col_j3QxtZIS4bqB8f7E/pay \
  -H "Authorization: Bearer sk_test_…"

Resposta

{
  "id": "col_j3QxtZIS4bqB8f7E",
  "object": "collection",
  "mode": "test",
  "method": "spei",
  "status": "paid",
  "account": null,
  "amount": 12500000,
  "currency": "MXN",
  "reference": "KT7Q2M9XA",
  "instructions": {
    "type": "clabe",
    "clabe": "646180153982493432",
    "reference": "KT7Q2M9XA"
  },
  "payer": {
    "name": "Comercial del Norte"
  },
  "metadata": {
    "order_id": "48213"
  },
  "settlement": null,
  "expires_at": "2026-11-10T14:32:00.000Z",
  "paid_at": null,
  "created": "2026-11-10T14:02:00.000Z"
}

Pagamentos

Paga uma conta local a partir do saldo em dólar. O débito é o valor convertido mais a taxa; fica reservado enquanto processa e volta ao saldo se falhar.

O objeto

idtexto: Prefixo po_.
statusenum: processing → paid ou failed.
railenum: pix · spei · transfers_ar · co · ach · wire · sepa
amount / currencyinteiro / texto: Quanto chega no destino, na moeda do trilho.
debitobjeto: amount e fee em centavos de dólar, fx_rate.
accounttexto | null: Conta conectada de onde sai. null = o seu saldo.
failure_reasontexto | null: Motivo quando failed.

Objeto

{
  "id": "po_8sLk2PqZr0Vb1mYc",
  "object": "payout",
  "mode": "test",
  "rail": "pix",
  "status": "processing",
  "account": null,
  "amount": 50000,
  "currency": "BRL",
  "beneficiary": {
    "name": "Fornecedor Ltda",
    "pix_key": "financeiro@fornecedor.com.br"
  },
  "debit": {
    "currency": "USD",
    "amount": 9293,
    "fee": 102,
    "fx_rate": 5.44
  },
  "failure_reason": null,
  "metadata": {},
  "completed_at": null,
  "created": "2026-11-10T14:05:00.000Z"
}

POST/v1/payouts

Criar pagamento

Os campos do beneficiário mudam por trilho (tabela abaixo).

Corpo

railenumobrigatório: pix · spei · transfers_ar · co · ach · wire · sepa
amountinteiroobrigatório: Centavos da moeda de destino (BRL, MXN, ARS, USD, EUR).
beneficiaryobjetoobrigatório: Campos do trilho (ver tabela).
accounttexto: acct_… para pagar do saldo de uma conta conectada.
metadataobjeto: Até 20 pares chave/valor.

Veja os campos de cada trilho em Beneficiários por trilho.

cURL

curl -X POST https://api.kontino.co/v1/payouts \
  -H "Authorization: Bearer sk_test_…" \
  -H "Idempotency-Key: pedido-48213" \
  -H "Content-Type: application/json" \
  -d '{
    "rail": "pix",
    "amount": 50000,
    "beneficiary": {
      "name": "Fornecedor Ltda",
      "pix_key": "financeiro@fornecedor.com.br"
    }
  }'

Resposta

{
  "id": "po_8sLk2PqZr0Vb1mYc",
  "object": "payout",
  "mode": "test",
  "rail": "pix",
  "status": "processing",
  "account": null,
  "amount": 50000,
  "currency": "BRL",
  "beneficiary": {
    "name": "Fornecedor Ltda",
    "pix_key": "financeiro@fornecedor.com.br"
  },
  "debit": {
    "currency": "USD",
    "amount": 9293,
    "fee": 102,
    "fx_rate": 5.44
  },
  "failure_reason": null,
  "metadata": {},
  "completed_at": null,
  "created": "2026-11-10T14:05:00.000Z"
}

GET/v1/payouts/:id

Buscar pagamento

Na produção, consulta o banco parceiro se ainda estiver processando.

cURL

curl https://api.kontino.co/v1/payouts/po_8sLk2PqZr0Vb1mYc \
  -H "Authorization: Bearer sk_test_…"

Resposta

{
  "id": "po_8sLk2PqZr0Vb1mYc",
  "object": "payout",
  "mode": "test",
  "rail": "pix",
  "status": "paid",
  "account": null,
  "amount": 50000,
  "currency": "BRL",
  "beneficiary": {
    "name": "Fornecedor Ltda",
    "pix_key": "financeiro@fornecedor.com.br"
  },
  "debit": {
    "currency": "USD",
    "amount": 9293,
    "fee": 102,
    "fx_rate": 5.44
  },
  "failure_reason": null,
  "metadata": {},
  "completed_at": "2026-11-10T14:06:12.000Z",
  "created": "2026-11-10T14:05:00.000Z"
}

GET/v1/payouts

Listar pagamentos

Do mais novo para o mais antigo.

Parâmetros da URL

limitinteiro: 1 a 100. Padrão 20.
starting_aftertexto: id do último item da página anterior.
statusenum: processing · paid · failed
accounttexto: Só os de uma conta conectada.

cURL

curl https://api.kontino.co/v1/payouts \
  -H "Authorization: Bearer sk_test_…"

Resposta

{
  "object": "list",
  "data": [
    {
      "id": "po_8sLk2PqZr0Vb1mYc",
      "object": "payout",
      "mode": "test",
      "rail": "pix",
      "status": "processing",
      "account": null,
      "amount": 50000,
      "currency": "BRL",
      "beneficiary": {
        "name": "Fornecedor Ltda",
        "pix_key": "financeiro@fornecedor.com.br"
      },
      "debit": {
        "currency": "USD",
        "amount": 9293,
        "fee": 102,
        "fx_rate": 5.44
      },
      "failure_reason": null,
      "metadata": {},
      "completed_at": null,
      "created": "2026-11-10T14:05:00.000Z"
    }
  ],
  "has_more": false
}

POST/v1/test/payouts/:id/complete

Concluir pagamento

Sandbox: escolha o desfecho.

Só no sandbox (chave sk_test_).

Corpo

outcomeenum: paid (padrão) · failed

cURL

curl -X POST https://api.kontino.co/v1/test/payouts/po_8sLk2PqZr0Vb1mYc/complete \
  -H "Authorization: Bearer sk_test_…" \
  -H "Content-Type: application/json" \
  -d '{
    "outcome": "paid"
  }'

Resposta

{
  "id": "po_8sLk2PqZr0Vb1mYc",
  "object": "payout",
  "mode": "test",
  "rail": "pix",
  "status": "paid",
  "account": null,
  "amount": 50000,
  "currency": "BRL",
  "beneficiary": {
    "name": "Fornecedor Ltda",
    "pix_key": "financeiro@fornecedor.com.br"
  },
  "debit": {
    "currency": "USD",
    "amount": 9293,
    "fee": 102,
    "fx_rate": 5.44
  },
  "failure_reason": null,
  "metadata": {},
  "completed_at": null,
  "created": "2026-11-10T14:05:00.000Z"
}

Saldo

available é o que dá para pagar agora; reserved são pagamentos em andamento. Tudo em centavos de dólar. Na produção vem da carteira real.

O objeto

availablelista: [{ currency: "USD", amount }]
reservedlista: Pagamentos processando.
pending_collectionsinteiro: Cobranças aguardando depósito.
accounttexto | null: A conta consultada.

Objeto

{
  "object": "balance",
  "mode": "test",
  "available": [
    {
      "currency": "USD",
      "amount": 665715
    }
  ],
  "reserved": [
    {
      "currency": "USD",
      "amount": 0
    }
  ],
  "pending_collections": 3,
  "account": null
}

GET/v1/balance

Buscar saldo

Seu saldo ou o de uma conta conectada.

Parâmetros da URL

accounttexto: acct_… para o saldo de uma conta conectada.

cURL

curl https://api.kontino.co/v1/balance \
  -H "Authorization: Bearer sk_test_…"

Resposta

{
  "object": "balance",
  "mode": "test",
  "available": [
    {
      "currency": "USD",
      "amount": 665715
    }
  ],
  "reserved": [
    {
      "currency": "USD",
      "amount": 0
    }
  ],
  "pending_collections": 3,
  "account": null
}

Contas conectadas

Para plataformas e marketplaces: cada cliente seu tem a própria conta Kontino, verificada pelo Kontino. Crie a conta, mande o link de onboarding e, quando o status virar active, receba e pague com account: "acct_…". O status chega no evento account.updated.

O objeto

idtexto: Prefixo acct_.
statusenum: pending → active ou rejected.
typeenum: individual · business
countrytexto: ISO-2 do país da pessoa ou empresa.
email / nametexto: Contato do titular.
external_idtexto | null: Seu id do cliente (único por modo).

Objeto

{
  "id": "acct_0OaABo8kDDqoB3YP",
  "object": "account",
  "mode": "test",
  "status": "pending",
  "type": "business",
  "country": "MX",
  "email": "financeiro@lojadocliente.mx",
  "name": "Loja do Cliente",
  "external_id": "merchant-8812",
  "metadata": {},
  "created": "2026-11-10T14:00:00.000Z"
}

POST/v1/accounts

Criar conta

Na produção, o e-mail não pode ter conta no Kontino.

Corpo

emailtextoobrigatório: E-mail do titular.
typeenumobrigatório: individual · business
countrytextoobrigatório: ISO-2.
nametexto: Nome do titular ou razão social.
external_idtexto: Seu id do cliente.
return_urltexto: https:// para onde o cliente volta depois do onboarding.
metadataobjeto: Até 20 pares chave/valor.

cURL

curl -X POST https://api.kontino.co/v1/accounts \
  -H "Authorization: Bearer sk_test_…" \
  -H "Idempotency-Key: pedido-48213" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "financeiro@lojadocliente.mx",
    "name": "Loja do Cliente",
    "type": "business",
    "country": "MX",
    "external_id": "merchant-8812"
  }'

Resposta

{
  "id": "acct_0OaABo8kDDqoB3YP",
  "object": "account",
  "mode": "test",
  "status": "pending",
  "type": "business",
  "country": "MX",
  "email": "financeiro@lojadocliente.mx",
  "name": "Loja do Cliente",
  "external_id": "merchant-8812",
  "metadata": {},
  "created": "2026-11-10T14:00:00.000Z"
}

POST/v1/accounts/:id/onboarding_links

Gerar link de onboarding

Link de 24 h para o cliente abrir a conta. Na produção ele envia dados e documentos; no sandbox, aprova ou recusa numa tela simulada.

Corpo

return_urltexto: Substitui o return_url da conta.

cURL

curl -X POST https://api.kontino.co/v1/accounts/acct_0OaABo8kDDqoB3YP/onboarding_links \
  -H "Authorization: Bearer sk_test_…" \
  -H "Idempotency-Key: pedido-48213" \
  -H "Content-Type: application/json" \
  -d '{
    "return_url": "https://suaplataforma.com/onboarding/fim"
  }'

Resposta

{
  "object": "onboarding_link",
  "account": "acct_0OaABo8kDDqoB3YP",
  "url": "https://app.kontino.co/abrir-conta/link?t=eyJhbGciOi…",
  "expires_at": "2026-11-11T14:00:00.000Z"
}

GET/v1/accounts/:id

Buscar conta

cURL

curl https://api.kontino.co/v1/accounts/acct_0OaABo8kDDqoB3YP \
  -H "Authorization: Bearer sk_test_…"

Resposta

{
  "id": "acct_0OaABo8kDDqoB3YP",
  "object": "account",
  "mode": "test",
  "status": "active",
  "type": "business",
  "country": "MX",
  "email": "financeiro@lojadocliente.mx",
  "name": "Loja do Cliente",
  "external_id": "merchant-8812",
  "metadata": {},
  "created": "2026-11-10T14:00:00.000Z"
}

GET/v1/accounts

Listar contas

Parâmetros da URL

limitinteiro: 1 a 100. Padrão 20.
starting_aftertexto: id do último item da página anterior.
statusenum: pending · active · rejected

cURL

curl https://api.kontino.co/v1/accounts \
  -H "Authorization: Bearer sk_test_…"

Resposta

{
  "object": "list",
  "data": [
    {
      "id": "acct_0OaABo8kDDqoB3YP",
      "object": "account",
      "mode": "test",
      "status": "pending",
      "type": "business",
      "country": "MX",
      "email": "financeiro@lojadocliente.mx",
      "name": "Loja do Cliente",
      "external_id": "merchant-8812",
      "metadata": {},
      "created": "2026-11-10T14:00:00.000Z"
    }
  ],
  "has_more": false
}

POST/v1/test/accounts/:id/verify

Simular verificação

Sandbox: aprova ou recusa sem passar pelo link.

Só no sandbox (chave sk_test_).

Corpo

outcomeenum: approved (padrão) · rejected

cURL

curl -X POST https://api.kontino.co/v1/test/accounts/acct_0OaABo8kDDqoB3YP/verify \
  -H "Authorization: Bearer sk_test_…" \
  -H "Content-Type: application/json" \
  -d '{
    "outcome": "approved"
  }'

Resposta

{
  "id": "acct_0OaABo8kDDqoB3YP",
  "object": "account",
  "mode": "test",
  "status": "active",
  "type": "business",
  "country": "MX",
  "email": "financeiro@lojadocliente.mx",
  "name": "Loja do Cliente",
  "external_id": "merchant-8812",
  "metadata": {},
  "created": "2026-11-10T14:00:00.000Z"
}

Eventos

Cada mudança gera um evento, entregue aos seus webhooks e guardado por 30 dias.

O objeto

idtexto: Prefixo evt_. Use para ignorar repetidos.
typetexto: Ver o catálogo de eventos.
data.objectobjeto: O objeto como estava no momento do evento.

Objeto

{
  "object": "list",
  "data": [
    {
      "id": "evt_Qm3Lz8VnR2pX0tYa",
      "object": "event",
      "type": "collection.paid",
      "mode": "test",
      "created": "2026-11-10T14:03:47.000Z",
      "data": {
        "object": {
          "id": "col_j3QxtZIS4bqB8f7E",
          "status": "paid"
        }
      }
    }
  ],
  "has_more": false
}

GET/v1/events

Listar eventos

Parâmetros da URL

limitinteiro: 1 a 100. Padrão 20.
starting_aftertexto: id do último item da página anterior.
typetexto: Ex.: collection.paid

cURL

curl https://api.kontino.co/v1/events \
  -H "Authorization: Bearer sk_test_…"

Resposta

{
  "object": "list",
  "data": [
    {
      "id": "evt_Qm3Lz8VnR2pX0tYa",
      "object": "event",
      "type": "collection.paid",
      "mode": "test",
      "created": "2026-11-10T14:03:47.000Z",
      "data": {
        "object": {
          "id": "col_j3QxtZIS4bqB8f7E",
          "status": "paid"
        }
      }
    }
  ],
  "has_more": false
}

Beneficiários por trilho

rail	Moeda	Campos obrigatórios	Observação
pix	BRL	name, pix_key	Chave Pix de qualquer tipo.
spei	MXN	name, clabe	CLABE de 18 dígitos.
transfers_ar	ARS	name, cbu_cvu, tax_id	CBU, CVU ou alias; tax_id é o CUIT/CUIL do titular.
ach	USD	name, routing_number, account_number, account_type, account_class, address_line_1, city, state, postal_code, country	account_type: checking · saving. account_class: individual · business. Opcionais: address_line_2, tax_id, recipient_relationship.
sepa	EUR	name, iban, account_class, address_line_1, city, postal_code, country	Opcionais: bic, address_line_2, state.
wire	USD	name, routing_number, account_number, account_class, address_line_1, city, state, postal_code, country	Wire doméstico nos EUA. Opcionais: address_line_2, tax_id, recipient_relationship.
co	COP	first_name, last_name, document_type, document_id, email, bank_code, account_number, account_type	ACH Colômbia. document_type: CC, CE, NIT, PASS ou PEP; account_type: checking ou saving.

ACH

{
  "rail": "ach",
  "amount": 250000,
  "beneficiary": {
    "name": "Acme Supplies LLC",
    "routing_number": "021000021",
    "account_number": "483920110",
    "account_type": "checking",
    "account_class": "business",
    "address_line_1": "350 Fifth Ave",
    "city": "New York",
    "state": "NY",
    "postal_code": "10118",
    "country": "US"
  }
}

Sandbox

Tudo simulado e reprodutível, com as mesmas regras da produção.

Moeda	1 USD =
MXN	18,35
ARS	1.450
BRL	5,44
EUR	0,918

CUIT válido para testar Transferencias: 20-12345678-6. Rotas que só existem no sandbox: /test/collections/:id/pay, /test/payouts/:id/complete e /test/accounts/:id/verify. Sem código: Desenvolvedores › Testar no painel.

Produção

As cobranças caem no saldo em dólar da conta Kontino da sua empresa (ou da conta conectada informada).
O titular que o comprador vê na transferência é o banco parceiro, não a sua empresa. Mostre no checkout o valor e a reference para o comprador conferir.
settlement.net é o que entrou no saldo, já com o câmbio do momento e as taxas da sua proposta.
Se um webhook atrasar, GET /collections/:id e GET /payouts/:id consultam o banco parceiro na hora.

Em breve

Em construção. Ainda não há endpoints; quando entrarem, aparecem aqui e em “Versões e mudanças”, sem quebrar o que já existe.

Cartão de crédito internacional. Visa, Mastercard e Amex de qualquer país, com liquidação em dólar no mesmo saldo.
Apple Pay. Pagamento em um toque no iPhone, Mac e Safari, pela mesma cobrança.
Google Pay. Cartões salvos na conta Google, no Android e no Chrome.
Emissão de cartões. Cartões virtuais e físicos para vocês e para as contas conectadas, com limites e controles pela API.

Quer entrar no piloto? Fale com o seu gerente pelo painel.