Crea cargos a un destino

Crea cargos en la cuenta de tu plataforma, cobra comisiones y transfiere de inmediato los fondos restantes a tus cuentas conectadas.

Crea cargos a un destino cuando los clientes hacen la transacción con tu plataforma por productos o servicios suministrados por tus cuentas conectadas y transfieres fondos inmediatamente a tus cuentas conectadas. Con este tipo de cargo:

Creas un cargo en la cuenta de tu plataforma.
Determinas si el total o una parte de los fondos se transfiere a la cuenta conectada.
Se debita del saldo de tu cuenta el costo de las comisiones, los reembolsos y los contracargos de Stripe.

Este tipo de cargo es más óptimo para plataformas como Airbnb, una plataforma de alquiler de alojamientos o Lyft, una aplicación de viajes compartidos.

Los cargos a un destino solo son compatibles si tanto tu plataforma como la cuenta conectada están en el mismo país. Para que se admitan entre países, debes especificar el comerciante a cargo del cobro en la cuenta conectada con el parámetro on_behalf_of en el Payment Intent u otros escenarios de transferencias transfronterizas válidas. Recomendamos usar cargos a un destino para las cuentas conectadas que tienen acceso al Dashboard de Express o que no tienen acceso al Dashboard.

Vista previa privada

Puedes usar cargos a un destino, sin el parámetro on_behalf_of, cuando tu plataforma y la cuenta conectada estén en diferentes países de EE. UU., el Reino Unido y la Unión Europea. Para acceso anticipado, comunícate con us.

Web

iOS

Android

React Native

Para crear una integración de pagos personalizada, incorpora componentes de interfaz de usuario (IU) en tu sitio con Stripe Elements. El código del cliente y del servidor crea un formulario del proceso de compra que acepta varios métodos de pago. Comprueba cómo esta integración se compara con otros tipos de integración de Stripe.

Para ver cómo funciona Link en un usuario que regresa, introduce el correo electrónico demo@stripe.com. Para ver cómo funciona Link cuando se crea una cuenta nueva, introduce cualquier otro correo electrónico y completa el resto del formulario. En esta demostración, solo se muestra Google Pay o Apple Pay si tienes una tarjeta activa con cualquiera de las billeteras.

Esfuerzo de integración

Mismo código

Tipo de integración

Combina componentes de la interfaz de usuario en un flujo de pago personalizado

Personalización de la interfaz de usuario

Personalización a nivel CSS con la API Appearance

Primero, inscríbete para obtener una cuenta de Stripe.

Usa nuestras bibliotecas oficiales para acceder a la API de Stripe desde tu aplicación:

Crear un PaymentIntent
Lado del servidor

Stripe usa un objeto PaymentIntent para representar tu intención de cobrarle a un cliente y hace el seguimiento de los intentos de cobro y de los cambios en el estado del pago en todo el proceso.

Los métodos de pago que se les muestran a los clientes durante el proceso de compra también se incluyen en el PaymentIntent. Puedes permitir que Stripe extraiga automáticamente los métodos de pago de la configuración del Dashboard o puedes enumerarlos en forma manual.

A menos que tu integración requiera una opción basada en código para ofrecer métodos de pago, no los enumeres manualmente. Stripe evalúa la moneda, las restricciones de los métodos de pago y otros parámetros para determinar la lista de métodos de pago admitidos. Stripe les da prioridad a aquellos que aumentan la conversión y guardan mayor relación con la moneda y la ubicación del cliente. Los métodos de pago menos prioritarios se ocultan en un menú de contenido adicional.

Crea un PaymentIntent en tu servidor con un importe y una moneda habilitados. En la última versión de la API, especificar el parámetro automatic_payment_methods es opcional porque Stripe habilita su funcionalidad de forma predeterminada. Puedes administrar los métodos de pago desde el Dashboard. Stripe gestiona la devolución de los métodos de pago que cumplen con los requisitos en función de factores como el importe de la transacción, la moneda y el flujo de pagos.

Recuperar el secreto de cliente

