Una transacción de pago con Web Payments comienza con el descubrimiento de tu app de pagos. Obtén información para configurar una forma de pago y preparar tu app de pagos para que los comercios y los clientes realicen pagos.
Publicado: 27 de septiembre de 2017, última actualización: 1 de julio de 2025
Para usarla con la API de Payment Request, una app de pagos debe estar asociada a un identificador de forma de pago. Los comercios que deseen integrar una app de pagos usarán el identificador de la forma de pago para indicarlo al navegador. En este artículo, se explica cómo funciona el descubrimiento de apps de pago y cómo configurar tu app de pago para que un navegador la descubra y la invoque correctamente.
Si no conoces el concepto de pagos en la Web o cómo funciona una transacción de pago a través de apps de pago, primero lee los siguientes artículos:
Navegadores compatibles
Los pagos en la Web constan de varias tecnologías diferentes, y el estado de compatibilidad depende del navegador.
Cómo un navegador descubre una app de pagos
Todas las apps de pagos deben proporcionar lo siguiente:
- Identificador de la forma de pago basado en URL
- Manifiesto de la forma de pago (excepto cuando un tercero proporciona el identificador de la forma de pago)
- Manifiesto de la app web
El proceso de descubrimiento comienza cuando un comercio inicia una transacción:
- El navegador envía una solicitud a la URL del identificador de la forma de pago y recupera el manifiesto de la forma de pago.
- El navegador determina la URL del manifiesto de la app web a partir del manifiesto del método de pago y recupera el manifiesto de la app web.
- El navegador determina si debe iniciar la app de pagos del SO o la app de pagos basada en la Web desde el manifiesto de la app web.
En las siguientes secciones, se explica en detalle cómo configurar tu propia forma de pago para que los navegadores puedan detectarla.
Paso 1: Proporciona el identificador de la forma de pago
Un identificador de forma de pago es una cadena basada en URL. Por ejemplo, el identificador de Google Pay es https://google.com/pay. Los desarrolladores de apps de pagos pueden elegir cualquier URL como identificador de método de pago, siempre y cuando tengan control sobre ella y puedan publicar contenido y encabezados HTTP arbitrarios. En este artículo, usaremos https://bobbucks.dev/pay como identificador de la forma de pago.
Cómo usan los comercios el identificador de la forma de pago
Se construye un objeto PaymentRequest con una lista de identificadores de formas de pago que identifica las apps de pagos que un comercio decide aceptar. Los identificadores de la forma de pago se establecen como un valor para la propiedad supportedMethods. Por ejemplo:
[comerciante] solicita el pago:
const request = new PaymentRequest([{
supportedMethods: 'https://bobbucks.dev/pay'
}], {
total: {
label: 'total',
amount: { value: '10', currency: 'USD' }
}
});
Paso 2: Publica el manifiesto de la forma de pago
Un manifiesto de la forma de pago es un archivo JSON que define qué app de pagos puede usar esta forma de pago.
Proporciona el manifiesto de la forma de pago
Cuando un comercio inicia una transacción de pago, el navegador envía una solicitud HTTP HEAD a la URL del identificador del método de pago. La URL del identificador del método de pago responde con un encabezado HTTP Link que apunta a la URL en la que el navegador puede recuperar el manifiesto del método de pago.
Configura el servidor de la forma de pago para que responda con un encabezado HTTP Link que incluya el atributo rel="payment-method-manifest" y la URL del manifiesto de la forma de pago. Por ejemplo, si el manifiesto está en https://bobbucks.dev/pay/payment-manifest.json, el encabezado de respuesta incluiría lo siguiente:
Link: <https://bobbucks.dev/pay/payment-manifest.json>; rel="payment-method-manifest"
La URL puede ser un nombre de dominio completamente calificado o una ruta de acceso relativa. Inspecciona https://bobbucks.dev/pay para ver un ejemplo del tráfico de red. También puedes usar un comando de curl:
curl --include https://bobbucks.dev/pay
A continuación, el navegador envía una solicitud HTTP GET a la URL del manifiesto de la forma de pago. El servidor responde con el cuerpo del manifiesto de la forma de pago.
Un manifiesto de forma de pago tiene dos campos, default_applications y supported_origins.
| Nombre de la propiedad | Descripción |
|---|---|
default_applications (obligatorio) |
Es un array de URLs que dirigen a los manifiestos de las apps web en los que se alojan las apps de pago. (La URL puede ser relativa). Se espera que este array haga referencia al manifiesto de desarrollo, al manifiesto de producción, etcétera. |
supported_origins |
Es un array de URLs que apunta a orígenes que pueden alojar apps de pago de terceros que implementan la misma forma de pago. Ten en cuenta que varias apps de pago pueden implementar una forma de pago. |
Un archivo de manifiesto de forma de pago debería verse de la siguiente manera:
[controlador de pagos] /payment-manifest.json:
{
"default_applications": ["https://bobbucks.dev/manifest.json"],
"supported_origins": [
"https://alicepay.friendsofalice.example"
]
}
Cuando el navegador lee el campo default_applications, encuentra una lista de vínculos a los manifiestos de apps web de las apps de pago compatibles.
Paso 3: Publica un manifiesto de la app web
Un manifiesto de aplicación web se usa para definir una aplicación web, como lo indica su nombre. Es un archivo de manifiesto muy utilizado para definir una app web progresiva (AWP).
Un manifiesto típico de la app web se vería de la siguiente manera:
[controlador de pagos] /manifest.json:
{
"name": "Pay with Bobpay",
"short_name": "Bobpay",
"description": "This is an example of the Payment Handler API.",
"icons": [
{
"src": "images/manifest/icon-192x192.png",
"sizes": "192x192",
"type": "image/png"
},
{
"src": "images/manifest/icon-512x512.png",
"sizes": "512x512",
"type": "image/png"
}
],
"serviceworker": {
"src": "service-worker.js",
"scope": "/",
"use_cache": false
},
"start_url": "/",
"display": "standalone",
"theme_color": "#3f51b5",
"background_color": "#3f51b5",
"related_applications": [
{
"platform": "play",
"id": "com.example.android.samplepay",
"min_version": "1",
"fingerprints": [
{
"type": "sha256_cert",
"value": "4C:FC:14:C6:97:DE:66:4E:66:97:50:C0:24:CE:5F:27:00:92:EE:F3:7F:18:B3:DA:77:66:84:CD:9D:E9:D2:CB"
}
]
}
]
}
La información que se describe en un manifiesto de la app web también se usa para definir cómo aparece una app de pagos en la IU de Payment Request.
| Nombre de la propiedad | Descripción |
|---|---|
name (obligatorio)
|
Se usa como el nombre de la app de pagos. |
icons (obligatorio)
|
Se usa como el ícono de la app de pagos. Solo Chrome usa estos íconos. Otros navegadores pueden usarlos como íconos de resguardo si no los especificas como parte del instrumento de pago. |
serviceworker
|
Se usa para detectar el service worker que se ejecuta como la app de pagos basada en la Web. |
serviceworker.src |
Es la URL desde la que se descarga la secuencia de comandos del service worker. |
serviceworker.scope |
Es una cadena que representa una URL que define el alcance del registro de un trabajador de servicio. |
serviceworker.use_cache |
Es la URL desde la que se descarga la secuencia de comandos del service worker. |
related_applications
|
Se usa para detectar la app que actúa como la app de pagos proporcionada por el SO. Encuentra más detalles en la guía para desarrolladores de apps de pagos de Android. |
prefer_related_applications
|
Se usa para determinar qué app de pagos se debe iniciar cuando hay disponibles una app de pagos proporcionada por el SO y una app de pagos basada en la Web. |
La propiedad name del manifiesto de la app web se usa como el nombre de la app de pagos, y la propiedad icons se usa como el ícono de la app de pagos.
Cómo determina Chrome qué app de pagos iniciar
Cómo iniciar la app de pagos específica de la plataforma
Para iniciar la app de pagos específica de la plataforma, se deben cumplir las siguientes condiciones:
- El campo
related_applicationsse especifica en el manifiesto de la app web y cumple con las siguientes condiciones:- El ID y la firma del paquete de la app instalada coinciden, mientras que la versión mínima (
min_version) en el manifiesto de la app web es menor o igual que la versión de la aplicación instalada.
- El ID y la firma del paquete de la app instalada coinciden, mientras que la versión mínima (
- El campo
prefer_related_applicationsestrue. - La app de pagos específica de la plataforma está instalada y tiene lo siguiente:
- Es un filtro de intents de
org.chromium.action.PAY. - Es un identificador de forma de pago especificado como el valor de la propiedad
org.chromium.default_payment_method_name.
- Es un filtro de intents de
Consulta la Guía para desarrolladores de apps de pago para Android si deseas obtener más detalles sobre cómo configurarlas.
[controlador de pagos] /manifest.json
"prefer_related_applications": true,
"related_applications": [{
"platform": "play",
"id": "xyz.bobpay.app",
"min_version": "1",
"fingerprints": [{
"type": "sha256_cert",
"value": "92:5A:39:05:C5:B9:EA:BC:71:48:5F:F2:05:0A:1E:57:5F:23:40:E9:E3:87:14:EC:6D:A2:04:21:E0:FD:3B:D1"
}]
}]
Si el navegador determinó que la app de pagos específica de la plataforma está disponible, el flujo de descubrimiento finaliza aquí. De lo contrario, continúa con el siguiente paso: iniciar la app de pagos basada en la Web.
Cómo iniciar la app de pagos basada en la Web
La app de pagos basada en la Web debe especificarse en el campo serviceworker del manifiesto de la app web.
[controlador de pagos] /manifest.json:
"serviceworker": {
"src": "payment-handler.js"
}
El navegador inicia la app de pagos basada en la Web enviando un evento paymentrequest al trabajador de servicio. El trabajador de servicio no tiene que registrarse con anticipación. Se puede registrar justo a tiempo.
Información sobre las optimizaciones especiales
Cómo los navegadores pueden omitir la IU de Payment Request y lanzar directamente una app de pagos
En Chrome, cuando se llama al método show() de PaymentRequest, la API de Payment Request muestra una IU proporcionada por el navegador llamada "IU de Payment Request". Esta IU permite que los usuarios elijan una app de pagos. Después de presionar el botón Continuar en la IU de Payment Request, se inicia la app de pagos seleccionada.
Mostrar la IU de Payment Request antes de iniciar una app de pagos aumenta la cantidad de pasos que debe seguir el usuario para completar un pago. Para optimizar el proceso, el navegador puede delegar el cumplimiento de esa información a las apps de pago y lanzar una app de pago directamente sin mostrar la IU de Payment Request cuando se llama a show().
Para iniciar una app de pagos directamente, se deben cumplir las siguientes condiciones:
show()se activa con un gesto del usuario (por ejemplo, un clic del mouse).- Solo hay una app de pagos que cumple con los siguientes requisitos:
- Admite el identificador de la forma de pago solicitada.
¿Cuándo se registra una app de pagos basada en la Web de forma just-in-time (JIT)?
Las apps de pago basadas en la Web se pueden iniciar sin que el usuario visite explícitamente el sitio web de la app de pago y registre el service worker. El service worker se puede registrar justo a tiempo cuando el usuario elige pagar con la app de pagos basada en la Web. Hay dos variaciones para el momento del registro:
- Si se muestra la IU de Payment Request al usuario, la app se registra justo a tiempo y se inicia cuando el usuario hace clic en Continuar.
- Si se omite la IU de Payment Request, la app de pagos se registra justo a tiempo y se inicia directamente. Omitir la IU de Payment Request para iniciar una app registrada justo a tiempo requiere un gesto del usuario, lo que evita el registro inesperado de Service Workers de origen cruzado.
Próximos pasos
Ahora que tu app de pagos es visible, descubre cómo desarrollar una app de pagos específica para la plataforma y una app de pagos basada en la Web.