Como configurar uma forma de pagamento

Uma transação de pagamento usando o Web Payments começa com a descoberta do seu app de pagamento. Saiba como configurar uma forma de pagamento e preparar seu app para que comerciantes e clientes façam pagamentos.

Eiji Kitamura

Publicado em: 27 de setembro de 2017. Última atualização: 1º de julho de 2025

Para ser usado com a API Payment Request, um app de pagamento precisa estar associado a um identificador de forma de pagamento. Os comerciantes que querem fazer a integração com um app de pagamento usam o identificador da forma de pagamento para indicar isso ao navegador. Este artigo explica como funciona a descoberta de apps de pagamento e como configurar seu app de pagamento para ser descoberto e invocado corretamente por um navegador.

Se você não conhece o conceito de pagamentos na Web ou como uma transação de pagamento funciona em apps de pagamento, leia os seguintes artigos primeiro:

• Empoderando apps de pagamento com pagamentos on-line
• Ciclo de vida de uma transação de pagamento

Suporte ao navegador

Os pagamentos na Web consistem em algumas tecnologias diferentes, e o status de suporte depende do navegador.

	Chromium		Safari		Firefox
	Computador	Android	Computador	Dispositivo móvel	Computador/dispositivo móvel
API Payment Request	✔	✔	✔	✔
API Payment Handler baseada na Web	✔	✔
App de pagamento para iOS/Android	✔	✔	✔*	✔*

Observação : *o Safari é compatível com o Apple Pay, mas não com apps de pagamento de terceiros.

Como um navegador descobre um app de pagamento

Todos os apps de pagamento precisam fornecer o seguinte:

• Identificador da forma de pagamento baseada em URL
• Manifesto da forma de pagamento (exceto quando o identificador da forma de pagamento é fornecido por terceiros)
• Manifesto do app da Web

O processo de descoberta começa quando um comerciante inicia uma transação:

1. O navegador envia uma solicitação ao URL do identificador da forma de pagamento e busca o manifesto da forma de pagamento.
2. O navegador determina o URL do manifesto do app da Web no manifesto do método de pagamento e busca o manifesto do app da Web.
3. O navegador determina se deve iniciar o app de pagamento do SO ou o app de pagamento baseado na Web do manifesto do app da Web.

As próximas seções explicam em detalhes como configurar sua própria forma de pagamento para que os navegadores possam descobri-la.

Etapa 1: fornecer o identificador da forma de pagamento

Um identificador de forma de pagamento é uma string baseada em URL. Por exemplo, o identificador do Google Pay é https://google.com/pay. Os desenvolvedores de apps de pagamento podem escolher qualquer URL como um identificador de forma de pagamento, desde que tenham controle sobre ele e possam veicular conteúdo e cabeçalhos HTTP arbitrários. Neste artigo, vamos usar https://bobbucks.dev/pay como o identificador da forma de pagamento.

Observação : os apps de pagamento também podem aceitar formas de pagamento de terceiros.

Como os comerciantes usam o identificador da forma de pagamento

Um objeto PaymentRequest é criado com uma lista de identificadores de forma de pagamento que identificam apps de pagamento que um comerciante decide aceitar. Os identificadores de forma de pagamento são definidos como um valor para a propriedade supportedMethods. Exemplo:

[comerciante] solicita pagamento:

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

Etapa 2: veicular o manifesto do método de pagamento

Um manifesto de forma de pagamento é um arquivo JSON que define qual app de pagamento pode usar essa forma de pagamento.

Forneça o manifesto da forma de pagamento

Quando um comerciante inicia uma transação de pagamento, o navegador envia uma solicitação HTTP HEAD para o URL do identificador da forma de pagamento. O URL do identificador do método de pagamento responde com um cabeçalho HTTP Link que aponta para o URL em que o navegador pode buscar o manifesto do método de pagamento.

Observação : os redirecionamentos são permitidos até três vezes no mesmo site para um identificador de forma de pagamento no Chrome.

