Criar cobrança

curl -X POST https://bukio-backend-production.up.railway.app/v1/payments \
  -H "Authorization: Bearer bk_live_..." \
  -H "Idempotency-Key: pedido-1842" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 15000,
    "method": "pix",
    "description": "Pedido 1842",
    "expiresInMinutes": 30
  }'

# Cartão: "method": "card" (a resposta traz o paymentUrl)
# Cripto: "method": "crypto", "cryptoCurrency": "btc" (a resposta traz crypto)
# Divisão: "split": [{ "subaccountId": "vendedor-42", "amount": 10000 }, { "subaccountId": "vendedor-77", "amount": 4000 }]

const res = await fetch("https://bukio-backend-production.up.railway.app/v1/payments", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BUKIO_API_KEY}`,
    "Idempotency-Key": "pedido-1842",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ amount: 15000, description: "Pedido 1842", expiresInMinutes: 30 }),
});
const charge = await res.json();
console.log(charge.id, charge.copyPaste);

import os, requests

res = requests.post(
    "https://bukio-backend-production.up.railway.app/v1/payments",
    headers={
        "Authorization": f"Bearer {os.environ['BUKIO_API_KEY']}",
        "Idempotency-Key": "pedido-1842",
    },
    json={"amount": 15000, "description": "Pedido 1842", "expiresInMinutes": 30},
)
charge = res.json()
print(charge["id"], charge["copyPaste"])

<?php
$ch = curl_init("https://bukio-backend-production.up.railway.app/v1/payments");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("BUKIO_API_KEY"),
        "Idempotency-Key: pedido-1842",
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => json_encode(["amount" => 15000, "description" => "Pedido 1842", "expiresInMinutes" => 30]),
]);
$charge = json_decode(curl_exec($ch), true);
echo $charge["id"], " ", $charge["copyPaste"];

{
  "id": "BKY-7KQ2M9XP4RZT",
  "status": "pending",
  "statusTitle": "Entrada pendente",
  "method": "pix",
  "methodTitle": "Pix",
  "amount": 15000,
  "fee": 0,
  "refundedAmount": 0,
  "description": "Pedido 1842",
  "txid": "7kq2m9xp4rzt1a2b3c4d5e6f",
  "copyPaste": "00020126580014br.gov.bcb.pix...6304ABCD",
  "paymentUrl": null,
  "crypto": null,
  "card": null,
  "expiresAt": "2026-10-08T15:30:00.000Z",
  "paidAt": null,
  "customer": null,
  "payer": null,
  "subaccountId": null,
  "split": null,
  "createdAt": "2026-10-08T15:00:00.000Z"
}

{
  "error": { "code": "BELOW_MINIMUM", "message": "O valor mínimo da cobrança é R$ 1,00." },
  "requestId": "req_01JA..."
}

POST

payments

curl -X POST https://bukio-backend-production.up.railway.app/v1/payments \
  -H "Authorization: Bearer bk_live_..." \
  -H "Idempotency-Key: pedido-1842" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 15000,
    "method": "pix",
    "description": "Pedido 1842",
    "expiresInMinutes": 30
  }'

# Cartão: "method": "card" (a resposta traz o paymentUrl)
# Cripto: "method": "crypto", "cryptoCurrency": "btc" (a resposta traz crypto)
# Divisão: "split": [{ "subaccountId": "vendedor-42", "amount": 10000 }, { "subaccountId": "vendedor-77", "amount": 4000 }]

const res = await fetch("https://bukio-backend-production.up.railway.app/v1/payments", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BUKIO_API_KEY}`,
    "Idempotency-Key": "pedido-1842",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ amount: 15000, description: "Pedido 1842", expiresInMinutes: 30 }),
});
const charge = await res.json();
console.log(charge.id, charge.copyPaste);

import os, requests

res = requests.post(
    "https://bukio-backend-production.up.railway.app/v1/payments",
    headers={
        "Authorization": f"Bearer {os.environ['BUKIO_API_KEY']}",
        "Idempotency-Key": "pedido-1842",
    },
    json={"amount": 15000, "description": "Pedido 1842", "expiresInMinutes": 30},
)
charge = res.json()
print(charge["id"], charge["copyPaste"])

<?php
$ch = curl_init("https://bukio-backend-production.up.railway.app/v1/payments");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("BUKIO_API_KEY"),
        "Idempotency-Key: pedido-1842",
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => json_encode(["amount" => 15000, "description" => "Pedido 1842", "expiresInMinutes" => 30]),
]);
$charge = json_decode(curl_exec($ch), true);
echo $charge["id"], " ", $charge["copyPaste"];