El PaymentIntent incluye un secreto de cliente que el lado del cliente usa para completar el proceso de pago de forma segura. Puedes usar diferentes métodos para pasar el secreto del cliente al lado del cliente.

Recupera el secreto de cliente de un punto de conexión de tu servidor con la funcionalidad fetch del navegador. Este método es más conveniente si tu lado del cliente es una aplicación de una sola página, especialmente, si fue diseñada con un marco de front-end moderno como React. Crea el punto de conexión del servidor que se usa para el secreto de cliente:

Luego recupera el secreto de cliente con JavaScript del lado del cliente:

(async () => {
  const response = await fetch('/secret');
  const {client_secret: clientSecret} = await response.json();
  // Render the form using the clientSecret
})();

Recopilar datos de pago
Lado del cliente

Recopila los datos de pago del cliente con el Payment Element. Payment Element es un componente de interfaz de usuario prediseñado que simplifica la recopilación de datos de pago para una variedad de métodos de pago.

El Payment Element contiene un iframe que envía la información de pago a Stripe de manera segura a través de una conexión HTTPS. Evita colocar el Payment Element dentro de otro iframe porque algunos métodos de pago requieren redirigir a otra página para la confirmación del pago.

Si eliges usar un iframe y quieres aceptar Apple Pay o Google Pay, el iframe debe tener el atributo permitir definido en igual a "payment *"

Para que la integración funcione, la dirección de la página de finalización de compra debe empezar con https:// en lugar de http://. Puedes probar tu integración sin usar HTTPS, pero recuerda habilitarla cuando estés listo para aceptar pagos reales.

Configurar Stripe.js

El Payment Element se encuentra disponible automáticamente como funcionalidad de Stripe.js. Incluye el script de Stripe.js en tu página de finalización de compra agregándolo al head de tu archivo HTML. Siempre debes cargar Stripe.js directamente desde js.stripe.com para cumplir con la normativa PCI. No incluyas el script en un paquete ni alojes una copia en tus sistemas.

checkout.html
<head>
  <title>Checkout</title>
  <script src="https://js.stripe.com/basil/stripe.js"></script>
</head>

Crea una instancia de Stripe con el siguiente código JavaScript en tu página de pago:

checkout.js
// Set your publishable key: remember to change this to your live publishable key in production
// See your keys here: https://dashboard.stripe.com/apikeys
const stripe = Stripe('pk_test_TYooMQauvdEDq54NiTphI7jx'
);

Agrega el Payment Element a tu página de pago

El Payment Element necesita un lugar específico en tu página de pago. Crea un nodo DOM vacío (contenedor) con un ID único en tu formulario de pago:

checkout.html
<form id="payment-form">
  <div id="payment-element">
    <!-- Elements will create form elements here -->
  </div>
  <button id="submit">Submit</button>
  <div id="error-message">
    <!-- Display error message to your customers here -->
  </div>
</form>

Cuando se cargue el formulario anterior, crea una instancia de Payment Element y móntala en el nodo DOM del contenedor. Especifica el secreto de cliente del paso anterior en options cuando crees la instancia Elements:

Debes administrar el secreto de cliente con cuidado porque sirve para completar el cargo. No lo registres, no lo insertes en direcciones URL ni lo expongas a nadie que no sea el cliente.

checkout.js
const options = {
  clientSecret: '{{CLIENT_SECRET}}',
  // Fully customizable with appearance API.
  appearance: {/*...*/},
};

// Set up Stripe.js and Elements to use in checkout form, passing the client secret obtained in a previous step
const elements = stripe.elements(options);

// Create and mount the Payment Element
const paymentElementOptions = { layout: 'accordion'};
const paymentElement = elements.create('payment', paymentElementOptions);
paymentElement.mount('#payment-element');

El Payment Element renderiza un formulario dinámico que le permite a tu cliente elegir un método de pago. Para cada método de pago, el formulario le pide automáticamente al cliente que complete todos los datos de pago necesarios.

Personaliza el aspecto

Personaliza el Payment Element para que coincida con el diseño de tu sitio especificando el objeto appearance en options al crear el proveedor Elements.

Recopila las direcciones

