Payment Lib

Required Implementations

Toda lógica principal deve estar contida dentro de LoadCheckoutPaymentContext
ES5 válido (Pode ser compilado ou o que for, mas é importante ter em conta os browser que damos suporte e não utilizar métodos sem polyfills - inclusive abrimos alguns métodos com polyfills para auxiliar no desenvolvimento)

LoadCheckoutPaymentContext

Este método é exposto em um contexto global através de window.LoadCheckoutPaymentContext, ele é responsável por efetuar o carregamento de todos Plugins dos partners.

Ele espera como parâmetro um método que conterá todo o código do Plugin que é esperado que seja executado dentro do Checkout React.Esse método recebe 2 argumentos como no exemplo a seguir:

LoadCheckoutPaymentContext(function (Checkout, PaymentMethods) {  
  // Your plugin implementation  
})

O método LoadCheckoutPaymentContext recebe 2 parâmetros, que são:

Checkout - Contém os dados e métodos responsáveis por interagir com os componentes do checkout
PaymentMethods - Instâncias pré-definidas de como cada tipo de pagamento deve se comportar Cada um desses parâmetros é responsável por controlar como o checkout e seus componentes irá comportar, eles também permitem ao plugin execução de Ajax Calls ou por exemplo utilização de dados do carrinho como LineItems. A seguir eles serão mais detalhados.

Checkout [argument]

O parâmetro de Checkout é repsonsável por todo comportamento e interação com o Checkout, e possui os seguintes objetos:

Nome	Descrição
updateFields	Atualiza a exibição dos inputs opcionais do checkout. Lista de fields
addPaymentOption	Adiciona o método criado ao checkout
closeAlert	Fecha o alerta de erro no Checkout, caso este esteja aberto.
setInstallments	Atualiza o array com as opções de parcelamento. Exemplo
getData	Obtém os dados do carrinho (endereço, dados do form de pagamento, email, país, etc). Abaixo exibiremos um exemplo completo do objeto
http	Objeto utilizado para fazer ajax calls
utils	Objeto com funções auxiliar, as funções auxiliares estão listadas abaixo

Throttle
LoadScript
FlattenObject

getData

exemplo do objeto data:

