Criar cobrança

Gera uma cobrança Pix e devolve o copia e cola para o pagador.

POST/v1/chargesescopo: charge:write

Exige o header Idempotency-Key. Repetir a chamada com a mesma chave devolve a cobrança já criada.

Corpo

`amount` inteiro (centavos)obrigatório	Mínimo e máximo por cobrança são definidos pelo administrador da plataforma (padrão: a partir de R$ 1,00, sem teto).
`method` stringopcional	Apenas "pix" na v1. Padrão "pix".
`customer.name` stringobrigatório	Nome do pagador.
`customer.email` stringobrigatório	E-mail válido do pagador.
`customer.document` stringobrigatório	CPF ou CNPJ, com ou sem máscara. O adquirente exige.
`customer.phone` stringopcional	Telefone do pagador.
`description` stringopcional	Até 140 caracteres. Aparece na sua listagem de cobranças.
`reference` stringopcional	Seu identificador. Volta em todas as respostas e eventos desta cobrança.
`expires_in` inteiro (segundos)opcional	De 60 a 604800 (7 dias). Sem isso, vale o padrão da conta.
`webhook_url` stringopcional	Recebe todos os eventos desta cobrança, sem cadastro prévio. É a forma recomendada de ser avisado do pagamento. Precisa ser http(s) e pública.
`webhook_secret` stringopcional	Assina as entregas feitas a webhook_url (header X-Webhook-Signature).

Exemplo

cURL

curl -X POST https://api.transakto.io/v1/charges \
  -H "x-api-key: sk_live_..." \
  -H "Idempotency-Key: pedido-1042" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 4990,
    "method": "pix",
    "description": "Assinatura mensal",
    "reference": "pedido-1042",
    "expires_in": 3600,
    "customer": {
      "name": "Maria Souza",
      "email": "maria@exemplo.com.br",
      "document": "123.456.789-09"
    },
    "webhook_url": "https://meusistema.com.br/hooks/pagamentos",
    "webhook_secret": "um-segredo-bem-longo"
  }'

Resposta 201

{
  "id": "8f1c2a90-1f4b-4f0e-9d33-5a2c1b7e9a10",
  "object": "charge",
  "status": "pending",
  "amount": 4990,
  "currency": "BRL",
  "method": "pix",
  "description": "Assinatura mensal",
  "reference": "pedido-1042",
  "customer": {
    "name": "Maria Souza",
    "email": "maria@exemplo.com.br",
    "document": "12345678909"
  },
  "pix": {
    "br_code": "00020126580014BR.GOV.BCB.PIX...",
    "end_to_end_id": null
  },
  "receiver": {
    "name": "Loja Exemplo LTDA",
    "document": "12345678000199",
    "pix_key": "financeiro@exemplo.com.br",
    "pix_key_type": "EMAIL",
    "institution_name": "Banco Exemplo",
    "institution_ispb": "00000000",
    "branch": "0001",
    "account": "1234567",
    "account_type": "CACC"
  },
  "webhook_url": "https://meusistema.com.br/hooks/pagamentos",
  "expires_at": "2026-07-28T15:00:00.000Z",
  "paid_at": null,
  "created_at": "2026-07-28T14:00:00.000Z"
}

pix.br_code é o payload EMV. Exiba como texto para copiar e como QR Code gerado a partir dessa mesma string. Não há URL de imagem: o QR é derivado do código, e gerá-lo no seu lado evita depender de outra chamada de rede na hora do checkout.

Erros comuns

INVALID_DOCUMENT quando o CPF ou CNPJ não passa na validação de dígito. METHOD_NOT_SUPPORTED para boleto ou cartão. METHOD_DISABLED quando o método foi desligado pela plataforma. AMOUNT_BELOW_MINIMUM e AMOUNT_ABOVE_MAXIMUM quando o valor sai dos limites configurados: a mensagem traz o limite em centavos e em reais. ACQUIRER_REJECTED quando o adquirente recusa: a mensagem repassa o motivo que ele devolveu.

A cobrança é gravada antes de ir ao adquirente. Por isso, mesmo recusada, ela existe: o corpo do 422 traz o charge_id, e consultar esse id devolve a cobrança com status failed e o motivo em failure_reason. Repetir o pedido com a mesma Idempotency-Key devolve essa mesma cobrança falha. Para tentar de novo, use uma chave nova.

A cobrança criada pela API aparece na dashboard junto com as do checkout, marcada com origem API.

Corpo

Exemplo#

Mostrando o Pix ao pagador#

Erros comuns#

Exemplo

Mostrando o Pix ao pagador

Erros comuns