De forma predeterminada, el Payment Element solo recopila los datos necesarios de la dirección de facturación. Para recopilar la dirección de facturación completa de un cliente (por ejemplo, para calcular el impuesto sobre bienes y servicios digitales) o la dirección de envío, usa el Address Element.

Solicita un token de comerciante de Apple Pay

Si configuraste tu integración para aceptar pagos de Apple Pay, te recomendamos que configures la interfaz de Apple Pay para devolver un token de comerciante a fin de habilitar las transacciones iniciadas por el comerciante (MIT). Solicita el tipo de token de comerciante correspondiente en el Payment Element.

Enviar el pago a Stripe
Lado del cliente

Usa stripe.confirmPayment para completar el pago con los datos del Payment Element. Proporciona una return_url a esta función para indicar a dónde Stripe debe redirigir al usuario después de completar el pago. Es posible que primero se redirija al usuario a un sitio intermedio, como una página de autorización del banco y, luego, a lareturn_url. Los pagos con tarjeta redirigen inmediatamente a la return_url cuando un pago se realiza correctamente.

Si no quieres realizar el redireccionamiento de pagos con tarjeta una vez que se completan los pagos, puedes configurar el redireccionamiento en if_required. Esto solo redirigirá a los clientes que finalizan su compra con métodos de pago basados en redireccionamiento.

checkout.js
const form = document.getElementById('payment-form');

form.addEventListener('submit', async (event) => {
  event.preventDefault();

  const {error} = await stripe.confirmPayment({
    //`Elements` instance that was used to create the Payment Element
    elements,
    confirmParams: {
      return_url: 'https://example.com/order/123/complete',
    },
  });

  if (error) {
    // This point will only be reached if there is an immediate error when
    // confirming the payment. Show error to your customer (for example, payment
    // details incomplete)
    const messageContainer = document.querySelector('#error-message');
    messageContainer.textContent = error.message;
  } else {
    // Your customer will be redirected to your `return_url`. For some payment
    // methods like iDEAL, your customer will be redirected to an intermediate
    // site first to authorize the payment, then redirected to the `return_url`.
  }
});

Asegúrate de que la return_url corresponda a una página de tu sitio web que proporcione el estado del pago. Cuando Stripe redirige al cliente a la return_url, proporcionamos los siguientes parámetros de consulta de URL:

Parámetro	Descripción
`payment_intent`	El identificador único del `PaymentIntent`.
`payment_intent_client_secret`	El secreto de cliente del objeto `PaymentIntent`.

Precaución

Si tienes herramientas que rastrean la sesión del navegador del cliente, es posible que debas agregar el dominio stripe.com a la lista de exclusión de referentes. Los redireccionamientos hacen que algunas herramientas creen nuevas sesiones, lo que te impide realizar un seguimiento de la sesión completa.

Usa uno de los parámetros de consulta para recuperar el PaymentIntent. Examina el estado del PaymentIntent para decidir qué mostrarás a tus clientes. También puedes adjuntar tus propios parámetros de consulta cuando proporciones la return_url, que se mantendrán durante el proceso de redireccionamiento.

status.js
// Initialize Stripe.js using your publishable key
const stripe = Stripe('pk_test_TYooMQauvdEDq54NiTphI7jx'
);

// Retrieve the "payment_intent_client_secret" query parameter appended to
// your return_url by Stripe.js
const clientSecret = new URLSearchParams(window.location.search).get(
  'payment_intent_client_secret'
);

// Retrieve the PaymentIntent
stripe.retrievePaymentIntent(clientSecret).then(({paymentIntent}) => {
  const message = document.querySelector('#message')

  // Inspect the PaymentIntent `status` to indicate the status of the payment
  // to your customer.
  //
  // Some payment methods will [immediately succeed or fail][0] upon
  // confirmation, while others will first enter a `processing` state.
  //
  // [0]: https://stripe.com/docs/payments/payment-methods#payment-notification
  switch (paymentIntent.status) {
    case 'succeeded':
      message.innerText = 'Success! Payment received.';
      break;

    case 'processing':
      message.innerText = "Payment processing. We'll update you when payment is received.";
      break;

    case 'requires_payment_method':
      message.innerText = 'Payment failed. Please try another payment method.';
      // Redirect your user back to your payment page to attempt collecting
      // payment again
      break;

    default:
      message.innerText = 'Something went wrong.';
      break;
  }
});

