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 instalar seu app de pagamento prontos para que comerciantes e clientes façam pagamentos.

Eiji Kitamura

Para ser usado com a API Payment Request, um app de pagamento precisa estar associado a uma identificador da forma de pagamento. Comerciantes que querem fazer a integração com um app de pagamento usará o identificador da forma de pagamento para indicar isso ao navegador. Isso artigo discute como funciona a descoberta de apps de pagamento e como configurar app de pagamento seja descoberto e invocado pelo navegador.

Se você não conhece o conceito de Web Payments ou o funcionamento de uma transação de pagamento usando apps de pagamento, leia os seguintes artigos primeiro:

• Capacitação de apps de pagamento com o Web Payments
• O ciclo de uma transação de pagamento

Suporte ao navegador

O Web Payments consiste em algumas tecnologias diferentes e o suporte depende do navegador.

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

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

Como um navegador descobre um app de pagamento

Todo app de pagamento precisa fornecer o seguinte:

• Identificador da forma de pagamento com base no URL
• manifesto da forma de pagamento (exceto quando o identificador da forma de pagamento é fornecidos por terceiros)
• Manifesto de app da Web

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

1. O navegador envia uma solicitação para a forma de pagamento identificador e buscas a forma de pagamento manifesto do app.
2. O navegador determina o app da Web manifesto do manifesto da forma de pagamento e busca o manifesto do app da Web.
3. O navegador determina se o app de pagamento do SO ou o do app de pagamento baseado na Web pelo manifesto do app.

As próximas seções explicam detalhadamente como configurar sua própria forma de pagamento para que os navegadores possam encontrá-los.

Etapa 1: fornecer o identificador da forma de pagamento

Uma forma de pagamento identificador é 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 pagamento identificador de método, desde que tenham controle sobre ele e possam atender a padrões conteúdo. Neste artigo, vamos usar https://bobbucks.dev/pay como forma de pagamento identificador.

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

Como os comerciantes usam o identificador da forma de pagamento

Um objeto PaymentRequest é criado com uma lista de formas de pagamento identificadores que identificam pagamentos apps que um comerciante decide aceitar. Os identificadores da 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' }
  }
});

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

Etapa 2: veicular o manifesto da forma de pagamento

Um manifesto de forma de pagamento é um Arquivo JSON que define qual app de pagamento pode usar esta forma de pagamento.

Fornecer o manifesto da forma de pagamento

Quando um comerciante inicia uma transação de pagamento, o navegador envia uma solicitação Solicitação GET para o URL do identificador da forma de pagamento. O servidor responde com a forma de pagamento corpo do manifesto.

O manifesto de uma 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 apontam para manifestos de apps da Web em que o pagamento aplicativos são hospedados. O URL pode ser relativo. Essa matriz é esperada para referenciar o manifesto de desenvolvimento, o manifesto de produção etc.
supported_origins	Uma matriz de URLs que apontam para origens que podem hospedar APIs apps de pagamento que implementam a mesma forma de pagamento. Um pagamento pode ser implementada por vários apps de pagamento.

Um arquivo de manifesto de forma de pagamento vai ficar assim:

[gerenciador de pagamentos] /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.

Observação : a partir do Chrome 83, o Chrome é compatível com um único app de pagamento padrão por forma de pagamento única.

Como alternativa, encaminhe o navegador para encontrar o manifesto da forma de pagamento em outro local

O URL do identificador da forma de pagamento pode responder com um cabeçalho Link. que direciona para outro URL em que o navegador pode buscar a forma de pagamento manifesto do aplicativo. Isso é útil quando um manifesto de forma de pagamento está hospedado em um ou quando o app de pagamento é disponibilizado por terceiros.

Configure o servidor da forma de pagamento para responder com um cabeçalho HTTP Link com o atributo rel="payment-method-manifest" e a forma de pagamento do manifesto.

Por exemplo, se o manifesto estiver em https://bobbucks.dev/payment-manifest.json: o cabeçalho de resposta incluiria:

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

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

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

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

Etapa 3: exibir um manifesto de app da Web

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

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

[gerenciador de pagamentos] /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 de solicitação de pagamento.

.

Campos importantes do manifesto do app da Web

Nome da propriedade	Descrição
name (obrigatório)	Usado como nome do app de pagamento.
icons (obrigatório)	Usado como ícone do app de pagamento. Apenas o Chrome usa esses ícones. outro 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 executado como o pagamento baseado na Web app.
serviceworker.src	O URL do qual fazer o download do script do service worker.
serviceworker.scope	String que representa um URL que define o escopo escopo de registro.
serviceworker.use_cache	O URL do qual 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. Veja mais detalhes em Android guia para desenvolvedores de apps de pagamento.
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 estiverem disponíveis.

Rótulo e ícone do app de pagamento.

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

Como o Chrome determina qual app de pagamento iniciar

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 do app instalado e a assinatura têm correspondência, enquanto o mínimo versão (min_version) no manifesto do app da Web é menor ou igual a a 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 os apps de pagamento para Android: guia para desenvolvedores. para mais detalhes sobre como configurá-los.

[gerenciador de pagamentos] /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 aplicativo de pagamento específico da plataforma está disponível, o o fluxo de descoberta é encerrado aqui. Caso contrário, segue para a próxima etapa. iniciando o app de pagamento baseado na Web.

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 da Web.

[gerenciador de pagamentos] /manifest.json:

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

O navegador inicia o app de pagamento baseado na Web enviando um paymentrequest. para o service worker. O service worker não precisa estar registrado avançar. Ele pode ser registrado em tempo real.

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

Como os navegadores podem pular a interface de solicitação de pagamento e iniciar um app de pagamento diretamente

No Chrome, quando o método show() de PaymentRequest é chamado, o recurso de pagamento A API Request exibe uma interface do navegador chamada "IU de solicitação de pagamento". Isso A 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 interface de solicitação de pagamento intervém antes de iniciar o app de pagamento.

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

Ignore a interface 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).
• Só há um app de pagamento que:
  • Oferece suporte ao identificador da forma de pagamento solicitada.

.

Observação : no momento, o Safari só é compatível com o Apple Pay. Por isso, ele sempre inicia o app diretamente, ignorando a interface 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 a necessidade de uma visita prévia explícita do usuário ao site do app de pagamento e registrar o service worker. O serviço worker pode ser registrado em tempo real quando o usuário optar por pagar com aplicativo de pagamento baseado na Web. Há duas variações de tempo de registro:

• Se a interface do Payment Request for mostrada ao usuário, o app estará registrado no momento certo e iniciado quando o usuário clica em Continuar.
• Se a interface do Payment Request for ignorada, o app de pagamento vai ser registrado no momento certo e lançados diretamente. Como pular a interface de solicitação de pagamento para iniciar um aplicativo registrado na hora certa exige um gesto do usuário, o que impede registro inesperado de service workers de origem cruzada.

.

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

Próximas etapas

Agora que seu app de pagamento está detectável, aprenda a desenvolver um design específico app de pagamento e um app de pagamento baseado na Web.

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