{
  form: {},
  order: {
    cart: {
      id: 164943094,
      hash: '640a1214704c0470410d0f0712ca4fe8efb9e5b1',
      number: null,
      prices: {
        shipping: '0.00',
        discount_gateway: 0,
        discount_coupon: 1.99,
        discount_promotion: 0,
        discount_coupon_and_promotions: 1.99,
        subtotal_with_promotions_and_coupon_applied: 0,
        subtotal: 1.99,
        total: 0,
        total_usd: 0
      },
      lineItems: [
        {
          id: 180289687,
          name: 'Barato do dia',
          price: '1.99',
          quantity: 1,
          free_shipping: false,
          product_id: 42077389,
          variant_id: 108691186,
          thumbnail: '//d26lpennugtm8s.cloudfront.net/stores/947/640/products/61193340_2332461190364712_7945763697455005696_n1-2cdc274080e83dfe2f15708278623450-100-0.jpg',
          variant_values: '',
          sku: null,
          properties: [],
          url: 'https://prefixnot2.lojavirtualnuvem.com.br/produtos/barato-do-dia/?variant=108691186'
        }
      ],
      currency: 'BRL',
      currencyFormat: {
        'short': 'R$%s',
        'long': 'R$%s'
      },
      lang: 'pt',
      langCode: 'pt_BR',
      coupon: {
        id: 535091,
        code: 'NOT100',
        type: 'percentage',
        value: '100.00',
        valid: true,
        used: 0,
        max_uses: null,
        start_date: null,
        end_date: null,
        min_price: null,
        categories: null
      },
      shipping: {
        type: 'ship',
        method: 'correios',
        option: '04510',
        branch: null,
        disabled: null,
        raw_name: 'Correios - PAC',
        suboption: null
      },
      status: {
        order: 'open',
        order_cancellation_reason: null,
        fulfillment: 'unpacked',
        payment: 'pending'
      },
      completedAt: null,
      line_items: [
        {
          id: 180289687,
          name: 'Barato do dia',
          price: '1.99',
          quantity: 1,
          free_shipping: false,
          product_id: 42077389,
          variant_id: 108691186,
          thumbnail: '//d26lpennugtm8s.cloudfront.net/stores/947/640/products/61193340_2332461190364712_7945763697455005696_n1-2cdc274080e83dfe2f15708278623450-100-0.jpg',
          variant_values: '',
          sku: null,
          properties: [],
          url: 'https://prefixnot2.lojavirtualnuvem.com.br/produtos/barato-do-dia/?variant=108691186'
        }
      ]
    },
    shippingAddress: {
      zipcode: '31330290',
      first_name: 'João',
      last_name: 'Cesar',
      address: 'Avenida Miguel Perrela',
      number: '123',
      floor: '',
      locality: 'Castelo',
      city: 'Belo Horizonte',
      state: 'Minas Gerais',
      country: 'BR',
      phone: '',
      between_streets: null,
      reference: null
    },
    billingAddress: {
      id_number: '12345678910',
      zipcode: '31330000',
      first_name: 'João',
      last_name: 'Cesar',
      address: 'Avenida Miguel Perrela',
      number: '123',
      floor: '',
      locality: 'Castelo',
      city: 'Belo Horizonte',
      state: 'Minas Gerais',
      country: 'BR',
      phone: ''
    },
    contact: {
      name: 'João Cesar',
      email: 'joaocesar123p1@mailinator.com',
      phone: '31999999999',
    }
  },
  country: 'BR',
  totalPrice: 21,
  storeId: 947640,
  callbackUrls: {
    success: 'https://acmestore.lojavirtualnuvem.com.br/checkout/v3/success/194667243/a69f9c70eade480302bf9544452f9b92c528624e',
    failure: 'https://acmestore.lojavirtualnuvem.com.br/checkout/v3/next/194667243/a69f9c70eade480302bf9544452f9b92c528624e',
    cancel: 'https://acmestore.lojavirtualnuvem.com.br/checkout/v3/next/194667243/a69f9c70eade480302bf9544452f9b92c528624e'
  },
  installments: null
}

Exemplo da utilização do método getData no script de pagamento:

LoadCheckoutPaymentContext(function (Checkout, PaymentMethods) {
  var Credit = PaymentMethods.Transparent.CardPayment({
    id: 'credit',
    name: 'credit',
    onSubmit: function() {
      // Obtem todos os dados do objeto de data que vimos acima
      var data = Checkout.getData()

      // Obtem apenas os dados da chave `form` do objeto de data
      var form = Checkout.getData('form')
    }
  });
});

http

exemplo:

Checkout.http.post('/checkout/payment/', {
  cartId: cartId,
  cartHash: cartHash,
  endpoint: 'transparent',
  method: 'moip'
}).then(function (response) {
  // do something with response
});

PaymentMethods [argument]

Cada método tem uma pré-configuração, abaixo temos a listagem de todos tipos de pagamento disponíveis:

Nome	Descrição
CustomPayment	Classe contendo os métodos e configurações para o tipo de pagamento custom
ModalPayment	Classe contendo os métodos e configurações para o tipo de pagamento modal
RedirectPayment	Classe contendo os métodos e configurações para o tipo de pagamento redirect
Transparent	Classe contendo os métodos e configurações para o tipo de pagamento transparent. O método transparente possi as seguintes subclasses:

CardPayment
DebitPayment
BankDebitPayment
BoletoPayment
TicketPayment
WireTransferPayment
PixPayment
QrCodePayment

A diferença entre as classes dos métodos é o template e os inputs disponíveis em cada um. Lista de inputs

Exemplo utilizando CustomPayment

LoadCheckoutPaymentContext(function (Checkout, PaymentMethods) {
  var Custom = PaymentMethods.CustomPayment({
    id: 'custom',
    name: 'custom'
  });
  Checkout.addPaymentOption(Custom);
});

Se o método em questão for Transparent a instância deve ser invocada utilizando uma das subclasses. Ex:

