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

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.

A resposta é 202 Accepted. Salve o id dela e consulte repetidamente o endpoint de issuance até que address esteja disponível. Depois dê ao pagador o payment_url retornado.

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

Uma fatura permanece aberta por 30 dias por padrão. Para escolher outra vida útil, adicione expires_in ao corpo da requisição, por exemplo "expires_in":"7d". Os valores permitidos são 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.

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

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. Aguarde o endereço da mesma forma que 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.

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": "registering",
  "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": null,
      "status": "registering"
    }
  ],
  "expires_at": "2026-10-19T09:00:00Z"
}

Salve o id do grupo. GET /api/v1/shops/{shop_id}/issuances/{id} retorna o grupo com cada opção; consulte repetidamente até que as opções tenham endereços, depois dê ao pagador o payment_url do grupo, onde ele escolhe uma 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

Uma fatura pode ter no máximo 1.000.000 tokens. Um lojista pode ter até 2.000 faturas ativas e um número limitado de endereços de depósito ativos por família de rede. Cancele faturas ou desative depósitos que você não precisa mais para liberar espaço. Veja Limites para os valores exatos e os códigos de erro.

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`.

Envie autenticação e uma Idempotency-Key salva para qualquer uma das operações.

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.