Pagamentos com cartão na API ChargesAntigo

As APIs Charges e Tokens são APIs legadas usadas em integrações antigas da Stripe para aceitar pagamentos com cartão de débito e crédito. Nas novas integrações, use PaymentIntents.

A API Charges limita o aproveitamento de recursos da Stripe. Para usar os recursos mais avançados da Stripe, use o Stripe Checkout ou migre para a API Payment Intents.

Fluxo de pagamentos

Na maioria dos casos, a API PaymentIntents oferece mais flexibilidade e opções de integração.

Reembolsos

Para reembolsar um pagamento com a API, crie um reembolso e forneça o ID da cobrança a ser reembolsada.

curl https://api.stripe.com/v1/refunds \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d charge={{CHARGE_ID}}

Para reembolsar parte de um pagamento, forneça um parâmetro amount em forma de inteiro em centavos (ou o menor valor possível na moeda da cobrança).

curl https://api.stripe.com/v1/refunds \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d charge={{CHARGE_ID}} \
  -d amount=1000

Apple Pay

Quando o cliente aprova o pagamento, seu aplicativo recebe uma instância PKPayment com os dados do cartão criptografados, implementando os métodos de PKPaymentAuthorizationViewControllerDelegate.

1. Use o método do SDK createTokenWithPayment para transformar o PKPayment em um Token da Stripe
2. Use esse Token para criar uma cobrança.

extension CheckoutViewController: PKPaymentAuthorizationViewControllerDelegate {

    func paymentAuthorizationViewController(_ controller: PKPaymentAuthorizationViewController, didAuthorizePayment payment: PKPayment, handler: @escaping (PKPaymentAuthorizationResult) -> Void) {
        // Convert the PKPayment into a Token
        STPAPIClient.shared.createToken(withPayment: payment) { token, error in
              guard let token = token else {
                  // Handle the error
                  return
              }
            let tokenID = token.tokenId
            // Send the token identifier to your server to create a Charge...
            // If the server responds successfully, set self.paymentSucceeded to YES
        }
    }

    func paymentAuthorizationViewControllerDidFinish(_ controller: PKPaymentAuthorizationViewController) {

Descrição dinâmica no extrato

Por padrão, a descrição no extrato da sua conta Stripe aparece nos extratos do cliente sempre que você cobra o cartão. Também é possível configurar a descrição do extrato dinamicamente, em todas as solicitações de cobrança, com o argumento statement_descriptor no objeto Charge.

curl https://api.stripe.com/v1/charges \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "amount"=999 \
  -d "currency"="usd" \
  -d "description"="Example charge" \
  -d "source"="tok_visa" \
  -d "statement_descriptor"="Custom descriptor"

As descrições de extratos são limitadas a 22 caracteres, não podem usar os caracteres especiais <, >, ', " ou * e não devem consistir exclusivamente em números.

Para definir a descrição do extrato dinamicamente em cobranças em cartões de crédito e débito, a parte dinâmica é anexada ao descritor do comerciante da liquidação (separado por um * e um espaço em branco). Por exemplo, uma descrição no extrato de uma empresa chamada FreeCookies pode incluir o tipo de cookie comprado: FREECOOKIES* MORANGO.

O * e o espaço em branco são contabilizados nos 22 caracteres, e a Stripe automaticamente aloca 10 caracteres para a descrição dinâmica do extrato. Isso significa que a descrição do comerciante da liquidação pode ser truncada se tiver mais de 10 caracteres (considerando que a descrição dinâmica também tenha mais de 10 caracteres). Se a descrição dinâmica para o extrato também tiver mais de 10 caracteres, as duas serão cortadas para ficar só com 10.

Se tiver dificuldades com os limites de caracteres, crie uma descrição encurtada no Stripe Dashboard para reduzir a descrição do comerciante da liquidação. Com isso, sobra mais espaço para a descrição dinâmica. A descrição encurtada:

• Substitui a descrição do extrato do comerciante da liquidação ao usar descrições dinâmicas.
• Pode ter de 2 a 10 caracteres.

Se não souber como as descrições ficam quando são combinadas, consulte o Stripe Dashboard.

Armazenar informações em metadados

A Stripe aceita metadados nas solicitações mais comuns, como processamento de cobranças. Os metadados não aparecem para o cliente nem são usados como referência para a recusa ou bloqueio de uma cobrança no nosso sistema de prevenção de fraudes.

Com metadados, é possível associar outras informações importantes para você às atividades da Stripe. Todos os metadados ficarão visíveis no Dashboard (por exemplo: ao analisar a página de uma cobrança específica) e também ficarão disponíveis nos relatórios e exportações comuns. Por exemplo, o ID do pedido da sua loja pode ser anexado à cobrança usada para pagar esse pedido. Dessa forma, você, seu contador ou equipe de finanças poderá reconciliar facilmente as cobranças da Stripe com os pedidos no seu sistema.

Se estiver usando o Radar, considere a possibilidade de enviar outros dados do cliente e do pedido como metadados. Assim, você pode gravar regras do Radar com atributos de metadados e ter mais informações sobre o pagamento disponível no Dashboard para agilizar seu processo de revisão.

curl https://api.stripe.com/v1/charges \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "amount"=999 \
  -d "currency"="usd" \
  -d "description"="Example charge" \
  -d "source"="tok_visa" \
  -d "metadata[order_id]"=6735

Recusas

Para que a integração responda automaticamente a falhas de pagamento, você pode acessar o outcome de uma cobrança de duas formas.

• Processe o erro de API retornado quando um pagamento falha. Para pagamentos bloqueados e recusados pelo emissor do cartão, o erro inclui o ID da cobrança, que pode ser usado para acessá-la.
• Use webhooks para monitorar as atualizações de status. Por exemplo, o evento charge.failed é acionado quando um pagamento falha.