var Credit = PaymentMethods.Transparent.CardPayment({
  id: 'acme_credit'
});

Parâmetros das instancias dos PaymentMethods: No exemplo acima passamos apenas o id, abaixo iremos mostrar a lista completa.

fields

Utilizado para indicar quais inputs opcionais do checkout estarão habilitados. A lista de campos depende do template.

CardPayment:

Nome	Descrição	Tipo	Exemplo
bankList	Lista de bancos	array	[{ name: 'Bank1', code: '23' }...]
issuerList	Lista de bancos (AR)	array	[{ name: 'Itau', id: '11' }...]
card_holder_id_types	Lista de tipo de documento	array	[{ name: 'DNI', code: 'DNI' }, { name: 'CPF', code: 'CPF' }, { name: 'CNPJ', code: 'CNPJ' }, { name: 'CI', code: 'CI' }, { name: 'LC', code: 'LC' }, { name: 'LE', code: 'LE' }, { name: 'Otro', code: 'Otro'}]
card_holder_id_number	Documento	boolean	true or false
card_holder_birth_date	Data de aniversário	boolean	true or false
card_holder_phone	Telefone	boolean	true or false

DebitPayment:

Nome	Descrição	Tipo	Exemplo
bank_list	Lista de bancos	array	[{ name: 'Bank1', code: '23' }...]
debit_card_holder_name	Nome do comprador	boolean	true or false
debit_card_id_number	Documento	boolean	true or false

BoletoPayment:

Nome	Descrição	Tipo	Exemplo
boleto_holder_name	Nome do comprador	boolean	true or false
boleto_id_number	Documento	boolean	true or false
efectivo_list	?	array	[{ name: 'Rapipago', code: 'rapipago' }...]

PixPayment:

Nome	Descrição	Tipo	Exemplo
holder_name	Nome do comprador	boolean	true or false
holder_id_number	Documento (CPF)	boolean	true or false

Geral

Nome	Descrição	Tipo	Exemplo
billing_address	Endereço de faturamento	boolean	true or false
cardBrands	Lista de bandeiras de cartões	object/array	{ credit_card: ['visa', ...]... }

