@upply/cielo-braspag

    0.12.0 • Public • Published

    cielo-braspag

    Client para a API da Cielo + Middleware Braspag em Node.Js

    README baseado na lib banzeh/cielo

    MIT license

    Índice

    Início

    API Cielo

    API Braspag

    Referência da API

    Testes

    Autor

    Contribua

    Licença

    Installation

    npm install --save cielo-braspag
    // ou
    yarn add cielo-braspag

    Como utilizar?

    Iniciando

    const paramsCielo = {
        MerchantId: 'xxxxxxxxxxxxxxxxxxxxxxx',
        MerchantKey: 'xxxxxxxxxxxxxxxxxxxxxxxxxx',
        sandbox: true, // Opcional - Ambiente de Testes
    };
     
    const cieloBraspag = require('cielo-braspag');
    const cielo = cieloBraspag.cielo(paramsCielo);
     
    // Caso precise integrar com a Braspag para utilizar o split de pagamentos
    const paramsBraspag = {
      clientId: 'xxxxxxxxxxxxxxxxxxxxxxx', // merchantId
      clientSecret: 'xxxxxxxxxxxxxxxxxxxxxxxxxx', // merchantKey
      sandbox: true, // Opcional - Ambiente de Testes
    };
     
    const braspag = cieloBraspag.braspag(paramsBraspag);
    cielo.use(braspag); // IMPORTANTE!

    Paramêtros de criação

    Cielo


    Campo Descrição Obrigatório? Default
    MerchantId Identificador da loja/marketplace na Cielo. Sim null
    MerchantKey Chave Publica para Autenticação Dupla na Cielo. Sim null
    sandbox Utilizará o ambientede testes da Cielo? Não false

    Braspag


    Campo Descrição Obrigatório? Default
    ClientId Identificador da loja/marketplace na Cielo. Sim null
    ClientSecret Chave Publica para Autenticação Dupla na Cielo. Sim null
    sandbox Utilizará o ambientede testes da Cielo? Não false

    API Cielo

    Tokenização de cartões

    Criando um cartão tokenizado

    const card = {
      customerName: 'Biro de Biro',
      number: '4123555598761234',
      holder: 'BIRO BIRO',
      expirationDate: '07/2027',
      brand: 'Visa',
    };
     
    // POST para /1/card
    cielo.cards.tokenizeCard(card, [fraudAnalysisData]);

    Consultando um cartão pelo token gerado

    const token = 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx';
     
    // GET para /1/card/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
    cielo.cards.tokenizeCard(card);

    Criando uma venda com cartão tokenizado

    const params = {
      requestId: 'some_id',
      merchantOrderId: '1234',
      customerName: 'Biro da Silva',
      customerStatus: 'NEW',
      customerIdentity: '11225468954',
      customerIdentityType: 'CPF', // ou 'CNPJ'
      amount: 12000,
      installments: 2,
      softDescriptor: 'some bullcrap',
      returnUrl: 'http://google.com',
      cardToken: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
      cvv: 'xxx',
      brand: 'Master',
      capture: false, // ou true para autorizar E capturar a venda
    };
     
    // POST para /1/sales
    cielo.creditCards.payWithToken(params);

    Cancelamento de vendas

    // cancelamento total
     
    const params = {
      paymentId: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
    };
     
    // PUT para /1/sales/{paymentId}/void
    cielo.creditCards.cancelSale(params);
     
    // ou cancelamento parcial
     
    const params = {
      paymentId: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
      amount: 12500,
    };
     
    // PUT para /1/sales/{paymentId}/void?amount=12500
    cielo.creditCards.cancelSale(params);

    Consulta de transações

    // consulta por paymentId
     
    const params = {
      paymentId: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
    };
     
    // GET para /1/sales/{paymentId}
    cielo.consulting.sale(params);
     
    // ou consulta por merchantOrderId
     
    const params = {
      merchantOrderId: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
    };
     
    // GET para /1/sales?merchantOrderId={merchantOrderId}
    cielo.consulting.sale(params);

    Análises de Fraude

    Caso deseje utilizar a análise de fraude, passe os dados necessários no segundo parâmetro de qualquer método de pagamento (por exemplo, payWithToken), de acordo com a documentação da Cielo.

    API Braspag

    O código relativo à Braspag serve tanto como um middleware para conformar a chamada aos requisitos da Braspag de forma transparente, quanto para fazer operações específicas da API da Braspag (por exemplo, ajustes em transações com split).

    Para utilizá-la como middleware, você deve configurar o objeto cielo assim:

    cielo.use(braspag);

    onde o objeto braspag é criado desta forma:

    const braspag = cieloBraspag.braspag(paramsBraspag);

    como mencionado na seção como utilizar

    Além disso, há operações específicas da plataforma da Braspag:

    Agenda Financeira

    Ajustando de uma transação com split

    Importante: ambos os merchantIds devem ter participado da transação. Não é possível ajustar uma transação para incluir um novo merchant id.

    const params = {
      merchantIdToDebit: 'EA4DB25A-F981-4849-87FF-026897E006C6',
      merchantIdToCredit: '44F68284-27CF-43CB-9D14-1B1EE3F36838',
      adjustDate: new Date(2018, 8, 17),
      amount: 1200,
      description: 'Lorem Ipsum Dolor Sit Amet',
      transactionId: '717A0BD0-3D92-43DB-9D1E-9B82DFAFA392',
    };
     
    // POST para /adjustment-api/adjustments/
    braspag.financialAgenda.adjustTransaction(params);

    Consultando um ajuste

    const transactionId = 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx';
     
    // GET para /adjustment-api/adjustments/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
    braspag.financialAgenda.getAdjustment(transactionId);

    Interceptors

    requestInterceptor

    Verifica se há um oauth token. Caso não haja, chama internamente renewToken(). Após isso, modifica a configuração da chamada para a API da Cielo:

    • Adiciona o header Authorization com o valor Bearer [oauth_token]
    • Altera o body.Payment.Type de CreditCard para SplittedCreditCard ou de DebitCard para SplittedDebitCard
    • Na chamada de cancelSale, para cancelamentos parciais, torna obrigatório passar a configuração de split, cuja soma do campo "amount" deve ser igual a params.amount, como no exemplo abaixo:
    // cancelamento total (sem alterações)
     
    const params = {
      paymentId: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
    };
     
    // PUT para /1/sales/{paymentId}/void
    cielo.creditCards.cancelSale(params);
     
    // ou cancelamento parcial
     
    const params = {
      paymentId: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
      amount: 12500,
      split: [
        {
          merchantId: 'first-merchant-id',
          amount: 10000,
        },
        {
          merchantId: 'second-merchant-id',
          amount: 2500,
        },
      ],
    };
     
    // PUT para /1/sales/{paymentId}/void?amount=12500
    cielo.creditCards.cancelSale(params);

    responseInterceptor

    Apenas retorna a response.

    responseErrorInterceptor

    Verifica se o código de erro é 401 e se há no array de erros da resposta algum erro com código 238 (token expirado). Em caso positivo, faz uma chamada interna para renewToken() e após a obtenção de novo token, refaz a chamada original.

    Renovar token oauth

    Use caso você queira renovar explicitamente o token e obtê-lo posteriormente. Normalmente não será necessário chamar este método.

    braspag.renewToken().then(token => {});

    Referência da API

    Consulte os campos necessários na documentação da Cielo

    PT-Br

    En

    Consulte os campos necessários para Split de Pagamentos na documentação da Braspag

    PT-Br

    Testes

    Para rodar os testes automatizados, apenas execute o seguinte comando

    npm test
    // ou
    yarn test

    Autor

    André Mazoni

    Github

    Contribua

    Recursos da API estão sendo implementados conforme a necessidade. Caso precise de alguma, não hesite em solicitar ou em adicioná-la à lib. Contribuições são bem vindas.

    Licença

    MIT License

    Install

    npm i @upply/cielo-braspag

    DownloadsWeekly Downloads

    28

    Version

    0.12.0

    License

    MIT

    Unpacked Size

    156 kB

    Total Files

    15

    Last publish

    Collaborators

    • avatar