Configure o servidor de forma de pagamento para responder com um cabeçalho HTTP Link com o atributo rel="payment-method-manifest" e o URL do manifesto da forma de pagamento. Por exemplo, se o manifesto estiver em https://bobbucks.dev/pay/payment-manifest.json, o cabeçalho de resposta vai incluir:

Link: <https://bobbucks.dev/pay/payment-manifest.json>; rel="payment-method-manifest"

O URL pode ser um nome de domínio totalmente qualificado ou um caminho relativo. Inspecione https://bobbucks.dev/pay para ver um exemplo de tráfego de rede. Você também pode usar um comando curl:

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

Observação : saiba mais sobre as práticas de formas de pagamento na documentação do W3C.

Em seguida, o navegador envia uma solicitação HTTP GET ao URL do manifesto da forma de pagamento. O servidor responde com o corpo do manifesto da forma de pagamento.

Observação: a solicitação não é necessariamente enviada ao identificador da forma de pagamento, dependendo da combinação do identificador e do navegador. Por exemplo, o Chrome não envia uma solicitação para https://play.google.com/billing e, em alguns casos, https://google.com/pay.

Um manifesto de forma de pagamento tem dois campos, default_applications e supported_origins.

Campos do manifesto da forma de pagamento

Nome da propriedade	Descrição
default_applications (obrigatório)	Uma matriz de URLs que aponta para manifestos de apps da Web em que os apps de pagamento estão hospedados. O URL pode ser relativo. É esperado que essa matriz referencie o manifesto de desenvolvimento, o manifesto de produção etc.
supported_origins	Uma matriz de URLs que apontam para origens que podem hospedar apps de pagamento de terceiros que implementam a mesma forma de pagamento. Uma forma de pagamento pode ser implementada por vários apps de pagamento.

Um arquivo de manifesto de forma de pagamento deve ter esta aparência:

[payment handler] /payment-manifest.json:

{
  "default_applications": ["https://bobbucks.dev/manifest.json"],
  "supported_origins": [
    "https://alicepay.friendsofalice.example"
  ]
}

Quando o navegador lê o campo default_applications, ele encontra uma lista de links para manifestos de apps da Web de apps de pagamento compatíveis.

Observação : o Chrome é compatível com um único app de pagamento padrão por forma de pagamento.

Etapa 3: veicular um manifesto de app da Web

Um manifesto de app da Web é usado para definir um app da Web, como o nome sugere. É um arquivo de manifesto amplamente usado para definir um Progressive Web App (PWA).

Um manifesto de app da Web típico seria assim:

[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
  },
  "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"
        }
      ]
    }
  ]
}

As informações descritas em um manifesto de app da Web também são usadas para definir como um app de pagamento aparece na interface do usuário da Solicitação de pagamento.

Campos importantes do manifesto do app da Web

Nome da propriedade	Descrição
name (obrigatório)	Usado como o nome do app de pagamento.
icons (obrigatório)	Usado como ícone do app de pagamento. Somente o Chrome usa esses ícones. Outros navegadores podem usá-los como ícones substitutos se você não os especificar como parte do instrumento de pagamento.
serviceworker	Usado para detectar o service worker que é executado como o app de pagamento baseado na Web.
serviceworker.src	O URL para fazer o download do script do service worker.
serviceworker.scope	Uma string que representa um URL que define o escopo de registro de um service worker.
serviceworker.use_cache	O URL para fazer o download do script do service worker.
related_applications	Usado para detectar o app que atua como o app de pagamento fornecido pelo SO. Encontre mais detalhes no guia do desenvolvedor de apps de pagamento do Android.
prefer_related_applications	Usado para determinar qual app de pagamento iniciar quando um app de pagamento fornecido pelo SO e um app de pagamento baseado na Web estão disponíveis.

A propriedade name do manifesto do app da Web é usada como o nome do app de pagamento, e a propriedade icons é usada como o ícone do app de pagamento.

Como o Chrome determina qual app de pagamento iniciar

Como iniciar o app de pagamento específico da plataforma

Para iniciar o app de pagamento específico da plataforma, as seguintes condições precisam ser atendidas:

