Criar cobrança Pix · Documentação Koku

POSThttps://api.kokupay.com/v1/pix/charges

Cria uma cobrança Pix e devolve o QR Code e o código copia e cola. Envie sempre os quatro dados do pagador (nome, CPF/CNPJ, e-mail e telefone): a emissão do Pix exige esses dados. Quando status vier created sem pix, o resultado da emissão ainda não é conhecido: consulte a cobrança depois e não crie outro pedido.

POST/v1/pix/charges

curl -X POST 'https://api.kokupay.com/v1/pix/charges' \
  -H "Authorization: Bearer $KOKU_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-1001" \
  -d '{
  "order_reference": "PEDIDO-1001",
  "amount_cents": 15990,
  "description": "Pedido 1001 - Loja Exemplo",
  "payer": {
    "name": "Maria Souza",
    "document": "12345678909",
    "email": "maria.souza@example.com",
    "phone": "11987654321"
  },
  "expires_in_seconds": 1800,
  "metadata": {
    "canal": "checkout-web"
  }
}'

const response = await fetch('https://api.kokupay.com/v1/pix/charges', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.KOKU_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': 'pedido-1001',
  },
  body: JSON.stringify({
    order_reference: 'PEDIDO-1001',
    amount_cents: 15990,
    description: 'Pedido 1001 - Loja Exemplo',
    payer: {
      name: 'Maria Souza',
      document: '12345678909',
      email: 'maria.souza@example.com',
      phone: '11987654321',
    },
    expires_in_seconds: 1800,
    metadata: {
      canal: 'checkout-web',
    },
  }),
});

const data = await response.json();
console.log(response.status, data);

import os

import requests

response = requests.request(
    "POST",
    "https://api.kokupay.com/v1/pix/charges",
    headers={
        "Authorization": f"Bearer {os.environ['KOKU_API_KEY']}",
        "Idempotency-Key": "pedido-1001",
    },
    json={
        "order_reference": "PEDIDO-1001",
        "amount_cents": 15990,
        "description": "Pedido 1001 - Loja Exemplo",
        "payer": {
            "name": "Maria Souza",
            "document": "12345678909",
            "email": "maria.souza@example.com",
            "phone": "11987654321",
        },
        "expires_in_seconds": 1800,
        "metadata": {
            "canal": "checkout-web",
        },
    },
    timeout=30,
)

print(response.status_code, response.json())

<?php

$ch = curl_init('https://api.kokupay.com/v1/pix/charges');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('KOKU_API_KEY'),
        'Content-Type: application/json',
        'Idempotency-Key: pedido-1001',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'order_reference' => 'PEDIDO-1001',
        'amount_cents' => 15990,
        'description' => 'Pedido 1001 - Loja Exemplo',
        'payer' => [
            'name' => 'Maria Souza',
            'document' => '12345678909',
            'email' => 'maria.souza@example.com',
            'phone' => '11987654321',
        ],
        'expires_in_seconds' => 1800,
        'metadata' => [
            'canal' => 'checkout-web',
        ],
    ]),
]);

$data = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
echo $status, PHP_EOL;
print_r($data);

Respostas

201 · Criar cobrança Pix

{
  "id": "8d3f6a12-4b9e-4c71-a2d5-6e0f1b3c9a47",
  "gateway_id": "5f0c2a9e-1b7d-4c3e-9a51-2d8e6f4b7c10",
  "environment": "production",
  "order_reference": "PEDIDO-1001",
  "amount_cents": "15990",
  "currency": "BRL",
  "description": "Pedido 1001 - Loja Exemplo",
  "status": "pending",
  "fee_percent_bps": 200,
  "fee_fixed_cents": "0",
  "fee_cents": null,
  "net_cents": null,
  "reserve_cents": null,
  "refunded_cents": "0",
  "expires_at": "2026-10-07T16:00:00.000Z",
  "paid_at": null,
  "late_payment": false,
  "is_simulated": false,
  "created_at": "2026-10-07T15:30:00.000Z",
  "updated_at": "2026-10-07T15:30:01.000Z",
  "pix": {
    "qr_code_payload": "00020101021226850014br.gov.bcb.pix2563qr.exemplo.com.br/pix/v2/8d3f6a124b9e4c71a2d56e0f1b3c9a475204000053039865406159.905802BR5913LOJA EXEMPLO6009SAO PAULO62070503***6304A1B2",
    "txid": "8d3f6a124b9e4c71a2d56e0f1b3c9a47",
    "expires_at": "2026-10-07T16:00:00.000Z"
  },
  "end_to_end_id": null,
  "payments_count": 0,
  "failure_message": null
}

200 · Repetição com a mesma chave

