Integrar com a API Invoicing
O Dashboard é o caminho mais comum para criar faturas. Se quiser automatizar a criação de faturas, você pode integrar a API. Crie uma integração completa e operacional do Invoicing usando o exemplo de integração.
Observação
Não é preciso fazer integração com a API Payments para integrar com a API Invoicing.
Configurar a Stripe
Use nossas bibliotecas oficiais para acessar a API Stripe:
Criar um produto
Para criar um produto, informe o nome dele:
Criar um preço
Preços definem o valor e a frequência da cobrança de produtos. Isso inclui o valor do produto, qual moeda utilizar e o intervalo de faturamento (quando o preço for de uma assinatura). Assim como os produtos, se você tiver poucos preços, é preferível gerenciá-los no Dashboard. Use o valor unitário para expressar preços na unidade mais baixa da moeda, nesse caso, centavos (US$ 10 é 1.000 centavos, então o valor unitário é 1000).
Observação
Se não for preciso criar um preço para seu produto, você também pode usar o parâmetro value durante a criação do item da fatura.
Para criar um preço e atribuí-lo ao produto, passe o ID, o valor unitário e a moeda do produto. Neste exemplo, o preço do produto “Gold Special” é US$ 10:
Criar um cliente
O objeto Customer representa o cliente que compra seu produto e é obrigatório para criar uma fatura. Para criar um cliente com name
, email
e description
, adicione este código, substituindo os valores pelos seus próprios valores:
Após criar o cliente, armazene o id
do cliente no seu banco de dados para usá-lo mais tarde. A próxima etapa, por exemplo, usa o ID do cliente para criar uma fatura.
Observação
Consulte Criar um cliente para ver mais parâmetros.
Criar uma fatura
Defina o atributo collection_method como send_invoice
. Para que a Stripe marque uma fatura como vencida, é preciso adicionar o parâmetro days_until_due. Quando você envia uma fatura, a Stripe a entrega ao cliente por um e-mail que inclui instruções de pagamento.
Em seguida, crie um item de fatura passando um id
de cliente, um price
de produto e um ID de fatura invoice
. Adicione itens de fatura a um único cliente por vez para evitar adicioná-los ao cliente errado.
O número máximo de itens da fatura é 250.
Se você definir auto_advance
como false
, será possível continuar modificando a fatura até finalizá-la. Para finalizar uma fatura provisória, use o Dashboard para pagá-la ou enviá-la ao cliente. Também é possível usar a API Finalize:
Observação
Se você criou a fatura por engano, anule-a. Você também pode marcar uma fatura como incobrável.
Gerenciar eventos pós-pagamento
A Stripe envia um evento invoice.paid
quando o pagamento de uma fatura é concluído. Ouça este evento para garantir um execução confiável. Se a sua integração depender apenas de um retorno de chamada no lado do cliente, o cliente poderá perder a conexão antes que o retorno de chamada seja executado, o que faria com que o cliente fosse cobrado sem que seu servidor fosse notificado. Configurar a integração para escutar eventos assíncronos também permite aceitar diferentes formas de pagamento com uma única integração.
Observação
Os pagamentos de fatura bem-sucedidos acionam os eventos invoice.paid
e invoice.payment_succeeded
. Os dois tipos de evento contêm os mesmos dados de fatura, por isso é necessário ouvir apenas um deles para receber notificação sobre pagamentos de fatura bem-sucedidos. A diferença é que os eventos invoice.payment_succeeded
são enviados em caso de pagamentos de fatura bem-sucedidos, mas não são enviados quando você marca uma fatura como paid_out_of_band. Os eventos invoice.paid
, por outro lado, são acionados em caso de pagamentos bem-sucedidos e pagamentos fora da Stripe. Como invoice.paid
cobre os dois cenários, normalmente recomendamos ouvir invoice.paid
em vez de invoice.payment_succeeded
.
Use a ferramenta de webhook do Dashboard ou siga o início rápido do webhook para receber esses eventos e executar ações, como enviar um e-mail de confirmação do pedido ao cliente, registrar a venda em um banco de dados ou iniciar um fluxo de trabalho de envio.
Além de gerenciar o evento invoice.paid
, recomendamos gerenciar dois outros eventos ao coletar pagamentos com o Payment Element:
Evento | Descrição | Ação |
---|---|---|
payment_intent.processing | Enviado quando um cliente inicia um pagamento, mas o pagamento ainda não foi concluído. Esse evento normalmente é enviado quando um débito bancário é iniciado. Ele é seguido por um evento invoice.paid ou invoice.payment_failed no futuro. | Envie ao cliente uma confirmação do pedido que indica que o pagamento está pendente. Para produtos digitais, pode ser necessário executar o pedido antes de aguardar a conclusão do pagamento. |
invoice.payment_failed | Enviado quando um cliente tenta pagar uma fatura, mas o pagamento falha. | Se um pagamento passou de processing para payment_failed , ofereça ao cliente outra tentativa para pagar. |