Cómo configurar una forma de pago

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.

Eiji Kitamura

Publicado el 27 de septiembre de 2017. Última actualización: 16 de octubre de 2026

Para usarse 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 con una app de pagos usarán el identificador de la forma de pago para indicárselo al 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 y la invoque correctamente.

Si no conoces los pagos web, primero lee la descripción general de los pagos web.

Tipos de apps de pagos

Una forma de pago puede ser compatible con una app de pagos para Android, una app de pagos basada en la Web o ambas:

• App de pagos para Android: Es una app instalada que Chrome inicia con un intent de Android. Chrome verifica el nombre del paquete y el certificado de firma de la app.
• App de pagos basada en la Web: Es un service worker que Chrome inicia en una ventana modal. Los usuarios no necesitan instalar nada.

Las apps de pagos para Android están disponibles en Chrome para Android y en WebView. Las apps de pagos basadas en la Web están disponibles en Chrome en todas las plataformas, pero no en WebView.

Si ambos tipos de apps están disponibles para una forma de pago y el manifiesto de tu app web establece prefer_related_applications en true, Chrome oculta tu app de pagos basada en la Web. De lo contrario, es posible que los usuarios vean ambas en la IU de Payment Request y elijan entre ellas.

Navegadores compatibles

Los pagos web constan de algunas tecnologías diferentes, y el estado de compatibilidad depende del navegador.

Cómo un navegador descubre una app de pagos

Cada app de pagos debe proporcionar lo siguiente:

• Identificador de 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:

1. 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.
2. El navegador determina la URL del manifiesto de la app web a partir del manifiesto de la forma de pago y recupera el manifiesto de la app web.
3. 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 descubrirla.

Paso 1: Proporciona el identificador de la forma de pago

Un identificador de forma de pago es una cadena basada en una 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 forma de pago, siempre que 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 las formas de pago se establecen como un valor para la propiedad supportedMethods. Por ejemplo:

[merchant] solicita el pago:

const request = new PaymentRequest([{
  supportedMethods: 'https://bobbucks.dev/pay'
}], {
  total: {
    label: 'total',
    amount: { value: '10', currency: 'USD' }
  }
});

Paso 2: Entrega 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 HTTP HEAD a la URL del identificador de la forma de pago. La URL del identificador de la forma de pago responde con un encabezado HTTP Link que apunta a la URL en la que el navegador puede recuperar el manifiesto de la forma de pago.

Configura el servidor de la forma 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/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 de tráfico de red. También puedes usar un comando curl:

curl --include https://bobbucks.dev/pay

Luego, 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.

Un archivo de manifiesto de forma de pago debería verse de la siguiente manera:

[payment handler] /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 pagos compatibles.

Paso 3: Entrega un manifiesto de la app web

Un manifiesto de app web se usa para definir una app web, como su nombre lo indica. Es un archivo de manifiesto muy usado para definir una app web progresiva (PWA).

Un manifiesto de app web típico se vería de la siguiente manera:

[payment handler] /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
  },
  "payment": {
    "supported_delegations": ["shippingAddress", "payerName", "payerEmail", "payerPhone"]
  },
  "start_url": "/",
  "display": "standalone",
  "theme_color": "#3f51b5",
  "background_color": "#3f51b5",
  "prefer_related_applications": true,
  "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"
        }
      ]
    }
  ]
}

Chrome lee diferentes campos según el tipo de app de pagos. En el caso de una app de pagos para Android, Chrome solo lee related_applications. Para una app de pagos basada en la Web, Chrome lee name, icons, serviceworker, payment y prefer_related_applications.

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

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_applications se especifica en el manifiesto de la app web y:
  • El ID del paquete y la firma 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 app instalada.
• La app de pagos específica de la plataforma está instalada y tiene lo siguiente:
  • Un filtro de intents de org.chromium.intent.action.PAY.
  • Un identificador de forma de pago especificado como el valor de la propiedad org.chromium.default_payment_method_name.

Consulta la guía para desarrolladores de apps de pagos para Android para obtener más detalles sobre cómo configurarlas.

[payment handler] /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 prefer_related_applications es true y la app de pagos específica de la plataforma está disponible, Chrome oculta la app de pagos basada en la Web. De lo contrario, Chrome también busca 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 se debe especificar en el campo serviceworker del manifiesto de la app web.

[payment handler] /manifest.json:

"serviceworker": {
  "src": "payment-handler.js"
}

El navegador inicia la app de pagos basada en la Web enviando un evento paymentrequest al service worker. No es necesario registrar el service worker con anticipación. Se puede registrar justo a tiempo.

Información sobre las optimizaciones especiales

Cómo los navegadores pueden omitir la IU de solicitud de pago y lanzar 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 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 necesita un usuario para completar un pago. Para optimizar el proceso, el navegador puede delegar la entrega de esa información a las apps de pagos y lanzar 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 condiciones:
  • Admite el identificador de la forma de pago solicitada.
  • Admite toda la información de envío y contacto que solicita el comercio.

¿Cuándo se registra una app de pagos basada en la Web justo a tiempo (JIT)?

Las apps de pagos basadas en la Web se pueden iniciar sin que el usuario visite de forma explícita el sitio web de la app de pagos 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. Existen 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.

Compila una app de pagos basada en la Web

Cuando el comercio llama a show(), Chrome envía un evento paymentrequest a tu service worker. Llama a openWindow() dentro de respondWith() para mostrar tu IU de pago y, luego, resuelve con la respuesta de pago.

Para ver la API completa, consulta la API de controlador de pagos basado en la Web en MDN.

Próximos pasos

• Guía para desarrolladores de apps de pagos para Android
• Proporciona información de envío y contacto desde una app de pagos para Android