• O campo related_applications é especificado no manifesto do app da Web e:
  • O ID do pacote e a assinatura do app instalado correspondem, e a versão mínima (min_version) no manifesto do app da Web é menor ou igual à versão do aplicativo instalado.
• O campo prefer_related_applications é true.
• O app de pagamento específico da plataforma está instalado e tem:
  • Um filtro de intent de org.chromium.action.PAY.
  • Um identificador de forma de pagamento especificado como o valor da propriedade org.chromium.default_payment_method_name.

Confira o guia para desenvolvedores de apps de pagamento do Android para mais detalhes sobre como configurar esses recursos.

[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"
  }]
}]

Se o navegador determinar que o app de pagamento específico da plataforma está disponível, o fluxo de descoberta será encerrado aqui. Caso contrário, ele vai para a próxima etapa, que é iniciar o app de pagamento baseado na Web.

Como iniciar o app de pagamento baseado na Web

O app de pagamento baseado na Web precisa ser especificado no campo serviceworker do manifesto do app Web.

[payment handler] /manifest.json:

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

O navegador inicia o app de pagamento baseado na Web enviando um evento paymentrequest ao service worker. O service worker não precisa ser registrado com antecedência. Ele pode ser registrado just-in-time.

Noções básicas sobre as otimizações especiais

Como os navegadores podem pular a interface do usuário da solicitação de pagamento e iniciar um app de pagamento diretamente

No Chrome, quando o método show() de PaymentRequest é chamado, a API Payment Request mostra uma interface fornecida pelo navegador chamada "Interface de solicitação de pagamento". Essa interface permite que os usuários escolham um app de pagamento. Depois de pressionar o botão Continuar na interface do Payment Request, o app de pagamento selecionado é iniciado.

A UI da solicitação de pagamento intervém antes de iniciar o app de pagamento.

Mostrar a interface do usuário da Solicitação de pagamento antes de iniciar um app de pagamento aumenta o número de etapas necessárias para que um usuário faça um pagamento. Para otimizar o processo, o navegador pode delegar o preenchimento dessas informações a apps de pagamento e iniciar um app de pagamento diretamente sem mostrar a interface do Payment Request quando show() é chamado.

Pule a UI de solicitação de pagamento e inicie o app de pagamento diretamente.

Para iniciar um app de pagamento diretamente, as seguintes condições precisam ser atendidas:

• show() é acionado com um gesto do usuário (por exemplo, um clique do mouse).
• Há apenas um app de pagamentos que:
  • Aceita o identificador da forma de pagamento solicitada.

Observação : no momento, o Safari só aceita o Apple Pay. Por isso, ele sempre inicia o app diretamente, sem passar pela interface do usuário de solicitação de pagamento.

Quando um app de pagamento baseado na Web é registrado just-in-time (JIT)?

Os apps de pagamento baseados na Web podem ser iniciados sem que o usuário visite explicitamente o site do app de pagamento e registre o service worker. O service worker pode ser registrado just-in-time quando o usuário escolhe pagar com o app de pagamento baseado na Web. Há duas variações para o tempo de registro:

• Se a interface do Payment Request for mostrada ao usuário, o app será registrado just-in-time e iniciado quando o usuário clicar em Continuar.
• Se a interface do usuário da solicitação de pagamento for ignorada, o app de pagamento será registrado just-in-time e iniciado diretamente. Para pular a interface do Payment Request e iniciar um app registrado just-in-time, é necessário um gesto do usuário, o que impede o registro inesperado de service workers de origem cruzada.

Observação : embora um único identificador de forma de pagamento possa ser compatível com vários apps de pagamento, o registro JIT só acontece quando o manifesto da forma de pagamento aponta para um único app de pagamento.

Próximas etapas

Agora que você já pode descobrir seu app de pagamento, aprenda a desenvolver um app de pagamento específico da plataforma e um app de pagamento baseado na Web.

• Apps de pagamento para Android: guia do desenvolvedor
• Guia para desenvolvedores de apps de pagamento baseados na Web