Administrar eventos posteriores al pago
Lado del servidor

Stripe envía un evento payment_intent.succeeded cuando se completa el pago. Usa la herramienta de webhook del Dashboard o sigue la guía de webhooks para recibir estos eventos y ejecutar acciones como, por ejemplo, enviar un correo electrónico de confirmación del pedido a tu cliente, registrar la venta en una base de datos o iniciar un flujo de envío.

Escucha estos eventos en lugar de esperar una devolución de llamada del cliente. De su lado, el cliente puede cerrar la ventana del navegador o salir de la aplicación antes de que se ejecute la devolución de llamada, y clientes malintencionados podrían manipular la respuesta. Si configuras tu integración para escuchar eventos asincrónicos, podrás aceptar diferentes tipos de métodos de pago con una sola integración.

Además de administrar el evento payment_intent.succeeded, recomendamos administrar estos otros eventos si se cobran pagos con el Payment Element:

Evento	Descripción	Acción
payment_intent.succeeded	Se envía cuando un cliente completa correctamente un pago.	Envía al cliente una confirmación del pedido y completa el pedido.
payment_intent.processing	Se envía cuando un cliente inicia con éxito un pago, pero éste aún no se completó. Este evento se envía normalmente cuando el cliente inicia un débito bancario. Le sigue un evento `payment_intent.succeeded` o `payment_intent.payment_failed` en el futuro.	Envía al cliente una confirmación del pedido que indique que el pago está pendiente. En caso de productos digitales, quizá te convenga completar el pedido antes de esperar que se complete el pago.
payment_intent.payment_failed	Enviado cuando un cliente intenta un pago, pero el pago falla.	Si un pago pasa de `processing` a `payment_failed`, ofrécele al cliente otro intento de pago.

Probar la integración

Número de tarjeta	Escenario	Cómo hacer la prueba
	El pago con tarjeta se efectúa correctamente y no requiere autenticación.	Completa el formulario de tarjeta de crédito con el número de tarjeta de crédito y la fecha de vencimiento, el CVC o el código postal.
	El pago con tarjeta requiere autenticación.	Completa el formulario de tarjeta de crédito con el número de tarjeta de crédito y la fecha de vencimiento, el CVC o el código postal.
	La tarjeta es rechazada con un código de rechazo `insufficient_funds`.	Completa el formulario de tarjeta de crédito con el número de tarjeta de crédito y la fecha de vencimiento, el CVC o el código postal.
	La tarjeta UnionPay puede tener entre 13 y 19 dígitos.	Completa el formulario de tarjeta de crédito con el número de tarjeta de crédito y la fecha de vencimiento, el CVC o el código postal.

Consulta Pruebas para obtener información adicional para probar tu integración.

OpcionalHabilitar métodos de pago adicionales

Cobra comisiones

Cuando se procesa un pago, en lugar de transferir el importe total de la transacción a una cuenta conectada, tu plataforma puede decidir tomar una parte del importe de la transacción en forma de comisiones. Puedes establecer el precio de las comisiones de dos maneras diferentes:

Utiliza la herramienta de tarifas de la plataforma para establecer y probar las reglas de comisiones de la plataforma. Esta función que no requiere programación del Dashboard de Stripe solo está disponible actualmente para plataformas responsables de pagar las comisiones de Stripe.
Establece tus reglas de tarifas internamente, especificando las comisiones directamente en un PaymentIntent utilizando el parámetro application_fee_amount o transfer_data[amount]. Las comisiones establecidas con este método anulan la lógica de tarifas especificada en la herramienta de tarifas de la plataforma.

Cuando se crean cargos con application_fee_amount, el importe total del cargo se transfiere de inmediato de la plataforma a la cuenta transfer_data[destination] después de la captura del cargo. El application_fee_amount (que no puede superar el importe total del cargo) se transfiere de nuevo a la plataforma.

