Mudanças na API Payment Request

Eiji Kitamura

Chrome 62

O PaymentDetailsModifier já está disponível

Em uma solicitação de pagamento, há casos em que você quer oferecer um desconto ou uma cobrança extra, dependendo da forma de pagamento escolhida pelo cliente. PaymentDetailsModifier é o recurso que você pode usar para isso.

Adicione a propriedade modifiers ao segundo argumento do construtor PaymentRequest com uma matriz do objeto PaymentDetailsModifier, que são regras declarativas de como os itens de exibição e o total devem ser modificados dependendo da forma de pagamento escolhida pelo cliente.

O exemplo a seguir mostra como declarar que um usuário vai receber uma cobrança de US $3 de taxa de processamento por escolher um pagamento com cartão de crédito.

let methods = [{
 supportedMethods: 'basic-card',
 data: {
   supportedNetworks: ['visa', 'mastercard']
   supportedTypes: ['credit', 'debit']
 }
}];

let details = {
 displayItems: [{
   label: 'T-shirt',
   amount: { currency: 'USD', value: '68.00' }
 }],
 total: {
   label: 'Total price',
   amount: { currency: 'USD', value: '68.00' }
 },
 modifiers: [{
   supportedMethods: 'basic-card',
   data: {
     supportedTypes: ['credit']
   },
   additionalDisplayItems: [{
     label: 'Processing fee',
     amount: { currency: 'USD', value: '3.00' }
   }],
   total: {
     label: 'Credit card price',
     amount: {currency: ‘USD’, value: ‘71.00’}}
 }]
};

let options = {};

let request = new PaymentRequest(methods, details, options);

Na planilha de solicitação de pagamento real, assim que escolher um pagamento com cartão de crédito, o usuário verá um item de exibição adicional chamado "Taxa de processamento" com uma cobrança de US $3, com um preço total de US $71,00.

PaymentDetailsModifier contém os seguintes parâmetros:

Nome da propriedade
supportedMethods	Especifique qual forma de pagamento aplica essa regra.
additionalDisplayItems	Outros itens de exibição em que você quer adicionar descontos ou cobranças extras.
total	Preço total após adicionar os additionalDisplayItems.
data	Para pagamentos com basic-card, isso será usado como uma forma de filtrar tipos de cartão específicos com supportedTypes. Caso contrário, o uso desse parâmetro vai depender da forma de pagamento (app de pagamento). Consulte a documentação de cada forma de pagamento.

Quando há opções de frete, as coisas ficam um pouco complicadas, porque o preço total de modifiers não pode ser estático e precisa de modificação dinâmica.

Para isso, você vai modificar o additionalDisplayItems e o total da propriedade modifiers no evento shippingaddresschange e shippingoptionchange, assim como faz com a propriedade displayItems do objeto PaymentDetails.

A propriedade supportedMethods agora usa uma string

A propriedade supportedMethods no objeto PaymentMethodData (o primeiro argumento para o construtor PaymentRequest) tem recebido uma matriz de strings que indica uma forma de pagamento. Agora, ele usa uma única string como argumento.

Por enquanto, ainda é possível fornecer uma matriz.

O que não fazer

Antigo: ainda funciona por enquanto.

var methodData = [{
     supportedMethods: ['basic-card'],
     data: {
       supportedNetworks: ['visa', 'mastercard', 'amex', 'jcb',
         'diners', 'discover', 'mir', 'unionpay']
     }
}, {
    supportedMethods: ['https://bobpay.xyz']
}];

O que fazer

Novo: a nova forma.

var methodData = [{
     supportedMethods: 'basic-card',
     data: {
       supportedNetworks: ['visa', 'mastercard', 'amex', 'jcb',
         'diners', 'discover', 'mir', 'unionpay']
     }
}, {
    supportedMethods: 'https://bobpay.xyz'
}];

Chrome 61

supportedTypes no cartão básico está disponível

Quando supportedMethods for basic-card, agora você poderá fornecer supportedTypes para indicar quais tipos de cartões são aceitos entre credit, debit e prepaid.