{
  "id": "8d3f6a12-4b9e-4c71-a2d5-6e0f1b3c9a47",
  "gateway_id": "5f0c2a9e-1b7d-4c3e-9a51-2d8e6f4b7c10",
  "environment": "production",
  "order_reference": "PEDIDO-1001",
  "amount_cents": "15990",
  "currency": "BRL",
  "description": "Pedido 1001 - Loja Exemplo",
  "status": "pending",
  "fee_percent_bps": 200,
  "fee_fixed_cents": "0",
  "fee_cents": null,
  "net_cents": null,
  "reserve_cents": null,
  "refunded_cents": "0",
  "expires_at": "2026-10-07T16:00:00.000Z",
  "paid_at": null,
  "late_payment": false,
  "is_simulated": false,
  "created_at": "2026-10-07T15:30:00.000Z",
  "updated_at": "2026-10-07T15:30:01.000Z",
  "pix": {
    "qr_code_payload": "00020101021226850014br.gov.bcb.pix2563qr.exemplo.com.br/pix/v2/8d3f6a124b9e4c71a2d56e0f1b3c9a475204000053039865406159.905802BR5913LOJA EXEMPLO6009SAO PAULO62070503***6304A1B2",
    "txid": "8d3f6a124b9e4c71a2d56e0f1b3c9a47",
    "expires_at": "2026-10-07T16:00:00.000Z"
  },
  "end_to_end_id": null,
  "payments_count": 0,
  "failure_message": null
}

201 · Cobrança recusada na emissão

{
  "id": "e41a9c7b-2d58-4e06-b3f1-7c9d0a2e5b18",
  "gateway_id": "5f0c2a9e-1b7d-4c3e-9a51-2d8e6f4b7c10",
  "environment": "production",
  "order_reference": "PEDIDO-1003",
  "amount_cents": "15990",
  "currency": "BRL",
  "description": "Pedido 1003 - Loja Exemplo",
  "status": "failed",
  "fee_percent_bps": 200,
  "fee_fixed_cents": "0",
  "fee_cents": null,
  "net_cents": null,
  "reserve_cents": null,
  "refunded_cents": "0",
  "expires_at": null,
  "paid_at": null,
  "late_payment": false,
  "is_simulated": false,
  "created_at": "2026-10-07T15:30:00.000Z",
  "updated_at": "2026-10-07T15:30:01.000Z",
  "pix": null,
  "end_to_end_id": null,
  "payments_count": 0,
  "failure_message": "Emissão recusada pela análise de risco."
}

409 · Mesma chave, outro corpo

{
  "error": {
    "code": "idempotency_conflict",
    "message": "A mesma chave de idempotência foi usada com um corpo diferente.",
    "details": {},
    "correlation_id": "0b1e6f3a-2c9d-4e57-8a14-c6d2f9e07b31"
  }
}

422 · Campo inválido

{
  "error": {
    "code": "validation_error",
    "message": "Requisição inválida: confira os campos indicados.",
    "details": {
      "fields": [
        {
          "field": "body/amount_cents",
          "rule": "union"
        }
      ]
    },
    "correlation_id": "5a9c2e71-8d3f-4b06-91e4-7f2b0c6d8a53"
  }
}

Autenticação

Authorization: Bearer <sua chave de API>

Escopo exigido: charges:write. Veja Chaves de API.

Cabeçalhos

Idempotency-Keystringobrigatório

Chave única por operação (8 a 200 caracteres ASCII visíveis). Repetir com o mesmo corpo devolve o mesmo resultado.

8 a 200 caracteres

Veja Idempotência.

Corpo da requisição

JSON (Content-Type: application/json). Campos não listados são recusados com 422.

order_referencestringobrigatório

Identificador do pedido no seu sistema. Único por conta: não pode ser reutilizado em outra cobrança.

1 a 120 caracteres

amount_centsinteiro ou stringobrigatório

Valor da cobrança em centavos, inteiro positivo (número JSON ou string decimal). 15990 = R$ 159,90.

currencystring

Moeda. Só BRL; pode ser omitida.

Valores: BRL

descriptionstring

Descrição exibida para você no painel. Até 500 caracteres.

até 500 caracteres

payerobjetoobrigatório

Dados do pagador. Exigidos para emitir o Pix: sem eles a emissão pode ser recusada.

payer.namestringobrigatório

Nome completo do pagador (até 200 caracteres).

até 200 caracteres

payer.documentstringobrigatório

CPF (11 dígitos) ou CNPJ (14 dígitos) do pagador, só números.

payer.emailstringobrigatório

E-mail do pagador. Usado só para emitir o Pix; a Koku não o grava.

até 254 caracteres

payer.phonestringobrigatório

Telefone com DDD, só dígitos, com ou sem +55 (ex.: 11987654321). Usado só para emitir o Pix; a Koku não o grava.

