Uma transação que usa 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.
Um app de pagamento precisa estar associado a um identificador da forma de pagamento para ser usado com a API Payment Request. Os comerciantes que quiserem fazer a integração com um app de pagamento usarão o identificador da forma de pagamento para indicar isso ao navegador. Este artigo discute como funciona a descoberta de apps de pagamento e como configurá-los para que sejam descobertos e invocados corretamente por um navegador.
Se você é novo no conceito de pagamentos na Web ou sobre como uma transação de pagamento funciona por meio de apps de pagamento, leia os artigos a seguir primeiro:
Suporte ao navegador
O Web Payments consiste em algumas tecnologias diferentes, e o status de suporte depende do navegador.
Como um navegador descobre um app de pagamento
Todo app de pagamento precisa oferecer o seguinte:
- Identificador da forma de pagamento com base no URL
- Manifesto da forma de pagamento, a menos que o identificador da forma de pagamento seja fornecido por terceiros
- Manifesto do app da Web
O processo de descoberta começa quando um comerciante inicia uma transação:
- O navegador envia uma solicitação para o URL do identificador da forma de pagamento e busca o manifesto da forma de pagamento.
- O navegador determina o URL do manifesto do app da Web no manifesto da forma de pagamento e busca o manifesto do app da Web.
- O navegador determina se o app de pagamento do SO ou o app de pagamento baseado na Web será iniciado a partir 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 da 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 identificador da forma
de pagamento, desde que tenham controle sobre ele e possam disponibilizar conteúdo
arbitrário. Neste artigo, usaremos https://bobbucks.dev/pay como o identificador da forma de pagamento.
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 os 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 o pagamento:
const request = new PaymentRequest([{
supportedMethods: 'https://bobbucks.dev/pay'
}], {
total: {
label: 'total',
amount: { value: '10', currency: 'USD' }
}
});
Etapa 2: exibir o manifesto da forma de pagamento
Um manifesto da forma de pagamento é um arquivo JSON que define qual app de pagamento pode usar essa forma de pagamento.
Enviar o manifesto da forma de pagamento
Quando um comerciante inicia uma transação de pagamento, o navegador envia uma solicitação HTTP GET para o URL do identificador da forma de pagamento.
O servidor responde com o corpo do manifesto da forma de pagamento.
O manifesto de uma forma de pagamento tem dois campos, default_applications e
supported_origins.
| Nome da propriedade | Descrição |
|---|---|
default_applications (obrigatório) |
Uma matriz de URLs que aponta para manifestos de apps da Web em que os aplicativos de pagamento estão hospedados. (O URL pode ser um relativo). Espera-se que essa matriz faça referência ao manifesto de desenvolvimento, 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. |
O arquivo de manifesto de uma forma de pagamento tem a seguinte aparência:
[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 compatíveis.
Outra opção é direcionar o navegador para o manifesto da forma de pagamento em outro local.
O URL do identificador da forma de pagamento pode responder opcionalmente com um cabeçalho Link
que aponta para outro URL em que o navegador pode buscar o manifesto da
forma de pagamento. Isso é útil quando um manifesto de forma de pagamento está hospedado em um servidor diferente
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 o URL do manifesto
da forma de pagamento.
Por exemplo, se o manifesto estiver em https://bobbucks.dev/payment-manifest.json,
o cabeçalho de resposta incluirá:
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. Inspecione
https://bobbucks.dev/pay/ em relação ao tráfego de rede para ver um exemplo. Também é possível usar um
comando curl:
curl --include https://bobbucks.dev/pay
Etapa 3: disponibilizar um manifesto de app da Web
Um manifesto de app da Web é usado para definir um app da Web como o nome sugere. Ele é um arquivo de manifesto amplamente usado para definir um Progressive Web App (PWA).
Um manifesto típico de app da Web 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.
| 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. Somente o Chrome usa esses ícones. Outros navegadores poderão 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 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 e 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 Android. |
prefer_related_applications
|
Usado para determinar qual app de pagamento iniciar quando um app de pagamento fornecido pelo SO e um baseado na Web estiverem 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 será iniciado
Lançamento do 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, enquanto a versão mínima (
min_version) no manifesto do app da Web é menor ou igual à versão do aplicativo instalado.
- O ID do pacote e a assinatura do app instalado correspondem, enquanto a versão mínima (
- 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.
- Um filtro de intent de
Confira o Guia de pagamentos do 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 app de pagamento específico da plataforma está disponível, o fluxo de descoberta será encerrado aqui. Caso contrário, ele avança para a próxima etapa: iniciar o app de pagamento baseado na Web.
Lançamento do 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 evento paymentrequest para o service worker. O service worker não precisa ser registrado com
antecedência. Ele pode ser registrado na hora certa.
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, a API Payment Request exibe uma IU fornecida pelo navegador chamada "IU 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 da solicitação de pagamento, o app de pagamento selecionado é iniciado.
Mostrar a interface da solicitação de pagamento antes de iniciar um app de pagamento aumenta o
número de etapas necessárias para um usuário realizar um pagamento. Para otimizar o processo,
o navegador pode delegar o fulfillment dessas informações a apps de pagamento e
iniciar um deles diretamente, sem mostrar a interface da solicitação de pagamento quando
show() for chamado.
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 pagamento que:
- Oferece suporte ao identificador da forma de pagamento solicitado.
Quando um app de pagamento baseado na Web é registrado just-in-time (JIT)?
Apps de pagamento baseados na Web podem ser iniciados sem a visita explícita do usuário ao site do app de pagamento e ao registro do service worker. O service worker pode ser registrado no momento certo, quando o usuário escolhe pagar com o app de pagamento baseado na Web. Há duas variações de tempo de registro:
- Se a interface de solicitação de pagamento for exibida ao usuário, o app será registrado no momento certo e iniciado quando o usuário clicar em Continuar.
- Se a interface de solicitação de pagamento for ignorada, o app de pagamento será registrado no momento certo e iniciado diretamente. Pular a interface da solicitação de pagamento para iniciar um app registrado no momento certo requer um gesto do usuário, o que impede registros inesperados de service workers de origem cruzada.
Próximas etapas
Agora que você tem seu app de pagamento detectável, saiba como desenvolver um app de pagamento específico à plataforma e um app de pagamento baseado na Web.