Skip to content
API para desenvolvedores

Integre e personalize

Abra o Payment for Stripe a partir do seu próprio aplicativo ou site com esquemas de URL, e controle quais produtos aparecem no aplicativo direto do painel do Stripe.
Integração com esquemas de URLDispare cobranças do seu aplicativo ou site, passe dados de clientes e trate os callbacks.Ocultar produtos com metadadosMantenha produtos exclusivos da loja online fora do aplicativo com uma única chave de metadados.
Integração com esquemas de URL

Como funciona

  1. 1Seu aplicativo abre um payment:// URL com parâmetros
  2. 2O Payment for Stripe abre e processa a transação
  3. 3Ao concluir, o aplicativo redireciona para o seu URL de retorno de chamada com o resultado.

Endpoints

Criar uma cobrança

payment://new?Processar um pagamento único com valor, moeda e descrição.

Parâmetros

  • amountintegerObrigatórioValor em centavos (ex.: 1000 = US$ 10,00)
  • currencystringCódigo ISO de moeda com três letras (padrão: a moeda atual do aplicativo)
  • descriptionstringDescrição da cobrança codificada em URL
  • customerstringAlias: customer_idID de cliente Stripe existente
  • emailstringE-mail do cliente para recebimento do recibo
  • namestringNome do cliente codificado em URL
  • metadatastringPares de chave-valor personalizados (JSON codificado em URL)
  • callbackstringURL para onde retornar após a conclusão
  • autoprocessbooleanAlias: autoIgnore a tela inicial e inicie a cobrança imediatamente.
  • auto_returnbooleanAciona a função de retorno de chamada quando o resultado é carregado, em vez de esperar que o lojista feche a caixa de diálogo de resultados. O padrão é falso.

Venda itens do seu catálogo

payment://cart?Adicione ao carrinho os preços do seu catálogo Stripe para pagamento presencial. A venda é salva como uma fatura Stripe paga. Nada é enviado ao cliente.

Parâmetros

  • pricesstringObrigatórioAlias: line_itemsIDs de preço separados por vírgulas com as respectivas quantidades (ex.: price_abc:2,price_xyz:1)
  • couponstringCódigo do cupom Stripe para aplicar ao carrinho
  • customerstringAlias: customer_idID de cliente Stripe existente
  • emailstringE-mail do cliente para recebimento do recibo
  • namestringNome do cliente codificado em URL
  • metadatastringPares de chave-valor personalizados (JSON codificado em URL)
  • callbackstringURL para onde retornar após a conclusão
  • autoprocessbooleanAlias: autoIgnore a tela inicial e inicie a cobrança imediatamente.
  • auto_returnbooleanAciona a função de retorno de chamada quando o resultado é carregado, em vez de esperar que o lojista feche a caixa de diálogo de resultados. O padrão é falso.

Pagar uma fatura existente

payment://invoice?Receba um pagamento presencial referente a uma fatura Stripe existente. O valor, a moeda, o cliente e o imposto são provenientes da fatura. Qualquer alteração nesses dados resultará em rejeição. O comerciante utiliza um leitor de cartão, o recurso " Tap to Pay ou a entrada manual de dados; em caso de sucesso, a fatura é marcada como paga fora da banda e vinculada por meio dos metadados charge_id e payment_intent_id. Faturas com assinaturas, default_payment_method ou status de paga, cancelada ou não cobrável são rejeitadas com um erro que pode ser acionado. Faturas em rascunho: o iOS as finaliza primeiro, o Android as rejeita com invoice_state_changed.

Parâmetros

  • idstringObrigatórioID da fatura Stripe (deve começar com in_)
  • callbackstringURL para a qual retornar após a conclusão. Recebe invoice_id e payment_intent_id em caso de sucesso.
  • metadatastringPares de chave-valor personalizados (JSON codificado em URL) mesclados nos metadados do PaymentIntent.
  • autoprocessbooleanAlias: autoIgnore a tela inicial e inicie a cobrança imediatamente.
  • auto_returnbooleanAciona a função de retorno de chamada quando o resultado é carregado, em vez de esperar que o lojista feche a caixa de diálogo de resultados. O padrão é falso.

Gerenciando retornos de chamada

Quando a transação for concluída, o Payment for Stripe redireciona para o seu URL de retorno de chamada com parâmetros de consulta que indicam o resultado. Por padrão, o redirecionamento é acionado depois que o lojista fecha a caixa de diálogo de resultado para que ele possa realizar ações pós-cobrança (enviar um recibo por e-mail, efetuar um reembolso). Passe `auto_return=true` para que o redirecionamento seja acionado assim que o resultado for conhecido. Compatível com iOS e Android.

