En resumen: tu aplicación o sitio web abre una URL payment://, Payment for Stripe procesa el pago y luego abre tu URL de devolución de llamada con el resultado. No se requiere SDK ni configuración del servidor. Funciona igual en iPhone y Android, con algunas diferencias que se detallan a continuación.
La referencia completa se encuentra en paymentforstripe.com/api.
Cómo funciona
- Tu aplicación abre una URL
payment://con parámetros. - Payment for Stripe abre y configura la venta. El comerciante recibe el pago mediante un lector, Tap to Pay o un comprobante de pago con tarjeta.
- Cuando finaliza, la aplicación abre la URL
callbackcon el resultado añadido como parámetros de consulta.
El comerciante debe haber iniciado sesión. Si llega un enlace mientras se está realizando otro cargo, la aplicación lo rechaza y su devolución de llamada recibe error=charge_in_progress.
Crear un cargo: payment://new
Un pago único por la cantidad que usted determine.
| Nombre | Tipo | Requerido | Descripción |
|---|---|---|---|
amount
|
entero | Sí | Cantidad en la unidad monetaria más pequeña, mayor que 0. 1000 = $10.00. |
currency
|
cadena | No | Código ISO de tres letras, como usd o eur. Si no se especifica, la aplicación utilizará la moneda que ya tenga configurada. |
description
|
cadena | No | Descripción del cargo. Codificarla en formato URL. |
customer
|
cadena | No | ID de cliente Stripe existente ( cus_…). customer_id también funciona. Cuando se configura, se ignoran email y name. |
email
|
cadena | No | Correo electrónico del cliente. Crea un nuevo cliente. |
name
|
cadena | No | Nombre del cliente. Codificarlo para URL. Crea un nuevo cliente. |
metadata
|
cadena | No | Objeto JSON codificado en URL con pares clave-valor, añadido al pago. Se aplican los límites de metadatos de Stripe. |
callback
|
cadena | No | URL que se abrirá cuando finalice la venta. |
autoprocess
|
booleano | No | true omite el teclado y comienza la carga de inmediato. Valor predeterminado false. |
auto_return
|
booleano | No | true se abre la función de devolución de llamada tan pronto como se conoce el resultado. Si es false por defecto, la función de devolución de llamada espera hasta que el comerciante cierre la pantalla de resultados. |
payment://new?amount=2500¤cy=eur&description=Coffee%20and%20pastry payment://new?amount=3500&autoprocess=true&auto_return=true&callback=myapp://payment-complete Se ignora un enlace con una amount faltante, cero o no numérica.
Crea una factura desde tu catálogo: payment://cart
El carrito se llena con los precios del catálogo de productos Stripe. El vendedor realiza el cobro como de costumbre y la venta se guarda en Stripe como una factura pagada con esos artículos. No se envía ninguna factura por correo electrónico al cliente.
| Nombre | Tipo | Requerido | Descripción |
|---|---|---|---|
prices
|
cadena | Sí | Pares price_id:quantity separados por comas, como price_abc:2,price_xyz:1. line_items también funciona. |
coupon
|
cadena | No | ID del cupón Stripe que se aplicará al carrito. |
customer
|
cadena | No | ID de cliente Stripe existente. customer_id también funciona. |
email
|
cadena | No | Correo electrónico del cliente. Crea un nuevo cliente. |
name
|
cadena | No | Nombre del cliente. Codificarlo para URL. |
metadata
|
cadena | No | Objeto JSON codificado en URL con pares clave-valor. |
callback
|
cadena | No | URL que se abrirá cuando finalice la venta. |
autoprocess
|
booleano | No | true inicia el cobro una vez que se haya cargado cada precio (y el cupón). |
auto_return
|
booleano | No | Igual que lo anterior. Valor predeterminado: false. |
payment://cart?prices=price_coffee:2,price_muffin:1&email=customer@example.com No envíes amount junto con prices. El total se obtiene de los precios, y cualquier enlace que incluya ambos se ignora. Los precios ocultos con payment_hidden siguen funcionando.
Pagar una factura existente: payment://invoice
Cobra en persona una factura abierta Stripe. El importe, la moneda, el cliente y los impuestos se obtienen de la factura. Si la transacción se realiza correctamente, la app marca la factura como pagada. Funciona en iPhone y Android.
| Nombre | Tipo | Requerido | Descripción |
|---|---|---|---|
id
|
cadena | Sí | ID de factura Stripe. Debe comenzar con in_. Enviar una factura abierta. En iPhone, primero se finaliza un borrador. En Android, se rechaza un borrador con error=invoice_state_changed. |
metadata
|
cadena | No | Objeto JSON codificado en URL, añadido al PaymentIntent. |
callback
|
cadena | No | URL que se abrirá cuando finalice la venta. Obtiene invoice_id y payment_intent_id si la venta se realiza correctamente. |
autoprocess
|
booleano | No | El true inicia el cobro una vez que se superan las comprobaciones de la factura, solo cuando se conecta un lector de tarjetas. |
auto_return
|
booleano | No | Igual que lo anterior. Valor predeterminado: false. |
payment://invoice?id=in_1ABC123xyz&autoprocess=true&callback=myapp://invoice-paid La factura establece la venta, por lo que cualquier amount, currency, customer, customer_id, email, name, description, coupon, prices o line_items hace que el enlace sea rechazado con error=invoice_invalid_param. Las facturas que están pagadas, nulas, incobrables, $0, vinculadas a una suscripción o configuradas para cobrar un método de pago predeterminado también son rechazadas, cada una con su propio error invoice_….
La devolución de llamada
La aplicación agrega estos elementos a su URL de devolución de llamada:
| Nombre | Tipo | Enviado | Descripción |
|---|---|---|---|
status
|
cadena | Siempre | success, error o cancelled. |
charge_id
|
cadena | Sobre el éxito | El ID del pago. En iPhone es el cargo Stripe ( ch_…). En Android es el PaymentIntent ( pi_…). |
stripe_charge_id
|
cadena | Solo para Android | El cargo Stripe ( ch_…). |
payment_intent_id
|
cadena | Sobre el éxito | El PaymentIntent. El iPhone lo envía solo para payment://invoice. Android lo envía para cada pago con tarjeta. |
invoice_id
|
cadena | Enlaces de facturas | La factura pagada, para payment://invoice. |
amount
|
entero | Sobre el éxito | Importe cobrado, en la unidad más pequeña. |
currency
|
cadena | Sobre el éxito | Código ISO en minúsculas. |
error
|
cadena | Por error | Un código corto como charge_in_progress o invoice_already_paid, o un mensaje legible para una tarjeta rechazada. |
myapp://payment-complete?status=success&charge_id=ch_3Qx…&success=true&amount=3500¤cy=usd&chargeId=ch_3Qx… ¿Necesitas el mismo ID en ambas plataformas? Lee primero stripe_charge_id y, si no funciona, usa charge_id.
Para integraciones más antiguas, la aplicación también envía success=true, chargeId, cancelled=true y error[message]. El nuevo código debería leer status.
Una cancelación activa la devolución de llamada inmediatamente. El éxito o el error de un cargo espera a que el comercio cierre la pantalla de resultados, a menos que se especifique auto_return=true. En iPhone, una venta en efectivo nunca activa la devolución de llamada, ya que no se realizó ningún cargo.
Codificación URL
- Codifica cada valor que tenga espacios o símbolos. Los espacios se convierten en
%20,{y}se convierten en%7By%7D,"se convierte en%22,:se convierte en%3A. - Si su URL de devolución de llamada tiene su propia cadena de consulta, codifique toda la devolución de llamada para que su
&no divida su enlacepayment://. - Las comas y los dos puntos en
pricespueden permanecer como están.
Los metadatos {"order_id":"1234","location":"Store A"} se convierten en:
payment://new?amount=10000&description=Invoice%20%231234&metadata=%7B%22order_id%22%3A%221234%22%2C%22location%22%3A%22Store%20A%22%7D El formato anterior metadata[order_id]=1234 también funciona.