@upply/cielo-braspag NPM

cielo-braspag

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

README baseado na lib banzeh/cielo

Índice

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

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.