# [Deprecated] Pagamenti con carta nell'API Charges

Addebitare, salvare e autenticare le carte con le API Stripe precedenti

The content on this page is deprecated and is superseded by:

- [Accept a payment](https://docs.stripe.com/payments/accept-a-payment.md)
- [Build a payments page](https://docs.stripe.com/payments/checkout.md)
- [The Payment Intents API](https://docs.stripe.com/payments/payment-intents.md)

> #### Deprecated
> 
> Abbiamo deprecato l’uso dell’API Charges per creare pagamenti con carta e prevediamo di rimuoverne il supporto. Utilizza invece [Checkout](https://docs.stripe.com/payments/checkout.md) o [l’API Payment Intents](https://docs.stripe.com/payments/payment-intents.md). Le nuove integrazioni non possono utilizzare l’API Charges per creare pagamenti.
> 
> L’API Charges non supporta le seguenti funzionalità, molte delle quali sono necessarie per la conformità delle carte di credito:
> 
> - Attività in India
- [Richiesta di autenticazione della carta da parte della banca](https://docs.stripe.com/payments/cards/overview.md)
- [Autenticazione forte del cliente (SCA)](https://docs.stripe.com/strong-customer-authentication.md)

If you use the Charges API, your access to newer Stripe features is limited. To get the latest features, [migrate to the Payment Intents API](https://docs.stripe.com/payments/payment-intents/migration.md).

## Flusso di pagamento

In most cases, the Payment Intents API offers more flexibility and integration options.

| API Charges | API Payment Intents |
| --- | --- |
| 1. Acquisisci i dati di pagamento del cliente nel browser con Elements.
2. Tokenizza i dati di pagamento con Stripe.js.
3. Esegui una richiesta per inviare il token al tuo server.
4. Usa il token per creare un addebito sul tuo server con l’importo e la valuta desiderati.
5. Evadi l’ordine del cliente se il pagamento è riuscito. | 1. Crea un PaymentIntent sul tuo server con l’importo e la valuta desiderati.
2. Invia la chiave privata client di PaymentIntent al lato client.
3. Acquisisci i dati di pagamento del cliente nel browser con Elements.
4. Utilizza Stripe.js o gli SDK per dispositivi mobili per gestire l’autenticazione [3D Secure](https://docs.stripe.com/payments/3d-secure/authentication-flow.md#three-ds-radar) e completa il pagamento sul lato client.
5. Utilizza i webhook per evadere l’ordine del cliente se il pagamento è riuscito. |

## Rimborsi

Per rimborsare un pagamento tramite l’API, crea un [rimborso](https://docs.stripe.com/api.md#create_refund) e indica l’ID del pagamento da rimborsare.

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

Per effettuare un rimborso parziale di un pagamento, specifica un parametro `amount`, che deve essere un numero intero espresso in centesimi (o nell’unità più piccola della valuta di addebito).

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

## Apple Pay

Quando il cliente approva il pagamento, la tua app implementa i metodi [PKPaymentAuthorizationViewControllerDelegate](https://developer.apple.com/documentation/passkit/pkpaymentauthorizationviewcontrollerdelegate) per ricevere un’istanza di [PKPayment](https://developer.apple.com/documentation/passkit/pkpayment) contenente i dati crittografati della sua carta.

1. Usa il metodo SDK [createTokenWithPayment](https://stripe.dev/stripe-ios/stripe-payments/Classes/STPAPIClient.html#/c:@CM@StripePayments@StripeCore@objc\(cs\)STPAPIClient\(im\)createTokenWithPayment:completion:) per trasformare il `PKPayment` in un `Token` Stripe.
2. Usa questo `Token` per creare un addebito.

#### Swift

```swift
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) {
        // Dismiss payment authorization view controller
        dismiss(animated: true, completion: {
            if (self.paymentSucceeded) {
                // Show a receipt page...
            } else {
                // Present error to customer...
            }
        })
    }
}
```

## Voce di estratto conto dinamica

Per impostazione predefinita, la [voce per gli estratti conto](https://docs.stripe.com/get-started/account/set-up.md#public-business-information) del tuo account Stripe appare sugli estratti conto del cliente ogni volta che effettui un addebito sulla sua carta. Inoltre, puoi impostare la voce per gli estratti conto in modo dinamico per ogni richiesta di addebito con l’argomento `statement_descriptor` sull’oggetto Charge.

#### curl

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

Le voci di estratto conto non possono contenere più di 22 caratteri, utilizzare i caratteri speciali `<`, `>`, `'`, `"` o `*`ed essere costituite solo da numeri.

Quando imposti la voce di estratto conto in modo dinamico su pagamenti tramite carta di credito o di debito, la parte dinamica viene aggiunta alla fine della voce di estratto conto dell’esercente nominale del pagamento (separata da un asterisco `*` e da uno spazio). Ad esempio, una voce di estratto conto di un’azienda denominata FreeCookies che include il tipo di biscotto acquistato potrebbe essere `FREECOOKIES* SUGAR`.

L’asterisco (`*`) e lo spazio sono inclusi nel limite di 22 caratteri. Inoltre, Stripe destina automaticamente 10 caratteri alla voce di estratto conto dinamica. Ciò significa che, se la voce dell’esercente nominale del pagamento e la voce di estratto conto dinamica superano i 10 caratteri, la voce dell’esercente del saldo potrebbe essere troncata. Se anche la voce di estratto conto dinamica supera questo limite, entrambe le voci vengono troncate a 10 caratteri.

Se hai problemi con i limiti di caratteri, puoi impostare una [voce di estratto conto abbreviata](https://dashboard.stripe.com/settings/public) nella Dashboard Stripe per abbreviare la voce dell’esercente nominale del pagamento. Avrai così più spazio per la voce di estratto conto dinamica. La voce abbreviata:

- Sostituisce la voce di estratto conto dell’esercente nominale del pagamento quando si utilizzano voci dinamiche.
- Può contenere da 2 a 10 caratteri.

> Se la voce di estratto conto del tuo account è più lunga di 10 caratteri, imposta una [voce abbreviata](https://dashboard.stripe.com/settings/public) nella Dashboard o utilizza un `statement_descriptor_prefix`. Questo impedisce che la voce di estratto conto venga troncata in modo imprevedibile.

Se non sai che aspetto hanno le voci di estratto conto quando sono combinate, puoi controllarle nella [Dashboard Stripe](https://dashboard.stripe.com/settings/public).

## Archiviare informazioni nei metadati

If using the [Payment Intents API](https://docs.stripe.com/payments/payment-intents.md), only retrieve and update the `metadata` and `description` fields on the Payment Intent object. If using both the Payment Intent and Charge objects, you’re not guaranteed to see consistent values for these fields.

Stripe supporta l’aggiunta dei [metadati](https://docs.stripe.com/api.md#metadata) alle richieste più comuni effettuate, ad esempio l’elaborazione degli addebiti. I metadati non vengono mostrati ai clienti né considerati per determinare se un addebito deve essere o meno rifiutato o bloccato dal nostro sistema di prevenzione delle frodi.

Attraverso i metadati, puoi associare altre informazioni per te significative all’attività Stripe. Tutti i metadati che includi sono visibili nella Dashboard (ad esempio, nella pagina di un singolo addebito) e sono inoltre disponibili nei report e nelle esportazioni comuni. Ad esempio, l’ID ordine del tuo negozio può essere associato all’addebito utilizzato per pagare tale ordine. Questo consente a te, al tuo commercialista e al tuo team finanziario di riconciliare facilmente i pagamenti in Stripe con gli ordini nel tuo sistema.

Se utilizzi *Radar* (Stripe Radar helps detect and block fraud for any type of business using machine learning that trains on data across millions of global companies. It’s built into Stripe and requires no additional setup to get started), puoi specificare come metadati qualsiasi informazione aggiuntiva sui clienti e sugli ordini. In tal modo, puoi scrivere [regole Radar utilizzando gli attributi dei metadati](https://docs.stripe.com/radar/rules/reference.md#metadata-attributes) e disporre nella Dashboard di maggiori informazioni sui pagamenti, accelerando così la procedura di revisione.

#### curl

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

> Non archiviare dati sensibili (informazioni sull’identità, dettagli di carte, ecc.) come metadati o nel parametro `description` dell’addebito.

## Pagamenti rifiutati

Se desideri che la tua integrazione risponda ai pagamenti non andati a buon fine in modo automatico, puoi accedere alla proprietà `outcome` di un addebito in due modi.

- [Gestisci l’errore API](https://docs.stripe.com/api.md#error_handling) restituito con l’esito negativo di un pagamento. Per i pagamenti bloccati o rifiutati dall’emittente della carta, l’errore include l’ID di addebito, che puoi usare per [recuperare](https://docs.stripe.com/api.md#retrieve_charge) l’addebito.
- Utilizza i [webhook](https://docs.stripe.com/webhooks.md) per monitorare gli aggiornamenti di stato. Ad esempio, quando un pagamento non va a buon fine si attiva l’evento `charge.failed`.