Depósitos e faturas
Use uma fatura para um pedido único com preço fixo. Use um depósito para um saldo de cliente que pode ser recarregado repetidamente.
Crie uma fatura
Seção intitulada “Crie uma fatura”curl -X POST 'https://platform.invoise.me/api/v1/shops/{shop_id}/invoices' \ -H 'Authorization: Bearer ivk_...' \ -H 'Idempotency-Key: <saved-unique-key>' \ -H 'Content-Type: application/json' \ -d "{\"chain_id\":${CHAIN_ID:?},\"token\":\"${TOKEN_ADDRESS:?}\",\"amount\":\"${AMOUNT:?}\",\"external_id\":\"order-123\"}"Substitua {shop_id} pelo ID da sua loja. Defina CHAIN_ID e TOKEN_ADDRESS a partir da resposta da API e AMOUNT nas menores unidades do token selecionado. external_id vincula a fatura a um pedido no seu sistema; ele não substitui a chave de idempotência.
Campos opcionais: description (até 500 caracteres), external_id (até 200) e return_url, que deve ser uma URL https://. Uma description ou um external_id mais longos retornam 400 invalid_description; outro return_url retorna 400 invalid_return_url. Depósitos aceitam os mesmos campos.
A resposta é 202 Accepted e já traz o address de pagamento e o payment_url; a fatura fica open imediatamente. Salve o id dela e dê ao pagador o payment_url retornado. Se a resposta for 503 address_unavailable, repita a mesma requisição com a mesma Idempotency-Key.
Pagamentos parciais se somam. Assim que dinheiro confirmado suficiente chega, o Invoise agenda o repasse e fecha a fatura. O destinatário recebe o valor da fatura menos a taxa de serviço. Qualquer pagamento em excesso vai para o Invoise, não para o destinatário.
Faturas são pagamentos únicos; elas não se renovam automaticamente.
Vida útil da fatura
Seção intitulada “Vida útil da fatura”Uma fatura permanece aberta por 30 dias por padrão. O Invoise pode mudar esse padrão, então envie expires_in se a sua integração depende da vida útil. Para escolher outra vida útil, adicione expires_in ao corpo da requisição, por exemplo "expires_in":"7d". Os valores permitidos são 1h, 2h, 1d, 7d, 30d, 180d e 365d.
As respostas de fatura, incluindo a página de pagamento pública, carregam expires_at. Quando esse prazo passa, uma fatura não paga se fecha: cancelled_at é definido e o webhook invoice.cancelled é enviado com data.reason definido como expired. Um pagamento que chega depois ainda é registrado e ainda pode se liquidar, assim como com uma fatura cancelada. Para vigências curtas como 1h, 2h ou 1d, assine invoice.cancelled para saber do vencimento na hora.
Depósitos não expiram. Enviar expires_in ao criar um depósito retorna 400 invalid_expires_in.
Crie um endereço de depósito
Seção intitulada “Crie um endereço de depósito”Use os mesmos cabeçalhos da requisição com este endpoint e corpo:
curl -X POST 'https://platform.invoise.me/api/v1/shops/{shop_id}/deposits' \ -H 'Authorization: Bearer ivk_...' \ -H 'Idempotency-Key: <saved-unique-key>' \ -H 'Content-Type: application/json' \ -d "{\"chain_id\":${CHAIN_ID:?},\"token\":\"${TOKEN_ADDRESS:?}\",\"external_id\":\"customer-123\"}"Não defina um amount fixo. O endereço vem na resposta de criação, como em uma fatura. O endereço pode receber recargas repetidas no token e na rede escolhidos.
Depósitos pequenos se acumulam até atingirem o limite de repasse da loja. Leia-o em GET /api/v1/shops/{shop_id}/terms. A Invoise cobra a taxa de cada repasse, não de cada transferência recebida: recargas repassadas juntas pagam uma taxa, e a taxa mínima da rede se aplica uma vez por repasse. Uma fatura paga a taxa uma vez, sobre o valor da fatura.
Ofereça vários tokens ou redes
Seção intitulada “Ofereça vários tokens ou redes”Envie assets em vez de chain_id e token para deixar o pagador escolher como pagar. Funciona para faturas e depósitos:
curl -X POST 'https://platform.invoise.me/api/v1/shops/{shop_id}/invoices' \ -H 'Authorization: Bearer ivk_...' \ -H 'Idempotency-Key: <saved-unique-key>' \ -H 'Content-Type: application/json' \ -d '{"assets":[{"chain_id":<chain-id>,"token":"<token-address>"},{"chain_id":<other-chain-id>,"token":"<other-token-address>"}],"amount":"10.5","external_id":"order-124"}'Com assets, o amount da fatura é um valor de token decimal, como "10.5", não unidades base: os tokens podem ter casas decimais diferentes. Cada opção deve atingir o minimum_payment da sua rede.
A resposta é um grupo. Cada opção é uma fatura ou endereço de depósito separado, com seu próprio address, valor em unidades base e status:
{ "id": "<group-id>", "group": true, "shop_id": "<shop-id>", "public_id": "<public-id>", "status": "open", "payment_url": "https://pay.invoise.me/<public-id>", "options": [ { "id": "<option-id>", "public_id": "<option-public-id>", "chain_id": 12345, "token": "<token-address>", "token_decimals": 6, "family": "evm", "amount": "10500000", "address": "<option-address>", "status": "open" } ], "expires_at": "2026-10-19T09:00:00Z"}Salve o id do grupo. Cada opção já traz seu address na resposta de criação, então dê ao pagador o payment_url do grupo imediatamente; lá ele escolhe uma opção. GET /api/v1/shops/{shop_id}/issuances/{id} retorna o grupo com cada opção.
Um grupo de fatura é pago uma única vez. Seu status segue a opção que foi paga, e paid_issuance_id a identifica. Os eventos de webhook são enviados por opção e trazem group_id e group_public_id. duplicate: true significa que o grupo já foi pago por outra opção: não credite o pedido duas vezes. Um grupo de depósito mantém um endereço reutilizável por opção.
Cancele um grupo de fatura ou pause um grupo de depósito pelo id do grupo; todas as opções mudam juntas. O id de uma opção individual retorna 400 issuance_in_group.
Se uma opção não puder ser criada, nada é criado e error.details identifica a opção como {chain_id, token}. Um par vazio ou repetido, ou assets enviado junto com chain_id ou token, retorna 400 invalid_assets.
Limites
Seção intitulada “Limites”Por padrão, uma fatura pode ter no máximo 1.000.000 tokens. Um lojista pode ter até 2.000 faturas ativas e até 100.000 endereços de depósito ativos em redes EVM, 100.000 na Tron e 100 na Solana, e pode criar por hora no máximo tantos endereços de pagamento novos quanto o seu limite de faturas ativas. Cancele faturas ou desative depósitos que você não precisa mais para liberar espaço. São valores padrão: a equipe do Invoise pode definir outros limites para um lojista. Para atender mais pagadores, desative os depósitos ociosos e ative-os de novo quando precisar: um depósito desativado não conta para o limite, e reativá-lo exige um lugar livre. Um endereço desativado continua monitorado, então o dinheiro enviado a ele depois ainda é creditado e repassado. Um endereço Solana desativado que ficou uma hora sem receber nada é verificado uma vez por hora, então esse dinheiro aparece com até uma hora de atraso; não desative um endereço em que ainda espera um pagamento. Você decide quais endereços alternar; uma chave de API da loja com write também pode alterná-los. Veja Limites para os valores exatos e os códigos de erro.
Pause um depósito ou cancele uma fatura
Seção intitulada “Pause um depósito ou cancele uma fatura”| Ação | Requisição |
|---|---|
| Pausar a página de pagamento de um depósito | PATCH /api/v1/shops/{shop_id}/deposits/{id} com {"enabled":false}. Use true para ativá-la novamente. |
| Cancelar a página de pagamento de uma fatura | POST /api/v1/shops/{shop_id}/invoices/{id}/cancel. |
As duas funcionam com uma chave de API da loja com write ou com uma sessão de proprietário; envie uma Idempotency-Key salva.
Essas ações fecham a página de pagamento. Elas não reembolsam dinheiro nem interrompem o monitoramento do endereço. Fundos enviados a uma fatura cancelada ainda podem se liquidar; seus eventos trazem invoice_cancelled: true.
Fundos enviados depois que uma fatura já se liquidou são registrados como transferências tardias. Eles não são repassados automaticamente. A recuperação, incluindo a recuperação de token errado, exige uma operação manual separada.
Veja a referência da API para todos os campos de requisição e resposta.