var methodData = [{
 supportedMethods: 'basic-card',
 data: {
   supportedNetworks: ['visa', 'mastercard', 'amex', 'jcb',
     'diners', 'discover', 'mir', 'unionpay']
   supportedTypes: ['credit', 'debit', 'prepaid']
 }
}];

Verifique o tipo de cartão com seu gateway de pagamento, já que essa filtragem pode não funcionar perfeitamente dependendo da origem.

Chrome 57

A PaymentRequest agora está disponível em iframes

Agora, a API Payment Request pode ser chamada de dentro de um iframe adicionando o atributo allowpaymentrequest ao elemento iframe.

<iframe src="/totally/fake/url" allowpaymentrequest></iframe>

PaymentMethodData é compatível com "basic-card"

O primeiro argumento para o construtor PaymentRequest() é uma matriz de dados de forma de pagamento. O formato PaymentMethodData foi alterado nesta versão.

O que não fazer

Antigo: ainda funciona por enquanto.

var methodData = [{
     supportedMethods: ['visa', 'mastercard', 'amex', 'jcb']
}];
var request = new PaymentRequest(methodData, details, options);

O que fazer

Novo: a nova estrutura.

var methodData = [{
     supportedMethods: ['basic-card'],
     data: {
       supportedNetworks: ['visa', 'mastercard', 'amex', 'jcb',
         'diners', 'discover', 'mir', 'unionpay']
     }
}];
var request = new PaymentRequest(methodData, details, options);

O formato da propriedade data depende do valor em supportedMethods e é baseado na especificação do cartão básico. Observe que a especificação inclui supportedTypes, que aceita credit, debit ou prepaid, mas o Chrome 57 ignora essa propriedade e trata todos os valores em supoprtedNetworks como cartões de crédito.

var methodData = [{
     supportedMethods: ['basic-card'],
     data: {
       supportedNetworks: ['visa', 'mastercard', 'amex', 'jcb',
         'diners', 'discover', 'mir', 'unionpay'],
       supportedTypes: ['credit'] <= not available
     }
}];

Chrome 56

pendente

Como parte das informações do item de pagamento, os desenvolvedores podem adicionar pending para indicar que o preço ainda não foi totalmente determinado. O campo pending aceita um valor booleano.

    {
      label: "State tax",
      amount: { currency: "USD", value : "5.00" },
      pending: true
    },

Isso é usado com frequência para mostrar itens de linha, como valores de frete ou tributos que dependem da seleção do endereço de entrega ou das opções de entrega. O Chrome indica campos pendentes na interface da solicitação de pagamento.

requestPayerName

Como parte da opção de frete (terceiro argumento para PaymentRequest), os desenvolvedores agora podem adicionar requestPayerName para solicitar o nome do pagador separado das informações do endereço de entrega. requestPayerName aceita um valor booleano.

shippingType

Como parte da opção de frete (terceiro argumento para PaymentRequest), os desenvolvedores agora podem adicionar shippingType para solicitar que a interface mostre "entrega" ou "retirada" em vez de "frete". shippingType aceita as strings shipping (padrão), delivery ou pickup.

shippingType="delivery"

shippingType="pickup"

Funções de serializador disponíveis para PaymentResponse e PaymentAddress

Os objetos PaymentResponse e PaymentAddress agora podem ser serializados em JSON. Os desenvolvedores podem converter um objeto JSON chamando a função toJSON() e evitar a criação de funções toDict() complicadas.

request.show().then(response => {
     let res = response.toJSON();
});

canMakePayment

Além da disponibilidade da API, é possível verificar se um usuário tem uma forma de pagamento ativa antes de invocar a API Payment Request. Essa etapa é opcional, já que os usuários ainda podem adicionar uma nova forma de pagamento na interface de pagamento.

let request = new PaymentRequest(methods, details, options);
if (request.canMakePayment) {
     request.canMakePayment().then(result => {
       if (result) {
         // Payment methods are available.
       } else {
         // Payment methods are not available, but users can still add
        // a new payment method in Payment UI.
       }
     }).catch(error => {
       // Unable to determine.
     });
}