Una vez cobrada la comisión de la aplicación, se crea un objeto Application Fee. Puedes ver una lista de las comisiones de la plataforma en el Dashboard, con las comisiones de la plataforma o en Sigma. También puedes usar la propiedad amount en el objeto Application Fee para elaborar informes detallados de comisiones.

Si usas un application_fee_amount, ten en cuenta que:

El application_fee_amount no puede superar el importe total de la transacción.
El application_fee_amount siempre se calcula en la misma moneda que la transacción.
The application fee settles in the same currency as the connected account’s settlement currency. For cross-border destination charges, this might differ from your platform’s settlement currency.
Tu plataforma paga la comisión de Stripe después de que se transfiere el application_fee_amount a tu cuenta.
No se aplican comisiones adicionales de Stripe al importe.
Tu plataforma puede usar la medición, notificación y verificación de comisiones de la plataforma incorporadas para conciliar las comisiones cobradas.
En los dashboards o componentes alojados en Stripe, como el componente Datos de pago, tu cuenta conectada puede ver tanto el importe total como el importe de la comisión de la plataforma.

Flujo de fondos

Con el código anterior, el importe total del cargo (USD 10.00) se agrega al saldo pendiente de la cuenta conectada. El application_fee_amount (USD 1.23) se deduce del importe del cargo y se transfiere a tu plataforma. Las comisiones de Stripe (USD 0.59) se deducen del saldo de la cuenta de tu plataforma. El importe de la comisión de la plataforma menos las comisiones de Stripe (USD 1.23 − USD 0.59 = USD 0.64) permanece en el saldo de la cuenta de tu plataforma.

El application_fee_amount estará a disposición de la cuenta de la plataforma conforme a su calendario habitual de transferencias, como si se tratara de fondos de cualquier otro cargo de Stripe.

Especifica el comerciante a cargo del cobro

El comerciante a cargo del cobro depende de las funcionalidades activas en una cuenta y de cómo se crea el cargo. El comerciante a cargo del cobro determina de quién es la información utilizada para efectuar el cargo. Esto incluye la descripción del cargo (ya sea de la plataforma o de la cuenta conectada) que aparecerá para ese cargo en el extracto bancario o de tarjeta de crédito del cliente.

Si especificas el comerciante a cargo del cobro, puedes ser más explícito sobre quién es el destinatario del cargo. Por ejemplo, algunas plataformas prefieren ser el comerciante a cargo del cobro porque el usuario final interactúa directamente con ellas, como es el caso de las plataformas on-demand. No obstante, algunas plataformas tienen cuentas conectadas que interactúan directamente con los consumidores finales (por ejemplo, las tiendas físicas de una plataforma de e-commerce). En estos casos, es más lógico que el comerciante a cargo del cobro sea la cuenta conectada.

Puedes establecer el parámetro on_behalf_of en el ID de una cuenta conectada para que esa cuenta sea el comerciante a cargo del cobro. Cuando se usa on_behalf_of:

Los cargos se liquidan en el país y la moneda de cobro de la cuenta conectada.
Se utiliza la estructura de comisiones del país de la cuenta conectada.
La descripción del cargo en el extracto bancario de la cuenta conectada se muestra en el extracto de la tarjeta de crédito del cliente.
Si la cuenta conectada está en un país diferente al de la plataforma, la dirección y el número de teléfono de la cuenta conectada se muestran en el extracto de la tarjeta de crédito del cliente.
La cantidad de días durante la que se retiene el saldo pendiente antes de pagar depende de la configuración del delay_days en la cuenta conectada.

Si se omite on_behalf_of, la plataforma es la empresa registrada para el pago.

Precaución

El parámetro on_behalf_of solo se admite para cuentas conectadas con una funcionalidad de pagos como card_payments. Las cuentas regidas por el Contrato de servicios del destinatario no pueden solicitar card_payments u otras funcionalidades de pago.

Emitir reembolsos

Si usas la API Payment Intents, los reembolsos deben emitirse por el último cargo creado.

