Client para a API da Cielo + Middleware Braspag em Node.Js
README baseado na lib banzeh/cielo
npm install --save cielo-braspag
// ou
yarn add cielo-braspag
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!
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 |
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 |
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]);
const token = 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx';
// GET para /1/card/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
cielo.cards.tokenizeCard(card);
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: 'https://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 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 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);
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.
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:
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);
const transactionId = 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx';
// GET para /adjustment-api/adjustments/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
braspag.financialAgenda.getAdjustment(transactionId);
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);
Apenas retorna a response.
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.
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 => {});
Consulte os campos necessários na documentação da Cielo
Consulte os campos necessários para Split de Pagamentos na documentação da Braspag
Para rodar os testes automatizados, apenas execute o seguinte comando
npm test
// ou
yarn test
André Mazoni
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.
MIT License