expires_in_secondsinteiro

Validade do QR em segundos, de 60 (1 minuto) a 604800 (7 dias). Padrão: 3600 (1 hora).

de 60 a 604800

metadataobjeto

Até 20 pares chave/valor de texto para o seu controle (chave até 60 e valor até 500 caracteres).

Resposta 201

201 na criação; 200 com o mesmo recurso quando a requisição é repetida com a mesma Idempotency-Key e o mesmo corpo (cabeçalho Idempotent-Replayed: true).

idstring (uuid)

Identificador da cobrança na Koku.

gateway_idstring (uuid)

Identificador da sua conta na Koku.

environmentstring

Ambiente da cobrança: production (sandbox está reservado para o ambiente de testes, em preparação).

Valores: sandbox, production

order_referencestring

Identificador do pedido enviado por você.

amount_centsstring (centavos)

Valor bruto da cobrança, em centavos (string decimal: "15990" = R$ 159,90).

currencystring

Moeda (BRL).

Valores: BRL

descriptionstring ou null

Descrição enviada na criação.

statusstring

Estado da cobrança. Veja Estados da cobrança.

Valores: created, pending, paid, partially_refunded, refunded, expired, cancelled, failed

fee_percent_bpsinteiro

Parte percentual da tarifa vigente na criação, em pontos-base (200 = 2,00%).

fee_fixed_centsstring (centavos)

Parte fixa da tarifa por transação, em centavos.

fee_centsstring (centavos) ou null

Tarifa da Koku sobre a venda, em centavos. null até o pagamento.

net_centsstring (centavos) ou null

Valor líquido da venda (bruto − tarifa), em centavos. null até o pagamento.

reserve_centsstring (centavos) ou null

Parte do líquido retida como reserva contratual, em centavos. null até o pagamento.

refunded_centsstring (centavos)

Total já devolvido ao pagador, em centavos.

expires_atstring (data e hora) ou null

Fim da validade do QR.

paid_atstring (data e hora) ou null

Momento do pagamento confirmado.

late_paymentbooleano

true quando o pagamento chegou depois da expiração (pagamento tardio).

is_simulatedbooleano

false em produção. true fica reservado para cobranças do ambiente de testes (em preparação), sem dinheiro real.

created_atstring (data e hora)

Criação da cobrança.

updated_atstring (data e hora)

Última alteração.

pixobjeto ou null

QR vigente. null enquanto a emissão não terminou ou quando a cobrança foi recusada.

pix.qr_code_payloadstring ou null

Código Pix copia e cola (BR Code). Gere a imagem do QR Code a partir dele.

pix.txidstring ou null

Identificador da transação Pix.

pix.expires_atstring (data e hora) ou null

Fim da validade deste QR.

end_to_end_idstring ou null

Identificador fim a fim (E2E) do Pix recebido. Preenchido quando paga.

payments_countinteiro

Quantidade de pagamentos recebidos para esta cobrança (inclui duplicados).

failure_messagestring ou null

Quando status é failed: motivo da recusa em texto fixo da Koku, próprio para exibir (ex.: Emissão recusada pela análise de risco.). Os textos possíveis estão em Estados da cobrança. null nos demais estados.

Erros

Status	Código	Quando
401	`unauthorized`	Chave ausente, inválida, revogada ou expirada.
403	`forbidden`	A chave não tem o escopo exigido (`details.reason = "missing_scope"`).
409	`idempotency_conflict`	A mesma `Idempotency-Key` foi usada com um corpo diferente.
409	`conflict`	`order_reference` já usado por outra cobrança (`details.reason = "order_reference_in_use"`).
422	`validation_error`	Campo inválido ou ausente, inclusive `Idempotency-Key` (`details.fields`).
429	`rate_limited`	Limite de requisições excedido. Aguarde o tempo de `Retry-After`.
503	`provider_unavailable`	A rede de processamento da Koku não pôde emitir o Pix e nenhuma cobrança foi criada. `details.reason = "processing_unavailable"`: indisponibilidade momentânea; repita com a mesma `Idempotency-Key`. `details.reason = "account_not_enabled"`: o recebimento Pix ainda não está habilitado para a sua conta; repetir não resolve, fale com a Koku.
503	`service_unavailable`	Instabilidade momentânea. Repita com a mesma `Idempotency-Key`.
500	`internal_error`	Falha inesperada. Repita com a mesma `Idempotency-Key`; persistindo, envie o `correlation_id` à Koku (veja Suporte).

Formato do corpo de erro em Erros.

#Autenticação

#Cabeçalhos

#Corpo da requisição

#Resposta 201

#Erros

Autenticação

Cabeçalhos

Corpo da requisição

Resposta 201

Erros