{
  "id": "BKY-7KQ2M9XP4RZT",
  "status": "pending",
  "statusTitle": "Entrada pendente",
  "method": "pix",
  "methodTitle": "Pix",
  "amount": 15000,
  "fee": 0,
  "refundedAmount": 0,
  "description": "Pedido 1842",
  "txid": "7kq2m9xp4rzt1a2b3c4d5e6f",
  "copyPaste": "00020126580014br.gov.bcb.pix...6304ABCD",
  "paymentUrl": null,
  "crypto": null,
  "card": null,
  "expiresAt": "2026-10-08T15:30:00.000Z",
  "paidAt": null,
  "customer": null,
  "payer": null,
  "subaccountId": null,
  "split": null,
  "createdAt": "2026-10-08T15:00:00.000Z"
}

{
  "error": { "code": "BELOW_MINIMUM", "message": "O valor mínimo da cobrança é R$ 1,00." },
  "requestId": "req_01JA..."
}

Escopo da forma de pagamento: payments:write no Pix, card:write no cartão e crypto:write em cripto (sem ele, 403 FORBIDDEN). A cobrança nasce pending; quando o pagamento é confirmado, vira paid e o webhook payment.paid avisa. Sem pagamento até a validade, vira expired (no Pix, ainda assim é creditada se o Pix cair depois). Veja antes as formas disponíveis para a conta.

string

required

8 a 128 caracteres, única por pedido (um UUID ou o número do pedido). Repetir com os mesmos dados devolve a mesma cobrança; com dados diferentes, 422 IDEMPOTENCY_KEY_REUSED.

integer

required

Valor em centavos. Abaixo do mínimo da conta: BELOW_MINIMUM; fora da faixa aceita no momento: BELOW_PROVIDER_MINIMUM ou ABOVE_PROVIDER_MAXIMUM.

string

default:"pix"

Forma de pagamento: pix (Copia e Cola e QR Code), card (cartão de crédito à vista, a partir de R

5,00, link válido por 30 minutos) ou `crypto` (a partir de R

2,00, válido por 10 minutos). Forma indisponível no momento: 422 METHOD_UNAVAILABLE.

string

default:"ltc"

Só com method: "crypto": ltc (padrão), btc, eth, sol, trx, doge, ada ou matic. Fora da lista: INVALID_CRYPTO_CURRENCY; enviada em outra forma: VALIDATION.

string

Até 140 caracteres. Vai para o extrato e para o webhook; no cartão, aparece também na página de pagamento.

integer

Só no Pix: validade do QR Code, de 5 a 43200 (30 dias). Sem o campo, a validade padrão da conta.

string

UUID de um cliente seu. Cliente de outra conta ou excluído: 422 INVALID_CUSTOMER.

string

sacc_... ou externalId de uma subconta: quando paga, a venda é creditada a ela (menos a tarifa e a sua comissão). Desativada: 422 SUBACCOUNT_INACTIVE; se ela for desativada depois, a venda fica com você.

object[]

Divide a venda entre até 10 subcontas, no lugar de subaccountId (os dois juntos: 422 INVALID_SPLIT). Cada item é { "subaccountId": "sacc_... ou externalId", "amount": centavos }; a soma pode ser menor que o valor (o resto fica com você), nunca maior. A mesma subconta duas vezes, parte sem valor ou mais de 10: 422 INVALID_SPLIT. Quando paga, cada subconta recebe a parte dela menos a sua comissão e a tarifa da WyzeCash na proporção da parte. Estorno e MED tiram de cada uma na mesma proporção.

object

Rastreio para os plugins de marketing ligados no painel. Campos opcionais, textos de até 500 caracteres: utm_source, utm_medium, utm_campaign, utm_content, utm_term, src, sck, fbc, fbp, gaClientId, gaSessionId, ip, userAgent, pageUrl. Nada disso vai para quem paga.

Resposta

string

Código da cobrança (BKY- + 12).

string

pending, paid, expired ou refunded.

string

Texto em português: Entrada pendente, paga (Pix recebido, Cartão aprovado ou Cripto recebida), Entrada expirada, Estornada.

string

pix, card ou crypto.

string

Pix, Cartão de crédito ou Cripto.

integer

Valor cobrado.

integer

Tarifa descontada quando paga (0 antes).

integer

Quanto já foi estornado ao pagador.

