# Pagos con tarjeta en la API Charges

Aprende a cargar, guardar y autenticar tarjetas con las API heredadas de Stripe.

> #### API heredada
> 
> El contenido de esta sección se refiere a una funcionalidad *Heredada* (Technology that's no longer recommended). En su lugar, usa la [API Payment Intents](https://docs.stripe.com/payments/accept-a-payment.md).
> 
> La API Charges no admite las siguientes funcionalidades, muchas de las cuales son necesarias para cumplir con la normativa de las tarjetas de crédito:
> 
> - Empresas en la India
- [Solicitudes bancarias para autenticación de tarjetas](https://docs.stripe.com/payments/cards/overview.md)
- [Autenticación reforzada de clientes (SCA)](https://docs.stripe.com/strong-customer-authentication.md)

Las API [Charges](https://docs.stripe.com/api/charges.md) y [Tokens](https://docs.stripe.com/api/tokens.md) son API heredadas que se usaban en integraciones antiguas de Stripe para aceptar pagos con tarjetas de crédito y débito. Para integraciones nuevas, usa [PaymentIntents](https://docs.stripe.com/payments/accept-a-payment.md).

La API Charges limita tus posibilidades de aprovechar las funcionalidades de Stripe. Para obtener las funcionalidades más recientes, usa [Stripe Checkout](https://docs.stripe.com/payments/checkout.md) o [migra a la API Payment Intents](https://docs.stripe.com/payments/payment-intents/migration.md).

## Flujo de pago

En la mayoría de los casos, la API PaymentIntents es más flexible y ofrece más opciones de integración.

| API Charges                                                                                                                                                                                                                                                                                                                                                   | API Payment Intents                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 1. Recopila la información de pago del cliente en el navegador con Elements.
  1. Tokeniza la información de pago con Stripe.js.
  1. Haz una solicitud para enviar el token a tu servidor.
  1. Usa el token para crear un cargo en tu servidor con el importe y la moneda que quieras.
  1. Completa el pedido del cliente si se efectúa con éxito el pago. | 1. Crea un PaymentIntent en tu servidor con el importe y la moneda que quieras.
  1. Envía el secreto de cliente del PaymentIntent al lado del cliente.
  1. Recopila la información de pago del cliente en el navegador con Elements.
  1. Usa Stripe.js o los SDK móviles para gestionar [3D Secure](https://docs.stripe.com/payments/3d-secure/authentication-flow.md#three-ds-radar) y completar el pago del lado del cliente.
  1. Usa webhooks para completar el pedido del cliente si se efectúa con éxito el pago. |

## Rembolsos

Para rembolsar un pago a través de la API, crea un [reembolso](https://docs.stripe.com/api.md#create_refund) y proporciona el ID del cargo a rembolsar.

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

Para rembolsar parte de un pago, ingresa el parámetro `amount` en forma de un entero en centavos (o la unidad más pequeña de la moneda del cargo).

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

## Apple Pay

Cuando tu cliente aprueba el pago, tu aplicación recibe una instancia de [PKPayment](https://developer.apple.com/documentation/passkit/pkpayment) que contiene los datos de la tarjeta cifrados mediante la implementación de los métodos [PKPaymentAuthorizationViewControllerDelegate](https://developer.apple.com/documentation/passkit/pkpaymentauthorizationviewcontrollerdelegate).

1. Usa el método del SDK [createTokenWithPayment](https://stripe.dev/stripe-ios/stripe-payments/Classes/STPAPIClient.html#/c:@CM@StripePayments@StripeCore@objc\(cs\)STPAPIClient\(im\)createTokenWithPayment:completion:) para convertir `PKPayment` en un `Token` de Stripe.
1. Usa este `Token` para aceptar pagos.

#### 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...
            }
        })
    }
}
```

## Descripción dinámica del cargo en el extracto bancario

La [descripción del cargo en el extracto bancario de tu cuenta de Stripe](https://docs.stripe.com/get-started/account/activate.md#public-business-information) aparece en los extractos del cliente de forma predeterminada cada vez que haces un cargo en su tarjeta. Además, puedes configurar la descripción del cargo en el extracto bancario dinámicamente en cada solicitud de cargo con el argumento `statement_descriptor` en el objeto 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"
```

Los descriptores de instrucciones están limitados a 22 caracteres, no pueden usar los caracteres especiales `<`, `>`, `'`, `"`, o `*`, y no deben consistir únicamente en números.

Si configuras una descripción dinámica del cargo en el extracto bancario para los cargos con tarjetas de crédito y débito, la porción dinámica se agrega a la descripción del extracto del comerciante de cobro (separada por un `*` y un espacio). Por ejemplo, la descripción del cargo en el extracto bancario de una empresa llamada FreeCookies que incluya el tipo de galletitas compradas, podría ser `FREECOOKIES* CON AZÚCAR`.

El `*` y el espacio están incluidos en el límite de 22 caracteres, y Stripe asigna automáticamente 10 caracteres para la descripción dinámica. Por lo tanto, si la descripción del comerciante excede los 10 caracteres y la descripción dinámica tiene 10 caracteres o más, la descripción del comerciante aparecerá truncada. Si la descripción dinámica del cargo tiene más de 10 caracteres, ambas descripciones quedarán truncadas en el décimo carácter.

Si tienes problemas con el límite de caracteres, puedes definir una [descripción abreviada](https://dashboard.stripe.com/settings/public) en el Dashboard de Stripe para acortar la descripción del comerciante de cobro y tener más espacio para la descripción dinámica. La descripción abreviada:

- Reemplaza la descripción en el extracto bancario del comerciante de cobro ante la presencia de una descripción dinámica.
- Puede tener entre 2 y 10 caracteres.

> Si la descripción del cargo en el extracto bancario de tu cuenta tiene más de 10 caracteres, configura una [descripción abreviada](https://dashboard.stripe.com/settings/public) en el Dashboard o usa `statement_descriptor_prefix`. Esto evita que la descripción del cargo aparezca truncada de manera impredecible.

Si no estás seguro de cómo se ven las descripciones en el extracto bancario cuando se combinan, puedes revisarlas en el [Dashboard de Stripe](https://dashboard.stripe.com/settings/public).

## Cómo almacenar información en metadatos

Si usas la [API Payment Intents](https://docs.stripe.com/payments/accept-a-payment.md), recupera y actualiza solo los campos `metadata` y `description` en el objeto Payment Intent. Si usas objetos Payment Intent y objetos Charge, los valores de estos campos pueden no ser uniformes.

Stripe admite el agregado de [metadatos](https://docs.stripe.com/api.md#metadata) a las solicitudes más comunes como, por ejemplo, procesar cargos. Los metadatos no están a la vista del cliente ni determinan en forma alguna si un cargo es rechazado o bloqueado por nuestro sistema de prevención de fraudes.

Con los metadatos, puedes asociar otros datos, que sean importantes para ti, a la actividad de Stripe. Los metadatos que incluyas pueden verse en el Dashboard (por ejemplo, al buscar un cargo en particular en la página) y también aparecen en informes y exportaciones comunes. Por ejemplo, se puede asociar la ID del pedido de tu tienda al cargo utilizado para pagar ese pedido. Esto les facilita a ti, a tu contador o al equipo de finanzas la conciliación de los cargos en Stripe con los pedidos en tu sistema.

Si estás usando *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), considera la posibilidad de especificar cualquier dato adicional del cliente y del pedido en forma de metadatos. Esto te permite redactar [reglas de Radar usando atributos de metadatos](https://docs.stripe.com/radar/rules/reference.md#metadata-attributes) y contar con más información sobre el pago dentro del Dashboard, con lo cual se puede agilizar tu proceso de revisión.

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

> No almacenes información confidencial (información personal identificable, datos de tarjetas, etc.) en forma de metadatos ni en el parámetro `description` del cargo.

## Rechazos

Si quieres que tu integración responda a errores en los pagos automáticamente, puedes acceder al `outcome` de un cargo de dos maneras.

- [Gestiona el error de API](https://docs.stripe.com/api.md#error_handling) devuelto cuando falla un pago. En caso de pagos bloqueados o rechazados por el emisor de la tarjeta, el error incluye el ID del cargo, que puedes usar para [recuperarlo](https://docs.stripe.com/api.md#retrieve_charge).
- Utiliza [webhooks](https://docs.stripe.com/webhooks.md) para supervisar las actualizaciones de estado. Por ejemplo, el evento `charge.failed` se activa cuando falla un pago.