Una transacción de pago a través de pagos web comienza cuando se descubre tu app de pagos. Obtén información sobre cómo configurar una forma de pago y preparar tu app de pagos para que los comercios y clientes realicen pagos.
Para que se use con la API de Payment Request, una app de pagos debe estar asociada con un identificador de forma de pago. Los comercios que quieran integrarse en una app de pagos usarán el identificador de forma de pago para indicarlo en el navegador. En este artículo, se explica cómo funciona el descubrimiento de apps de pagos y cómo configurar tu app de pagos para que un navegador la descubra e invoque correctamente.
Si eres nuevo en el concepto de pagos web o el funcionamiento de una transacción de pago a través de apps de pago, primero lee los siguientes artículos:
Navegadores compatibles
Los pagos web constan de diferentes tecnologías y el estado de compatibilidad depende del navegador.
Cómo detecta un navegador una app de pagos
Todas las apps de pago deben proporcionar lo siguiente:
- Identificador de la forma de pago basado en URLs
- 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 forma de pago y obtiene el manifiesto de la forma de pago.
- El navegador determina la URL del manifiesto de la app web a partir del manifiesto de la forma de pago y obtiene el manifiesto de la app web.
- El navegador determina si se inicia 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 encontrarla.
Paso 1: Proporciona el identificador de la forma de pago
Un identificador de forma de pago es una string basada en URL. Por ejemplo, el identificador de Google Pay es https://google.com/pay. Los desarrolladores de apps de pago pueden elegir cualquier URL como identificador de forma de pago, siempre y cuando tengan control sobre ella y puedan entregar contenido arbitrario. En este artículo, usaremos https://bobbucks.dev/pay como el identificador de la forma de pago.
Cómo usan los comercios el identificador de forma de pago
Se construye un objeto PaymentRequest con una lista de identificadores de formas de pago que identifica las apps de pago que un comercio decide aceptar. Los identificadores de las formas de pago se establecen como un valor para la propiedad supportedMethods. Por ejemplo:
[comercio] 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 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 GET HTTP a la URL del identificador 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) |
Un array de URLs que apunta a los manifiestos de apps web donde se alojan las apps de pago. (La URL puede ser relativa). Se espera que este array haga referencia al manifiesto de desarrollo, al de producción, etcétera. |
supported_origins |
Es un array de URLs que dirigen a orígenes que pueden alojar apps de pagos de terceros que implementan la misma forma de pago. Ten en cuenta que varias apps de pagos pueden implementar una forma de pago. |
Un archivo de manifiesto de la 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 manifiestos de apps web de apps de pagos compatibles.
De manera opcional, enruta el navegador para que busque el manifiesto de la forma de pago en otra ubicación.
De manera opcional, la URL del identificador de la forma de pago puede responder con un encabezado Link que dirija a otra URL en la que el navegador puede recuperar el manifiesto de la forma de pago. Esto resulta útil cuando el manifiesto de una forma de pago está alojado en un servidor diferente o cuando un tercero entrega la app de pagos.
Configura el servidor de formas de pago para que responda con un encabezado HTTP Link con 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/payment-manifest.json, el encabezado de respuesta incluirá lo siguiente:
Link: <https://bobbucks.dev/payment-manifest.json>; rel="payment-method-manifest"
La URL puede ser un nombre de dominio completo o una ruta de acceso relativa. Inspecciona https://bobbucks.dev/pay/ en busca de tráfico de red para ver un ejemplo. También puedes usar un comando curl:
curl --include https://bobbucks.dev/pay
Paso 3: Entrega un manifiesto de app web
Un manifiesto de app web se usa para definir una app web como su nombre sugiere. Es un archivo de manifiesto muy usado para definir una app web progresiva (AWP).
El manifiesto típico de las aplicaciones 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 el manifiesto de una 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 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 |
La URL desde la que se descargará la secuencia de comandos del service worker. |
serviceworker.scope |
Es una cadena que representa una URL que define el alcance de registro de un service worker. |
serviceworker.use_cache |
La URL desde la que se descargará la secuencia de comandos del service worker. |
related_applications
|
Se usa para detectar la app que actúa como la app de pagos que proporciona el SO. Obtén más detalles en la Guía para desarrolladores de apps de pago para Android. |
prefer_related_applications
|
Se usa para determinar qué app de pagos iniciar cuando estén 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 nombre de la app de pagos, mientras que la propiedad icons se usa como el ícono de la app de pagos.
Cómo determina Chrome qué app de pagos se debe iniciar
Inicia 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 se especifica lo siguiente:- El ID del paquete y la firma de la app instalada coinciden, mientras que la versión mínima (
min_version) del manifiesto de la app web es menor o igual que la versión de la aplicación instalada.
- El ID del paquete y la firma 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 las siguientes características:
- Un filtro de intents de
org.chromium.action.PAY - Es un identificador de forma de pago que se especifica como el valor de la propiedad
org.chromium.default_payment_method_name.
- Un filtro de intents de
Consulta la guía para desarrolladores sobre apps de pago para Android a fin de 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 finalizará aquí. De lo contrario, continúa con el siguiente paso: iniciar la app de pagos basada en la Web.
Inicia 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 mediante el envío de un evento paymentrequest al service worker. No es necesario que el service worker esté registrado de antemano. Se puede registrar justo a tiempo.
Información sobre las optimizaciones especiales
Cómo los navegadores pueden omitir la IU de Payment Request e iniciar una app de pagos directamente
En Chrome, cuando se llama al método show() de PaymentRequest, la API de Payment Request muestra una IU proporcionada por el navegador denominada "IU de Payment Request". Esta IU permite que los usuarios elijan una app de pagos. Después de presionar el botón Continue 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 necesarios para que un usuario entregue un pago. Para optimizar el proceso, el navegador puede delegar la entrega de esa información a las apps de pagos e iniciar una app de pagos 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 las siguientes características:
- Admite el identificador de forma de pago solicitado.
¿Cuándo se registra una app de pagos basada en la Web justo a tiempo (JIT)?
Las apps de pago basadas en la Web se pueden iniciar sin que el usuario visite explícitamente su sitio web y no 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. Existen dos variaciones para el momento del registro:
- Si se muestra al usuario la IU de Payment Request, la app se registra justo a tiempo y se inicia cuando el usuario hace clic en Continue.
- Si se omite la IU de Payment Request, la app de pagos se registra justo a tiempo y se inicia directamente. Si omites la IU de Payment Request para iniciar una app registrada justo a tiempo, debes hacer un gesto del usuario, lo que evita el registro inesperado de service workers de origen cruzado.
Próximos pasos
Ahora que ya puedes detectar tu app de pagos, obtén información para desarrollar una app de pagos específica para cada plataforma y una app de pagos basada en la Web.