Los cargos creados en la cuenta de la plataforma se pueden rembolsar usando la clave secreta de la cuenta de la plataforma. Cuando se rembolsa un cargo con un transfer_data[destination], de manera predeterminada, la cuenta de destino conserva los fondos transferidos y deja que la cuenta de la plataforma cubra el saldo negativo del rembolso. Para retirar los fondos de la cuenta conectada para cubrir el rembolso, establece el parámetro reverse_transfer en true al crear el rembolso:

De forma predeterminada, se rembolsa el cargo total, pero puedes crear un rembolso parcial definiendo el valor de amount con un número entero positivo.

Si el rembolso implica que se devuelve el total del cargo, se revierte el total de la transferencia. De lo contrario, se revierte un importe proporcional de la transferencia.

Reembolsar comisiones de la plataforma

Cuando se reembolsa un cargo con una comisión de la plataforma, de manera predeterminada, la cuenta de la plataforma conserva los fondos de la comisión. Para volver a enviar los fondos de la comisión de la plataforma a la cuenta conectada, establece el parámetro refund_application_fee en true al crear el reembolso:

Ten en cuenta que si rembolsas la comisión de la aplicación para un cargo a un Destino, también debes revertir la transferencia. Si el rembolso implica que se devuelve el total del cargo, también se rembolsa el total de la comisión. De lo contrario, se rembolsa un importe proporcional de la comisión.

Como alternativa, puedes especificar un valor false para refund_application_fee y reembolsar la comisión de la plataforma por separado a través de la API.

Reembolsos fallidos

Si un reembolso falla, o lo cancelas, el monto del reembolso fallido regresa al saldo de Stripe de tu cuenta de plataforma. Crea un envío de fondos para transferir los fondos a la cuenta conectada, según sea necesario.

Gestionar disputas

En el caso de los cargos de destino, con o sin on_behalf_of, Stripe debita los montos de las disputas y las comisiones de tu cuenta de la plataforma.

Te recomendamos configurar un webhook para recibir notificaciones de los eventos creados por la disputa. Cuando eso sucede, puedes intentar recuperar los fondos de la cuenta conectada revirtiendo la transferencia a través del Dashboard o creando una revocación de transferencia.

Si la cuenta conectada tiene un saldo negativo, Stripe intenta debitar de su cuenta externa si debit_negative_balances se establece en true.

Si impugnas la disputa y esta se resuelve a tu favor, puedes volver a transferir los fondos que revertiste previamente a la cuenta conectada. Si tu plataforma tiene un saldo insuficiente, la transferencia falla. Para evitar errores por saldo insuficiente, agrega fondos a tu saldo de Stripe.

Errores habituales

La retransferencia de una revocación anterior está sujeta a restricciones de transferencia transfronteriza, lo que significa que es posible que no tengas medios para pagar tu cuenta conectada. Por el contrario, espera para recuperar transferencias de pagos transfronterizas disputadas por cargos a un destino con on_behalf_of hasta después de perder la disputa.

Crea cargos a un destino

Crea cargos en la cuenta de tu plataforma, cobra comisiones y transfiere de inmediato los fondos restantes a tus cuentas conectadas.

Vista previa privada

Esfuerzo de integración

Tipo de integración

Personalización de la interfaz de usuario

Crear un PaymentIntentLado del servidor

Recuperar el secreto de cliente

Recopilar datos de pagoLado del cliente

Configurar Stripe.js

Agrega el Payment Element a tu página de pago

Personaliza el aspecto

Recopila las direcciones

Solicita un token de comerciante de Apple Pay

Enviar el pago a StripeLado del cliente

Precaución

Administrar eventos posteriores al pagoLado del servidor

Probar la integración

OpcionalHabilitar métodos de pago adicionales

Cobra comisiones

Flujo de fondos

Especifica el comerciante a cargo del cobro

Precaución

Emitir reembolsos

Reembolsar comisiones de la plataforma

Reembolsos fallidos

Gestionar disputas

Errores habituales

Consulta también

Crear un PaymentIntent
Lado del servidor

Recopilar datos de pago
Lado del cliente

Enviar el pago a Stripe
Lado del cliente

Administrar eventos posteriores al pago
Lado del servidor