Criar Cobrança

post

https://api.toktus.com/api/v1/charges/

Cria uma transação de pagamento no gateway selecionado.

Métodos de pagamento disponíveis:

Método	Campo obrigatório	Retorno específico
`credit_card`	`creditCard` (token, paymentMethodId ou dados raw)	Status da transação
`boleto`	`boleto.dueDate` (data de vencimento)	`boletoUrl` + `boletoBarcode`
`pix`	`pix.expiresInSeconds`	QR Code via endpoint PIX

Valores sempre em centavos (R$ 100,00 = 10000).

Pré-autorização: Envie capture: false para reservar o valor no cartão sem cobrar. Confirme depois via endpoint de captura.

Asaas: customerId é obrigatório — cadastre o cliente antes.
Mercado Pago: Cartão exige creditCard.token gerado no frontend.

Split por gateway: disponível em Stripe, Pagar.me e Asaas. Mercado Pago e PagSeguro não suportam split via API key (exigem credenciamento marketplace próprio) — cobranças com split nesses gateways são rejeitadas com 422 SPLIT_NOT_SUPPORTED (nunca cobradas sem o repasse); no fallback, eles são pulados.

Idempotência: envie o header Idempotency-Key (até 255 caracteres, único por tentativa). Retries com a mesma chave devolvem a resposta original — nunca criam segunda cobrança (janela de 24h; a resposta repetida vem com o header Idempotency-Replayed: true). Requisições simultâneas com a mesma chave recebem 409.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Body Params

gateway

string

enum

Identificador do gateway de pagamento:

stripe — Gateway internacional com APIs modernas
pagarme — Gateway brasileiro com boa documentação
asaas — Focado em cobranças recorrentes e boletos
mercadopago — Maior gateway da América Latina
pagseguro — Gateway tradicional do Brasil (PagBank)

Allowed:

paymentMethod

string

enum

required

Método de pagamento utilizado na transação:

credit_card — Cartão de crédito (à vista ou parcelado)
debit_card — Cartão de débito (aprovação instantânea)
boleto — Boleto bancário (compensação em 1-3 dias úteis)
pix — Pagamento instantâneo via PIX (disponível 24/7)

Allowed:

amount

integer

required

≥ 100

Valor da cobrança em centavos (R$ 100,00 = 10000). Valor mínimo: R$ 1,00 (100 centavos)

currency

string

length between 3 and 3

Defaults to BRL

Moeda (padrão: BRL)

description

string

length ≤ 200

Descrição identificadora da cobrança

capture

boolean

Defaults to true

Captura imediata. false = pré-autorização (reserva o valor sem cobrar)

customerId

string

ID do cliente no gateway (retornado em POST /api/v1/customers). Obrigatório para Asaas.

customer

object

Dados do pagador inline (alternativa ao customerId). Aceito por Stripe, Pagar.me e PagSeguro. Asaas exige customerId separado.

creditCard

object

Dados do cartão de crédito. Obrigatório quando paymentMethod = credit_card.

Prioridade de campos: paymentMethodId > token > dados raw (number/expMonth/expYear/cvv).

Compatibilidade por gateway:

Gateway	Token	PaymentMethod ID	Dados raw
Stripe			(requer ativação)
Pagar.me
Asaas
Mercado Pago	(obrigatório)	(alias)
PagSeguro	(encrypted)	(alias)

boleto

object

Configuração do boleto bancário. Obrigatório quando paymentMethod = boleto.

pix

object

Configuração do pagamento PIX. Obrigatório quando paymentMethod = pix.

split

array of objects

Regras de divisão de recebimento (split).

Suporte por gateway:

Gateway	Split
Stripe	✅
Pagar.me	✅
Asaas	✅ (`walletId`)
Mercado Pago	❌ — rejeitado com `422 SPLIT_NOT_SUPPORTED`
PagSeguro	❌ — rejeitado com `422 SPLIT_NOT_SUPPORTED`

Mercado Pago e PagSeguro só dividem via modelo marketplace (OAuth/credenciamento próprio), indisponível via API key. Pra sua segurança, cobranças com split nesses gateways são rejeitadas — nunca cobradas sem o repasse. No fallback, gateways sem suporte a split são pulados automaticamente.

Recomendado — use coprodutores cadastrados: informe coproducerId ou coproducerEmail. O Toktus API resolve automaticamente o ID correto para o gateway que processar (incluindo fallback).

Alternativa — ID direto do gateway: informe o campo nativo do gateway que você está usando. O valor não é portável para outros gateways (não funciona em fallback):

Campo	Gateway	Exemplo
`recipientId`	genérico (camelCase)	`re_xxx`
`recipient_id`	Pagar.me	`re_cmk1d6e2...`
`walletId`	Asaas	`w_xxx`
`destination`	Stripe Connect	`acct_xxx`

A soma dos amount deve ser 100 quando type = percentage.

split

code

string

length ≤ 255

Código do pedido ou venda no seu sistema (opcional). Use para agrupar cobranças de um mesmo pedido.

metadata

object

Metadados adicionais vinculados à cobrança

Responses

201Default Response