Cliente para a API da Cielo em node.js
npm install cielo-clientCliente para a API 3.0 da Cielo em Typescript/Nodejs
Este projeto é amplamente baseado no projeto original "cielo" criado por banzeh. Para consultar o código-fonte original e a documentação do projeto do autor, acesse diretamente o repositório.
Além das funcionalidades presentes no projeto original, este "fork" adiciona suporte a PIX e pretende incorporar, no futuro, novas funcionalidades disponibilizadas pela API da Cielo conforme forem lançadas.
#### Início
+ Instalação
+ Como Utilizar
+ Paramêtros de criação
#### Cartão de Crédito
+ Criando uma transação simples
+ Criando uma transação completa
+ Criando uma venda com Autenticação
+ Criando uma venda com Análise de Fraude
+ Criando uma venda com Card Token
+ Capturando uma venda
+ Cancelando uma venda
#### Cartão de Débito
+ Criando uma venda simplificada
#### PIX
+ Criando uma venda simplificada
#### Boleto
+ Criando uma venda de Boleto
#### Cartões
+ Gerando o token de um cartão
#### Consultas
+ Consultando as transações usando PaymentID
+ Consultando as transações usando MerchandOrderID
+ Consulta de Cardbin
+ Consulta de Recorrência
+ Consulta de cartão tokenizado
#### API Reference
#### Testes
#### Autor
#### License
js
npm install --save cielo
` Como utilizar?
$3
ts
import { CieloConstructor, Cielo } from 'cielo';const cieloParams: CieloConstructor = {
merchantId: 'xxxxxxxxxxxxxxxxxxxxxxx',
merchantKey: 'xxxxxxxxxxxxxxxxxxxxxxxxxx',
requestId: 'xxxxxxx', // Opcional - Identificação do Servidor na Cielo
sandbox: true, // Opcional - Ambiente de Testes
debug: true // Opcional - Exibe a requisição e a resposta no console no formato JSON
}
const cielo = new Cielo(cieloParams);
`$3
| Campo | Descrição | Obrigatório? | Default |
| :-------------: |:-------------:| :-----:| :-----:|
| merchantId | Identificador da loja na Cielo. | Sim | null |
| merchantKey | Chave publica para autenticação dupla na Cielo. | Sim | null |
| requestId | Identificador do Request, utilizado quando o lojista usa diferentes servidores para cada GET/POST/PUT. | Não | null |
| sandbox | Ambiente de testes da Cielo | Não | false |
| debug | Exibe requisição da transação no console | Não | false |
Cartão de Crédito
$3
Usando Promise
ts
const vendaParams: TransactionCreditCardRequestModel = {
customer: {
name: "Comprador crédito",
identity: "12345678909",
},
merchantOrderId: "2014111703",
payment: {
amount: 10000, // R$100,00
creditCard: {
brand: EnumBrands.VISA,
cardNumber: "4532117080573700",
holder: "Comprador T Cielo",
expirationDate: "12/2021",
},
installments: 1,
softDescriptor: "Banzeh",
type: EnumCardType.CREDIT,
capture: false,
},
};cielo.creditCard.transaction(dadosSale)
.then((data) => {
return console.log(data);
})
.catch((err) => {
return console.error('ERRO', err);
})
`Ou usando Async / Await
ts
const transaction = await cielo.creditCard.transaction(dadosSale);
console.log(transaction);
`$3
ts
const capturaVendaParams: CaptureRequestModel = {
paymentId: '24bc8366-fc31-4d6c-8555-17049a836a07',
amount: 2000, // Caso o valor não seja definido, captura a venda no valor total
};cielo.creditCard.captureSaleTransaction(capturaVendaParams)
.then((data) => {
return console.log(data);
})
.catch((err) => {
return console.error('ERRO', err);
})
`$3
js
const cancelamentoVendaParams: CancelTransactionRequestModel = {
paymentId: '24bc8366-fc31-4d6c-8555-17049a836a07',
amount: 100, // Caso o valor não seja definido, cancela a venda no valor total
};cielo.creditCard.cancelTransaction(cancelamentoVendaParams)
.then((data) => {
return console.log(data);
})
.catch((err) => {
return console.error('ERRO', err);
})
`Ou usando Async / Await
ts
const cancel = await cielo.creditCard.cancelSale(dadosSale);
console.log(cancel);
` Cartão de Débito
$3
ts
const debitCardTransactionParams: DebitCardSimpleTransactionRequestModel = {
merchantOrderId: "2014121201",
customer:{
name: "Paulo Henrique",
identity: "12345678909",
},
payment: {
type: EnumCardType.DEBIT,
amount: 15700,
provider: "Simulado",
returnUrl: "http://www.google.com.br",
debitCard:{
cardNumber: "4532117080573703",
holder: "Teste Holder",
expirationDate: "12/2022",
securityCode: "023",
brand: EnumBrands.VISA
}
}
} cielo.debitCard.createSimpleTransaction(debitCardTransactionParams)
.then((data) => {
return console.log(data);
})
.catch((err) => {
return console.error('ERRO', err);
})
` PIX
$3
ts
const pixTransactionParams: PIXTransactionRequestModel = {
merchantOrderId: "2014121201",
customer:{
name: "Paulo Henrique",
identity: "12345678909",
},
payment: {
type: EnumCardType.DEBIT,
amount: 15700,
provider: "Simulado",
returnUrl: "http://www.google.com.br",
payment: {
amount: 10000,
type: "Pix",
provider: "Cielo",
qrCode: {},
},
}
} cielo.pix.transaction(pixTransactionParams)
.then((data) => {
return console.log(data);
})
.catch((err) => {
return console.error('ERRO', err);
})
` Boleto
$3
ts
const boletoParams: BankSlipCreateRequestModel = {
merchantOrderId: '20180531',
customer: {
name: 'Comprádor Boleto Cíéló Áá',
identity: '1234567890',
address: {
street: 'Avenida Marechal Câmara',
number: '160',
complement: 'Sala 934',
zipCode: '22750012',
district: 'Centro',
city: 'Rio de Janeiro',
state: 'RJ',
country: 'BRA'
}
},
payment: {
type: 'Boleto',
amount: 15700,
provider: 'Bradesco2',
address: 'Rua Teste',
boletoNumber: '123',
assignor: 'Empresa Teste',
demonstrative: 'Desmonstrative Teste',
expirationDate: '5/1/2020',
identification: '11884926754',
instructions: 'Aceitar somente até a data de vencimento, após essa data juros de 1% dia.'
}
} cielo.bankSlip.create(boletoParams)
.then((data) => {
return console.log(data);
})
.catch((err) => {
return console.error('ERRO', err);
})
` Recorrência
$3
ts
const createRecurrencyParams: RecurrentCreateModel = {
merchantOrderId: '2014113245231706',
customer: {
name: 'Comprador rec programada'
},
payment: {
type: EnumCardType.CREDIT,
amount: 1500,
installments: 1,
softDescriptor: '123456789ABCD',
currency: 'BRL',
country: 'BRA',
recurrentPayment: {
authorizeNow: true,
endDate: '2022-12-01',
interval: EnumRecurrentPaymentInterval.SEMIANNUAL
},
creditCard: {
cardNumber: '4024007197692931',
holder: 'Teste Holder',
expirationDate: '12/2030',
securityCode: '262',
saveCard: false,
brand: 'Visa' as EnumBrands
}
}
} cielo.recurrent.create(createRecurrencyParams)
.then((data) => {
return console.log(data);
})
.catch((err) => {
return console.error('ERRO', err);
})
`$3
ts
const updateCustomer: RecurrentModifyCustomerModel = {
paymentId: firstRecurrency.payment.recurrentPayment.recurrentPaymentId,
customer: {
name: 'Customer',
email: 'customer@teste.com',
birthdate: '1999-12-12',
identity: '22658954236',
identityType: 'CPF',
address: {
street: 'Rua Teste',
number: '174',
complement: 'AP 201',
zipCode: '21241140',
city: 'Rio de Janeiro',
state: 'RJ',
country: 'BRA'
},
deliveryAddress: {
street: 'Outra Rua Teste',
number: '123',
complement: 'AP 111',
zipCode: '21241111',
city: 'Qualquer Lugar',
state: 'QL',
country: 'BRA',
}
}
}cielo.recurrent.modifyCustomer(updateCustomer)
.then((data) => {
return console.log(data);
})
.catch((err) => {
return console.error('ERRO', err);
})
`ts
const updateEndDate: RecurrentModifyEndDateModel = {
paymentId: firstRecurrency.payment.recurrentPayment.recurrentPaymentId,
endDate: '2021-01-09'
}cielo.recurrent.modifyEndDate(updateEndDate)
.then((data) => {
return console.log(data);
})
.catch((err) => {
return console.error('ERRO', err);
})
`ts
const modifyRecurrencyParams: RecurrentModifyIntervalModel = {
paymentId: firstRecurrency.payment.recurrentPayment.recurrentPaymentId,
interval: EnumRecurrentPaymentUpdateInterval.MONTHLY
}cielo.recurrent.modifyInterval(modifyRecurrencyParams)
.then((data) => {
return console.log(data);
})
.catch((err) => {
return console.error('ERRO', err);
})
`ts
const updateRecurrencyDay: RecurrentModifyDayModel = {
paymentId: firstRecurrency.payment.recurrentPayment.recurrentPaymentId,
recurrencyDay: 10
}cielo.recurrent.modifyRecurrencyDay(updateRecurrencyDay)
.then((data) => {
return console.log(data);
})
.catch((err) => {
return console.error('ERRO', err);
})
`ts
const updateAmount: RecurrentModifyAmountModel = {
paymentId: firstRecurrency.payment.recurrentPayment.recurrentPaymentId,
amount: 156 // Valor do Pedido em centavos: 156 equivale a R$ 1,56
}cielo.recurrent.modifyAmount(updateAmount)
.then((data) => {
return console.log(data);
})
.catch((err) => {
return console.error('ERRO', err);
})
`ts
const updateNextPaymentDate: RecurrentModifyNextPaymentDateModel = {
paymentId: firstRecurrency.payment.recurrentPayment.recurrentPaymentId,
nextPaymentDate: '2020-05-20'
}cielo.recurrent.modifyNextPaymentDate
.then((data) => {
return console.log(data);
})
.catch((err) => {
return console.error('ERRO', err);
})
`ts
const updatePayment: RecurrentModifyPaymentModel = {
recurrentPaymentId: RecurrentPaymentId,
payment: {
type: EnumCardType.CREDIT,
amount: "123",
installments: 3,
country: "USA",
currency: "BRL",
softDescriptor: "123456789ABCD",
creditCard: {
brand: EnumBrands.VISA,
holder: "Teset card",
cardNumber: "1234123412341232",
expirationDate: "12/2030"
}
}
}cielo.recurrent.modifyPayment(updatePayment)
.then((data) => {
return console.log(data);
})
.catch((err) => {
return console.error('ERRO', err);
})
`ts
const deactivateRecurrencyParams: RecurrentModifyModel = {
paymentId: firstRecurrency.payment.recurrentPayment.recurrentPaymentId
}cielo.recurrent.deactivate(deactivateRecurrencyParams)
.then((data) => {
return console.log(data);
})
.catch((err) => {
return console.error('ERRO', err);
})
`
#### Reabilitando um Pedido Recorrentets
const reactivateRecurrencyParams: RecurrentModifyModel = {
paymentId: firstRecurrency.payment.recurrentPayment.recurrentPaymentId
}cielo.recurrent.reactivate(updateReactivate)
.then((data) => {
return console.log(data);
})
.catch((err) => {
return console.error('ERRO', err);
})
` Cartões
$3
ts
const tokenParams: TokenizeRequestModel = {
customerName: 'Comprádor Teste Cíéló Áá',
cardNumber: '5555666677778884',
holder: 'Comprador T Cielo',
expirationDate: '12/2021',
brand: brand as EnumBrands
};cielo.card.createTokenizedCard(tokenParams)
.then((data) => {
console.log(data)
})
.catch((err) => {
console.log(err);
})
` Consultas
$3
ts
const consultaParams: ConsultTransactionPaymentIdRequestModel = {
paymentId: "24bc8366-fc31-4d6c-8555-17049a836a07"
};cielo.search.paymentId(consultaParams)
.then((data) => {
console.log(data)
})
.catch((err) => {
console.log(err);
})
`$3
ts
const consultaParamsMerchantOrderId: ConsultTransactionMerchantOrderIdRequestModel = {
merchantOrderId: "2014111706"
};cielo.search.merchantOrderId(consultaParamsMerchantOrderId)
.then((data) => {
console.log(data)
})
.catch((err) => {
console.log(err);
})
`$3
ts
const consultaBinNacionalParams: ConsultBinRequestModel = {
cardBin: '453211'
};cielo.search.bin(consultaBinNacionalParams)
.then((data) => {
console.log(data)
})
.catch((err) => {
console.log(err);
})
`$3
ts
const consultaCartaoTokenizadoParams: ConsultTokenRequestModel= {
cardToken: '66b2c162-efbf-4692-aee5-e536c0f81037'
}cielo.search.cardtoken(consultaCartaoTokenizadoParams)
.then((data) => {
console.log(data)
})
.catch((err) => {
console.log(err);
})
`$3
ts
const recurrencyConsultingParams: ConsultTransactionRecurrentPaymentIdRequestModel = {
recurrentPaymentId: firstRecurrency.payment.recurrentPayment.recurrentPaymentId
}cielo.search.recurrent(recurrencyConsultingParams)
.then((data) => {
console.log(data)
})
.catch((err) => {
console.log(err);
})
` API Reference
Consulte os campos necessários na documentação da Cielo
Testes
Para rodar os testes automatizados, apenas execute o seguinte comando
npm test
Thiago Medeiros
MIT License
Copyright (c) 2025 thihxm
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.