string | null

A descrição enviada.

string

Identificador do Pix, o mesmo que consta no QR Code.

string | null

Pix: o código Copia e Cola (BR Code). Gere o QR Code a partir dele. null no cartão e na cripto.

string | null

Cartão: o link da página segura de pagamento, para mandar ao cliente ou abrir num botão. null nas outras formas.

object | null

Cripto: o que o cliente precisa para pagar. null nas outras formas.

Show propriedades

string

Moeda (btc, ltc…).

string

Nome da moeda, ex.: Bitcoin (BTC).

string

Valor exato na moeda, em texto (sem arredondar).

string

Endereço da carteira que recebe.

object | null

Cartão aprovado: brand (bandeira) e last4 (final). null antes do pagamento e nas outras formas.

string | null

Cartão: quando o valor sai da retenção e entra no saldo disponível (15 dias depois da aprovação, D+15).

boolean

Cartão: se o valor já entrou no saldo disponível.

string

Validade (ISO 8601).

string | null

Hora do pagamento.

object | null

Cliente ligado.

Show propriedades

string

UUID do cliente.

string | null

Nome.

object | null

Quem pagou, como o banco informou. null antes do pagamento.

Show propriedades

string | null

Nome do pagador.

string | null

CPF sempre mascarado (***.456.789-**) ou CNPJ.

string | null

Banco do pagador.

string | null

A subconta da venda (sacc_...), quando há uma só.

object[] | null

A divisão: { subaccountId, name, amount } de cada subconta. null sem divisão.

string

Criação (ISO 8601).

curl -X POST https://bukio-backend-production.up.railway.app/v1/payments \
  -H "Authorization: Bearer bk_live_..." \
  -H "Idempotency-Key: pedido-1842" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 15000,
    "method": "pix",
    "description": "Pedido 1842",
    "expiresInMinutes": 30
  }'

# Cartão: "method": "card" (a resposta traz o paymentUrl)
# Cripto: "method": "crypto", "cryptoCurrency": "btc" (a resposta traz crypto)
# Divisão: "split": [{ "subaccountId": "vendedor-42", "amount": 10000 }, { "subaccountId": "vendedor-77", "amount": 4000 }]

const res = await fetch("https://bukio-backend-production.up.railway.app/v1/payments", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BUKIO_API_KEY}`,
    "Idempotency-Key": "pedido-1842",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ amount: 15000, description: "Pedido 1842", expiresInMinutes: 30 }),
});
const charge = await res.json();
console.log(charge.id, charge.copyPaste);

import os, requests

res = requests.post(
    "https://bukio-backend-production.up.railway.app/v1/payments",
    headers={
        "Authorization": f"Bearer {os.environ['BUKIO_API_KEY']}",
        "Idempotency-Key": "pedido-1842",
    },
    json={"amount": 15000, "description": "Pedido 1842", "expiresInMinutes": 30},
)
charge = res.json()
print(charge["id"], charge["copyPaste"])

<?php
$ch = curl_init("https://bukio-backend-production.up.railway.app/v1/payments");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("BUKIO_API_KEY"),
        "Idempotency-Key: pedido-1842",
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => json_encode(["amount" => 15000, "description" => "Pedido 1842", "expiresInMinutes" => 30]),
]);
$charge = json_decode(curl_exec($ch), true);
echo $charge["id"], " ", $charge["copyPaste"];

{
  "id": "BKY-7KQ2M9XP4RZT",
  "status": "pending",
  "statusTitle": "Entrada pendente",
  "method": "pix",
  "methodTitle": "Pix",
  "amount": 15000,
  "fee": 0,
  "refundedAmount": 0,
  "description": "Pedido 1842",
  "txid": "7kq2m9xp4rzt1a2b3c4d5e6f",
  "copyPaste": "00020126580014br.gov.bcb.pix...6304ABCD",
  "paymentUrl": null,
  "crypto": null,
  "card": null,
  "expiresAt": "2026-10-08T15:30:00.000Z",
  "paidAt": null,
  "customer": null,
  "payer": null,
  "subaccountId": null,
  "split": null,
  "createdAt": "2026-10-08T15:00:00.000Z"
}

{
  "error": { "code": "BELOW_MINIMUM", "message": "O valor mínimo da cobrança é R$ 1,00." },
  "requestId": "req_01JA..."
}

Visão geral

Saldo

Cobranças

Links de pagamento

Extrato

Saques

Subcontas

Clientes

MED

Resposta

​Resposta

Resposta