Integrar con la API Invoicing

Aprende a crear y enviar una factura con código.

El Dashboard es la vía más habitual para crear facturas. Si quieres automatizar este proceso, puedes hacer la integración con la API. Diseña una integración completa y funcional con Invoicing siguiendo nuestro modelo de integración.

Nota

No es necesario que te integres con la API Payments para integrarte con la API Invoicing.

Configurar Stripe

Usa nuestras bibliotecas oficiales para acceder a la API de Stripe:

Crear un producto

Para crear un producto, ingresa su nombre:

Crear un precio

Precios define cuánto cobrar por los productos y con qué frecuencia. Esto incluye cuánto cuesta el producto, qué moneda usar y el intervalo de facturación (cuando el precio es de una suscripción). Al igual que sucede con los productos, si tienes pocos precios, es preferible gestionarlos en el Dashboard. Usa el importe unitario para expresar los precios en la unidad más baja de la moneda, en este caso, centavos (USD 10 son 1,000 centavos, por lo que el importe unitario es 1000).

Nota

Como alternativa, si no necesitas crear un precio para tu producto, puedes usar el parámetro amount durante la creación de la partida de factura.

Para crear el precio y asignarlo al producto, especifica el ID de producto, el importe unitario y la moneda. En el siguiente ejemplo, el precio del producto “Gold Special“ es de USD 10:

Crear un cliente

El objeto Customer representa al cliente que compra el producto y es necesario para generar la factura. Para crear un cliente con name, email y description, agrega el siguiente código y reemplaza los valores por los que correspondan:

Después de crear el cliente, guarda su id en tu base de datos para poder usarlo después. En el próximo paso, por ejemplo, el ID del cliente se utiliza para crear una factura.

Nota

Busca los parámetros adicionales en Crear un cliente.

Crear una factura

Establece el atributo collection_method en send_invoice. Para que Stripe marque una factura como vencida, debes agregar el parámetro days_until_due. Cuando envías una factura, Stripe se la envía al cliente por correo electrónico junto con las instrucciones de pago.

A continuación, debes crear un ítem de factura indicando el id del cliente, el price del producto y la invoice del ID de la factura.

La cantidad máxima de ítems de factura es 250.

Si estableces auto_advance en false, puedes seguir modificando la factura hasta su finalización. Para finalizar una factura en borrador, usa el Dashboard, envíasela al cliente o págala. También puedes utilizar la API Finalize:

Nota

Si creaste la factura por error, puedes anularla. También puedes marcar una factura como incobrable.

Aceptar pago con factura

Cuando se finaliza la factura, se genera un PaymentIntent y se asocia con la factura. Usa Stripe Elements para recopilar los datos de pago y confirmar el PaymentIntent de la factura.

Nota

No puedes editar los valores monetarios ni el parámetro collection_method una vez finalizada una factura. Esta restricción también se aplica al PaymentIntent de la factura finalizada. Cuando actualizas el PaymentIntent de una factura con una llamada a update, solo puedes modificar los parámetros setup_future_usage, metadata, payment_method, description, receipt_email, payment_method_data, payment_method_options y shipping.

El Payment Element recopila de forma segura todos los datos de pago necesarios para diferentes métodos de pago. Consulta el Soporte para métodos de pago y productos para determinar si los métodos de pago configurados son compatibles tanto con Invoicing como con Payment Element.

Cómo especificar el secreto de cliente en el front-end

Stripe.js utiliza el client_secret del PaymentIntent para completar el proceso de pago de forma segura. Obtén el secreto de cliente de la factura mediante la expansión de su atributo confirmation_secret, cuando finalices la factura o cuando hagas otra llamada de API, como recuperar o actualizar, en la factura después de finalizarla. Devuelve el client_secret al front-end para completar el pago.

Después de devolver la factura, accede al secreto de cliente en el campo confirmation_secret expandido.

Configurar Stripe Elements

El Payment Element se encuentra disponible automáticamente como función de Stripe.js. Incluye el script Stripe.js en tu página de finalización de compra agregándolo al head de tu archivo HTML. Carga siempre 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.

pay-invoice.html
<head>
  <title>Pay Invoice</title>
  <script src="https://js.stripe.com/basil/stripe.js"></script>
</head>

Crea una instancia de Stripe con el siguiente JavaScript en tu página de finalización de compra:

pay-invoice.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'
);

Agregar el Payment Element a tu página

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

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

Cuando se cargue el formulario, crea una instancia de Payment Element y móntala en el nodo DOM del contenedor. Especifica el secreto de cliente de PaymentIntent como una opción al crear una instancia de Elements.

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