Parâmetros de retorno de chamada

  • statussuccess | error | cancelledResultado da transação
  • charge_idstringID da cobrança Stripe (em caso de sucesso). O iOS envia o ID da cobrança (ch_). O Android envia o ID do PaymentIntent (pi_) e coloca o ID da cobrança em stripe_charge_id.
  • stripe_charge_idstringID de cobrança Stripe (ch_) em caso de sucesso. Somente para Android.
  • invoice_idstringID da fatura Stripe (em caso de sucesso, apenas no fluxo payment://invoice)
  • payment_intent_idstringID da intenção de pagamento Stripe (em caso de sucesso). iOS: apenas o fluxo payment://invoice. Android: a cada venda com cartão.
  • errorstringMensagem de erro (em caso de erro)
Cobrança registrada, mas a fatura não pôde ser marcada como paga: o iOS retorna status=error com charge_id, invoice_id e payment_intent_id. O Android retorna status=success com invoice_reconciliation_failed=true.Campos legados, mantidos para integrações antigas: success, amount, currency, chargeId, cancelled, error[message]. Novas integrações devem ler os campos acima.

Exemplos

  • Cobrança simples

    Cobrar US$ 10,00 informando só o valorpayment://new?amount=1000

  • Cobrança com descrição

    Cobrar € 25,00 com descriçãopayment://new?amount=2500&currency=eur&description=Coffee%20and%20pastry

  • Cobrança com novo cliente

    Cobrar US$ 50,00 e criar um registro de cliente.payment://new?amount=5000&name=John%20Smith&email=[email protected]

  • Cobrar do cliente existente

    Cobrar US$ 75,00 de um cliente Stripe existente.payment://new?amount=7500&customer=cus_ABC123xyz

  • Cobrança com metadados

    Cobrar US$ 100,00 com metadados personalizados para seus registros.payment://new?amount=10000&description=Invoice%20%231234&metadata=%7B%22order_id%22%3A%221234%22%2C%22location%22%3A%22Store%20A%22%7D

  • Processamento automático com retorno de chamada

    Ignore a tela inicial e retorne ao seu aplicativo quando terminar.payment://new?amount=3500&autoprocess=true&callback=myapp://payment-complete

  • Retorno automático com o resultado

    Dispare a função de retorno assim que o resultado for conhecido, em vez de esperar que o lojista feche a caixa de diálogo de resultados.payment://new?amount=3500&autoprocess=true&auto_return=true&callback=myapp://payment-complete

  • Carrinho com itens listados

    Cobrar por produtos do seu catálogo Stripepayment://cart?prices=price_coffee:2,price_muffin:1&email=[email protected]

  • Pagar uma fatura existente

    Recebe pagamentos presenciais referentes a uma fatura existente do Stripe. Retorna o invoice_id e o payment_intent_id em caso de sucesso.payment://invoice?id=in_1ABC123xyz&autoprocess=true&callback=myapp://invoice-paid

  • Exemplo completo

    Todos os parâmetros combinados para um fluxo totalmente integradopayment://new?amount=15000&currency=usd&description=Service%20Fee&customer=cus_ABC123xyz&metadata=%7B%22invoice%22%3A%22INV-2024-001%22%7D&autoprocess=true&callback=myapp://payment-result
Codificação de URLLembre-se de codificar caracteres especiais em URLs nos valores dos parâmetros. Espaços se tornam %20, chaves se tornam %7B e %7D.
Ocultar produtos com metadados

Ocultar produtos do aplicativo

O aplicativo lista os produtos e preços da sua conta Stripe. Para manter um deles fora do aplicativo (por exemplo, itens vendidos apenas na sua loja online), adicione esta chave de metadados ao produto ou preço no painel do Stripe:payment_hidden = true
  • Em um produto: oculta o produto e todos os seus preços.
  • Em um preço: oculta apenas esse preço.
  • Remova a chave, ou defina-a como false, para exibi-lo novamente. As alterações valem na próxima vez que o aplicativo carregar sua lista de produtos.
Links de carrinho continuam funcionandoOcultar afeta apenas a lista de produtos dentro do aplicativo. URLs payment://cart que referenciam um preço oculto continuam funcionando, e assinaturas existentes não são afetadas.

Pronto para integrar?

Baixe o aplicativo e comece a testar sua integração hoje mesmo.
Baixe gratuitamente (iOS)Contate o suporte