Lista completa de bandeiras de cartões disponiveis: [ 'amex'', 'argencard', 'aura', 'bapropagos', 'cabal', 'cabaldebit', 'cencosud', 'cobroexpress', 'dinersclub', 'discover', 'elo', 'hiper', 'hipercard', 'iltalcred', 'jcb', 'maestro', 'magna', 'mastercard', 'nativa', 'pagofacil', 'rapipago', 'tarjeta-naranja', 'tarjeta-shopping', 'todopago', 'unionpay', 'visa', 'visadebit' ]

Exemplo informando as bandeiras de cartão:

var Credit = PaymentMethods.Transparent.CardPayment({
  id: 'credit',
  name: 'credit',
  fields: {
    cardBrands: {
      credit_card: ['visa', 'mastercard', 'elo', 'discover']
    }
  }
});

As bandeiras de cartões são exibidas como imagens no checkout, ao acessar o meio de pagamento em questão

Exemplo ativando data de aniversário e telefone ao form:

var Credit = PaymentMethods.Transparent.CardPayment({
  id: 'credit',
  name: 'credit',
  fields: {
    card_holder_birth_date: true,
    card_holder_phone: true
  }
});

Não é necessário informar o input como false, basta não informar que ele não será exibido.

Caso deseje atualizar um campo do formulário após a inicialização do script, você pode utilizar o método updateFields que faz parte do objeto Checkout.

Exemplo:

var Credit = PaymentMethods.Transparent.CardPayment({
  id: 'credit',
  name: 'credit',
  onLoad: function() {
    Checkout.updateFields({
      method: 'credit', // Este valor é o valor do id inserido
      value: { card_holder_birth_date: true }
    });
  }
});

scripts

Utilizado para carregar algum script externo dependente, antes de add o método ao checkout.

onLoad

Função executada após o método ser adicionado.

onDataChange

Função executada sempre que algum dado do carrinho é alterado

onSubmit

Função executada quando o usuário clica em "Finalizar pedido" e todos os campos obrigatórios do carrinho foram preenchidos corretamente

A função onSubmit recebe um parâmetro chamado callback, este parâmetro é uma função que é utilizada para retornar ao checkout as informações sobre o processo de pagamento.

A função callback pode ser invocada passando um objeto como parâmetro, esse objeto aceita as seguintes chaves:

Nome	Descrição
success	Se esta chave for passada como true, o checkout ira atualizar o pedido com as demais chaves passadas abaixo, se for passado false, o checkout irá exibir uma mensagem de erro ao usuário, a mensagem de erro pode ser definida na chave `message`
message	Mensagem exibida ao usuário quando o pagamento falha, a chave `success` deve ser passada como false
close	Fecha o pedido (true or false)
confirmed	Indica se o pagamento do pedido foi confirmado (true or false)
recovered	?
extraBoletoUrl	url do boleto gerado (string)
extraAuthorized	?
redirect	url de redirecionamento para o gateway de pagamento (string)
skipRedirect	Não realiza o redirecionamento no checkout, neste caso o redirecionamento deve ser feito diretamente no script

Exemplo:

LoadCheckoutPaymentContext(function (Checkout, PaymentMethods) {
	var Custom = PaymentMethods.CustomPayment({
    id: 'custom',
		name: 'custom',
		scripts: 'https://meuscriptonline.com/payment.js',
		onLoad: function() {
			// do something after the script loads
			// Example: generate a token
		},
		onDataChange: Checkout.utils.throttle(function () {
			// do something when data change
			// data changed is already available on `Checkout.getData()`
			// Example: update credit card installments when order value change
		}, 700),
		onSubmit: function (callback) {
			// do something when user submit payment
			callback({
				success: true/false,
				...
			})
		}
	});
	Checkout.addPaymentOption(Custom);
});

Checkout form data

Os dados do formulário do checkout podem ser encontrados no objeto Checkout.getData('form'), os possíveis dados são:

CardPayment:

Nome	Descrição	Opcional	Opção correspondente
cardNumber	número do cartão	Não
cardHolderName	nome do titular do cartão	Não
cardExpiration	data de expiração do cartão. ex: `12/20`	Não
cardCvv	código de verificação do cartão	Não
cardInstallments	número de parcelas	Não
cardHolderIdNumber	documento do comprador	Sim	card_holder_id_number
cardHolderBirthDate	data de aniversário do comprador	Sim	card_holder_birth_date
cardHolderPhone	telefone do comprador	Sim	card_holder_phone
bankId	Instituição bancaria	Sim	bankList
issuerId	Instituição bancaria (Argentina)	Sim	issuerList
cardHolderIdType	Tipo do documento	Sim	card_holder_id_types

DebitPayment:

Nome	Descrição	Opcional	Opção correspondente
bank	Instituição bancaria	Sim	bank_list
holderName	Nome do comprador	Sim	debit_card_holder_name
holderIdNumber	Documento do comprador	Sim	debit_card_id_number

BoletoPayment:

Nome	Descrição	Opcional	Opção correspondente
holderName	Nome do comprador	Sim	boleto_holder_name
holderIdNumber	Documento do comprador	Sim	boleto_id_number
brand	Valor do select de efectivo (Somente AR)	Sim	efectivo_list

As classes CustomPayment, ModalPayment e RedirectPayment não possuem inputs, pois o pagamento é realizado externamente. A diferença entre estes métodos é sua categorização e a exibição no checkout.

Parcelas

Para atualizar as parcelas do cartão de credito no checkout utilizamos o método setInstallments, exemplo:

O objeto dentro do array de installments deve ter as seguintes chaves:

Nome	Descrição
quantity	número da parcela
installmentAmount	Valor da parcela
totalAmount	Valor total

const installments = [{
	quantity: 1,
	installmentAmount: 25,
	totalAmount: 25
}, {
	quantity: 2,
	installmentAmount: 13,
	totalAmount: 26
}, {
	quantity: 3,
	installmentAmount: 10,
	totalAmount: 30
}]

Checkout.setInstallments(installments)

Credit Card Payment Without Leaving the Checkout

LoadCheckoutPaymentContext(function(Checkout, PaymentMethods) {
  var currentTotalPrice = Checkout.getData('order.cart.prices.total');
  var currencCreditCardBin = null;

  var getCardNumber = function () {
    return Checkout.getData('form.cardNumber') || '';
  };

  var getCardNumberBin = function () {
    return getCardNumber().substring(0, 6);
  };
	
  var refreshInstallments = function () {
    var creditCardBin = getCardNumberBin();

    var hasCreditCardBin = creditCardBin && creditCardBin.length >= 6;
    var hasPrice = Boolean(Checkout.getData('totalPrice'));
    var changedCreditCardBin = creditCardBin !== currencCreditCardBin;
    var changedPrice = Checkout.getData('totalPrice') !== currentTotalPrice;

    return (hasCreditCardBin && hasPrice) && (changedCreditCardBin || changedPrice);
  };
	
  var getInstallments = function() {
    Checkout.http.post('https://app.acmepayments.com/installments', {
      amount: Checkout.getData('totalPrice'),
      bin: getCardNumberBin()
    }).then(function (response) {
      Checkout.setInstallments(response);
    })
  }

  // Define an object to encapsulate the integration
  var AcmeTransparentCredit = PaymentMethods.Transparent.CardPayment({
    id: 'acme_credit',
    name: 'ACME Credit Payment',
    // This function will be called everytime a data on checkout change
    onDataChange: Checkout.utils.throttle(function () {
      if (refreshInstallments()) {
        getInstallments()
      } else if (!getCardNumberBin()) {
        // Clear installments if customer remove credit card number
        Checkout.setInstallments(null);
      }
    }, 700),
    // This function will be called when the consumer finishes the checkout flow so you can initiate the transaction
    onSubmit: function(callback) {
      // Let's imagine the app providies this endpoint to proccess credit payments
      Checkout.http.post('https://app.acmepayments.com/credit-payment', Checkout.getData('form'))
        .then(function(response) {
          // Now that we have the ACME Payments checkout, invoke the callback telling it we want to close order
          callback({
            success: true,
            close: true,
            confirmed: true
          });
        })
        .catch(function(error){
          // Handle a potential error in the http request
          callback({
            success: false
          });
        });
    }
  });

  // Register the object in the checkout
  Checkout.addPaymentOption(AcmeTransparentCredit);

});

Utils

Http (Já com suporte a promises, controle de CSRF com headers pré configurados)## Otimizações
Hoje expomos alguns métodos que não deveriam estar disponíveis para nossos integrantes, no futuro deveríamos exibir somente o necessário.
Mover o método http para dentro do objeto de utils

@tiendanube/checkout-payment-lib

Payment Lib

Required Implementations

LoadCheckoutPaymentContext

Checkout [argument]

getData

http

PaymentMethods [argument]

fields

CardPayment:

DebitPayment:

BoletoPayment:

PixPayment:

Geral

scripts

onLoad

onDataChange

onSubmit

Checkout form data

CardPayment:

DebitPayment:

BoletoPayment:

Parcelas

Credit Card Payment Without Leaving the Checkout

Utils

Readme

Keywords

Package Sidebar

Install

Weekly Downloads

Version

License

Unpacked Size

Total Files

Last publish

Collaborators

@tiendanube/checkout-payment-lib

Payment Lib

Required Implementations

LoadCheckoutPaymentContext

Checkout [argument]

getData

http

PaymentMethods [argument]

fields

CardPayment:

DebitPayment:

BoletoPayment:

PixPayment:

Geral

scripts

onLoad

onDataChange

onSubmit

Checkout form data

CardPayment:

DebitPayment:

BoletoPayment:

Parcelas

Credit Card Payment Without Leaving the Checkout

Utils

Readme

Keywords

Package Sidebar

Install

DownloadsWeekly Downloads

Version

License

Unpacked Size

Total Files

Last publish

Collaborators

Weekly Downloads