// Set up Stripe.js and Elements to use in your checkout form, passing in the client secret.
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');

Payment Element renderiza un formulario dinámico que le permite a tu cliente elegir un método de pago. El formulario recopila automáticamente todos los datos de pago necesarios correspondientes al método de pago seleccionado por el cliente.

Puedes personalizar el Payment Element para que combine con el diseño de tu sitio especificando el objeto appearance en options al crear una instancia de Elements.

Completar pago

Utiliza stripe.confirmPayment para completar el pago con los detalles del Payment Element. Esto crea un método de pago y confirma el Payment Intent de la factura, lo que genera un cargo. Si se requiere autenticación reforzada de clientes (SCA) para el pago, el Payment Element se encarga del proceso de autenticación antes de confirmar el Payment Intent.

Proporciona una return_url a la función confirmPayment para indicar a dónde redirige Stripe al usuario después de completar el pago. Tu usuario puede ser redirigido primero a un sitio intermedio, como una página de autorización bancaria, antes de ser redirigido a la return_url. Los pagos con tarjeta redirigen inmediatamente a la return_url cuando un pago se realiza correctamente.

pay-invoice.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`.
  }
});

Cuando tu cliente envía un pago, Stripe lo redirige a return_url e incluye los siguientes parámetros de consulta de URL. La página de retorno puede usarlos para obtener el estado del PaymentIntent a fin de mostrarle el estado del pago al cliente.

Cuando especificas la return_url, también puedes adjuntar tus propios parámetros de consulta para usarlos en la página de retorno.

Parámetro	Descripción
`payment_intent`	El identificador único del `PaymentIntent`.
`payment_intent_client_secret`	El secreto de cliente del objeto `PaymentIntent`. Para las integraciones de suscripciones, este client_secret también se expone en el objeto `Invoice` a través de `confirmation_secret`

Cuando el cliente es redirigido a tu sitio, puedes usar el payment_intent_client_secret para consultar el PaymentIntent y mostrarle el estado de la transacción a tu cliente.

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 el parámetro de consulta payment_intent_client_secret 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;
  }
});

Gestionar eventos posteriores al pago

Stripe envía un evento invoice.paid cuando se completa el pago de una factura. Escucha este evento para garantizar un cumplimiento confiable. Si su integración se basa solo en una devolución de llamada del lado del cliente, el cliente podría perder la conexión antes de que se ejecute la devolución de llamada, lo que provocaría que se le cobre al cliente sin notificar a tu servidor. Si configuras tu integración para escuchar eventos asincrónicos, también podrás aceptar diferentes tipos de métodos de pago con una sola integración.

Nota

Los pagos de facturas exitosos activan tanto un evento invoice.paid como invoice.payment_succeeded. Ambos tipos de eventos contienen los mismos datos de factura, por lo que solo es necesario escuchar a uno de ellos para recibir una notificación de pagos de facturas exitosos. La diferencia es que los eventos invoice.payment_succeeded se envían para pagos de facturas exitosos, pero no se envían cuando marcas una factura como paid_out_of_band. Por otro lado, los eventos invoice.paid se activan tanto para pagos exitosos como para pagos fuera de banda. Debido a que invoice.paid cubre ambas opciones, generalmente recomendamos escuchar invoice.paid en lugar de invoice.payment_succeeded.

Utiliza la herramienta webhook del Dashboard o sigue el inicio rápido del webhook 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.

Además de administrar el evento invoice.paid, recomendamos administrar otros dos eventos si se cobran pagos con el Payment Element:

Evento	Descripción	cliente
payment_intent.processing	Se envía cuando el cliente inició correctamente el pago, pero el pago aún no se ha completado. Este evento se envía con mayor frecuencia cuando se inicia un débito bancario. Más adelante, lo sigue un evento `invoice.paid` o `invoice.payment_failed`.	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.
invoice.payment_failed	Se envía cuando el cliente intentó pagar una factura, pero el pago falló.	Si un pago pasó de `processing` a `payment_failed`, ofrécele al cliente otro intento de pago.

Integrar con la API Invoicing

Aprende a crear y enviar una factura con código.

Nota

Configurar Stripe

Crear un producto

Crear un precio

Nota

Crear un cliente

Nota

Crear una factura

Nota

Aceptar pago con factura

Nota

Cómo especificar el secreto de cliente en el front-end

Configurar Stripe Elements

Agregar el Payment Element a tu página

Completar pago

Precaución

Gestionar eventos posteriores al pago

Nota

OpcionalPersonalizar una factura

Consulta también