Convenções da API
Formatos que valem para todas as rotas.
Valores em centavos
Todo valor é um inteiro em centavos de real: 4990 é R$ 49,90. Não há casas decimais nem arredondamento. A tarifa sai em fee_cents e o que entra no seu saldo em net_amount_cents.
amount_cents, são strings por compatibilidade. Use os de data.object, que são inteiros.Datas e identificadores
Datas seguem ISO 8601 em UTC, como 2026-09-24T14:32:11.000Z. Os IDs da Mainum são UUID. O external_id é seu: único por conta em cada recurso, até 128 caracteres.
Paginação
Listas devolvem data e next_cursor, sempre do mais novo para o mais antigo. Para a próxima página, repita a chamada com cursor igual ao next_cursor recebido; ele é null na última página. limit vai de 1 a 100 (padrão 20).
GET /v1/charges?limit=50&status=PAID&cursor=eyJhdCI6IjIwMjYtMDktMjRUMTQ6MzI6MTEuMDAwWiIsImlkIjoi...As listas de cobranças e de saques também filtram por status, external_id, created_from (inclusive) e created_to (exclusive).
Metadata
metadata guarda até 20 pares chave-valor seus (chaves de até 40 caracteres, valores de texto de até 500, 2 KB no total). É gravado na criação, não muda depois e volta em toda consulta, lista e webhook. Não guarde dados pessoais aqui.
request_id e erros
Toda resposta traz request_id. Guarde-o nos seus logs e informe ao suporte quando algo der errado. Erros têm sempre o mesmo formato: error é um código estável para o seu código; message e doc_url explicam para pessoas.
Compatibilidade
Dentro da v1, mudanças são só aditivas: campos, filtros, eventos e rotas novas podem aparecer a qualquer momento. Ignore campos que você não conhece em vez de rejeitar a resposta.