Este pacote oferece uma SDK moderna para integrar a API da Gerencianet com TypeScript. Diferente da SDK oficial, esta versão foi desenvolvida com foco total no TypeScript, proporcionando segurança de tipos e melhor reportagem de erros durante o desenvolvimento.
Atenção: O pacote está em desenvolvimento ativo. Atualmente, a API de PIX já está completamente integrada, exceto os Endpoints exclusivos da Efí Pay. Outras funcionalidades serão implementadas em futuras atualizações.
-
-
Variáveis de Ambiente (Environment Variables)
-
npm i @bruno-valero/gerencianet-sdk-typescriptAs variáveis de ambiente Não são mais obrigatórias para que o sdk funcione, porém é recomendável utilizá-las. Elas são usadas para informar as Credenciais necessárias para utilizar as APIs da Efí Pay, para configurá-las siga os passos abaixo:
Agora é possível utilizar o SDK para gerar automaticamente todas as variáveis ambientes necessárias. Por padrão elas serão geradas com valores dummy padrão, porém você pode inserir o valor de cada uma delas durante a criação se desejar.
Para criar as variáveis de ambiente, importe a classe EfiPay de @bruno-valero/gerencianet-sdk-typescript e use seu método estático generateDotEnv passando os valores das variáveis que você deseja. Não é obrigatório preencher todas as variáveis, as que não forem preenchidas por você serão substituídas por valores dummy padrão.
Observe o exemplo:
import EfiPay from '@bruno-valero/gerencianet-sdk-typescript'
EfiPay.generateDotEnv({
variables: {
CLIENT_ID_HOMOLOGACAO: 'meu client id de Homologação',
CLIENT_ID_PRODUCAO: 'meu client id de Produção',
CLIENT_SECRET_HOMOLOGACAO: 'meu client secret de Homologação',
CLIENT_SECRET_PRODUCAO: 'meu client secret de Produção',
PIX_KEY: 'minha chave pix',
WEBHOOK_PIX: 'minha url de webhook pix',
},
})Lembrando que para que as variáveis sejam efetivamente geradas, será necessário executar o script criado.
Se você ainda não criou um arquivo .env na raiz do seu projeto, o método EfiPay.generateDotEnv() irá criar este arquivo e escrever nele todas as variáveis de ambiente necessárias.
Lembrando que para que as variáveis sejam efetivamente geradas, será necessário executar o script criado.
Caso já haja um arquivo .env na raiz do seu projeto, ao usar o método EfiPay.generateDotEnv() ele irá escrever todas as variáveis de ambiente necessárias abaixo do conteúdo já existente no seu arquivo .env, portanto nenhuma das variáveis que você escreveu previamente serão substituídas ou sobrescritas.
Lembrando que para que as variáveis sejam efetivamente geradas, será necessário executar o script criado.
Caso já haja um arquivo .env na raiz do seu projeto e você queira sobrescrever completamente seu com as variáveis geradas automaticamente, basta passar a propriedade mode: "overwite", da seguinte forma:
import EfiPay from '@bruno-valero/gerencianet-sdk-typescript'
EfiPay.generateDotEnv({
variables: {
CLIENT_ID_HOMOLOGACAO: 'meu client id de Homologação',
CLIENT_SECRET_HOMOLOGACAO: 'meu client secret de Homologação',
},
// esta opção irá fazer com que o conteúdo do arquivo ".env" existente seja completamente sobrescrito
mode: 'overwrite',
})Lembrando que para que as variáveis sejam efetivamente geradas, será necessário executar o script criado.
Após criar o script que irá gerar as variáveis de ambiente conforme os exemplos de código acima, será necessário executá-lo para que as variáveis de ambiente sejam efetivamente geradas.
Então para facilitar o trabalho, escreva o script em um arquivo na raiz do seu projeto chamado generate-dot-env.js, agora basta abrir o terminal no diretório raiz do projeto e digitar o comando node ./generate-dot-env.js
Caso você queira escrever manualmente o conteúdo de suas variáveis de ambiente, siga os passos abaixo:
- Crie um arquivo na raiz do projeto com nome de
.env. - Abra o arquivo num editor de texto e armazene as seguintes variáveis de ambiente.
# CERTIFICATES ********************************************
CERTIFICADO_HOMOLOGACAO_PATH="./path/to/homologacao-certificate.(p12|pem)"
CERTIFICADO_PRODUCAO_PATH="./path/to/producao-certificate.(p12|pem)"
CERTIFICADO_HOMOLOGACAO_BASE64="base64_string_of_homologacao"
CERTIFICADO_PRODUCAO_BASE64="base64_string_of_producao"
# CREDENTIALS ********************************************
# HOMOLOGACAO
CLIENT_ID_HOMOLOGACAO="Your_Client_Id_for_Homologacao"
CLIENT_SECRET_HOMOLOGACAO="Your_Client_Secret_for_Homologacao"
# PRODUCAO
CLIENT_ID_PRODUCAO="Your_Client_Id_for_Producao"
CLIENT_SECRET_PRODUCAO="Your_Client_Secret_for_Producao"
# SUPPORT VARIABLES ********************************************
# PIX
PIX_KEY="you-pix-key--might-be-cpf-watsappNumber-or-randomkey-generated-by-efi-bank"
#WEBHOOKS
WEBHOOK_PIX="https://your-url/webhook/pix?ignorar=&hmac=your-custom-key"
# ACCOUNT IDENTIFIER
ACCOUNT_IDENTIFIER="your_account_identifier"- Se não estiver usando um framework, será necessário instalar o
dotenvpara ter acesso às variáveis de ambiente. Se for o caso, execute:
npm i dotenvPara obter maior segurança de tipagem é recomendado criar um arquivo para validar as variáveis de ambiente. Abaixo está um exemplo utilizando a biblioteca zod.
Instale a biblioteca
npm i zodCrie um arquivo com nome env.ts e valide as variáveis da seguinte forma:
import 'dotenv/config'
import z from 'zod'
const envSchema = z.object({
// CERTIFICATES
CERTIFICADO_HOMOLOGACAO_PATH: z
.string()
.min(1, 'environment variable "CERTIFICADO_HOMOLOGACAO_PATH" is missing'),
CERTIFICADO_PRODUCAO_PATH: z
.string()
.min(1, 'environment variable "CERTIFICADO_PRODUCAO_PATH" is missing'),
CERTIFICADO_HOMOLOGACAO_BASE64: z
.string()
.min(1, 'environment variable "CERTIFICADO_HOMOLOGACAO_BASE64" is missing'),
CERTIFICADO_PRODUCAO_BASE64: z
.string()
.min(1, 'environment variable "CERTIFICADO_PRODUCAO_BASE64" is missing'),
// CREDENTIALS
CLIENT_ID_HOMOLOGACAO: z
.string()
.min(1, 'environment variable "CLIENT_ID_HOMOLOGACAO" is missing'),
CLIENT_SECRET_HOMOLOGACAO: z
.string()
.min(1, 'environment variable "CLIENT_SECRET_HOMOLOGACAO" is missing'),
CLIENT_ID_PRODUCAO: z
.string()
.min(1, 'environment variable "CLIENT_ID_PRODUCAO" is missing'),
CLIENT_SECRET_PRODUCAO: z
.string()
.min(1, 'environment variable "CLIENT_SECRET_PRODUCAO" is missing'),
// SUPPORT VARIABLES
PIX_KEY: z
.string()
.min(1, 'environment variable "PIX_KEY" is missing'),
WEBHOOK_PIX: z
.string()
.min(1, 'environment variable "WEBHOOK_PIX" is missing'),
ACCOUNT_IDENTIFIER: z
.string()
.min(1, 'environment variable "ACCOUNT_IDENTIFIER" is missing'),
})
const _env = envSchema.safeParse(process.env)
if (!_env.success)
throw new Error(
`Environment variables error. Make sure that you have been created a ".env" file at the root of your project.
Also make sure that all environment variables have been set. See the documentation to learn about the environment variables that is required at "https://www.npmjs.com/package/@bruno-valero/gerencianet-sdk-typescript?activeTab=readme"
Error details:
${JSON.stringify(_env.error.format(), null, 2)}
`,
)
export const env = _env.dataPara poder utilizar as APIs da Efí Pay é necessário fornecer algumas credenciais que serão passadas através das Variáveis de Ambiente, vamos entender cada uma delas.
É necessário criar uma conta na gerencianet (Efí Pay) para poder obter as credenciais das APIs Efí Pay. Assista o vídeo que explica o processo de criação de contas se necessário.
Para ter acesso às suas credenciais é necessário criar um aplicativo. Ele representa uma conta dentro da Gerencianet que terá acesso às APIs da Efí Pay de forma que você pode ter diversos aplicativos, cada um contendo suas próprias credenciais e representando, por exemplo, um negócio aberto por você.
-
Vá até a aba API
-
Então crie uma aplicação
Depois de criada, acesse a aba Aplicações de suas APIs. Ela listará todas as suas aplicações criadas. Escolha a aplicação que você acabou de criar e então terá acesso às suas credenciais Client ID e Client Secret de Produção e de Homologação.
Com essas credenciais, alimente as Variáveis de Ambiente CLIENT_ID_HOMOLOGACAO, CLIENT_SECRET_HOMOLOGACAO e CLIENT_ID_PRODUCAO, CLIENT_SECRET_PRODUCAO. Lembrando que agora é possível gerá-las automaticamente através do SDK.
Acesse a aba Meus Certificados abaixo da aba Aplicações e então crie um certificado para Produção e outro para Homologação.
Ao criar um certificado, você receberá um arquivo que deve ser baixado no seu computador, certifique-se de não perder este arquivo, pois ele só pode ser baixado no momento da criação do certificado e não estará disponível para download posteriormente.
Salve o arquivo em algum lugar dentro do seu projeto e após fazer isso alimente as Variáveis de Ambiente CERTIFICADO_HOMOLOGACAO_PATH e CERTIFICADO_PRODUCAO_PATH com o caminho do arquivo onde você salvou os certificados, exemplo: "./src/certificados/homologacao.p12". Lembrando que agora é possível gerá-las automaticamente através do SDK.
Agora o SDK oferece uma forma de converter seus cerificados em formato base64.
Para realizar a conversão certifique-se de ter salvo os certificados em algum lugar em seu computador, então importe a classe EfiPay de @bruno-valero/gerencianet-sdk-typescript e use seu método estático generateBase64FromCertificate passando os caminhos onde os certificados estão salvos. Não é obrigatório passar os caminhos de todos os certificados, os que não forem preenchidos por você serão substituídas por valores dummy padrão.
Observe o exemplo:
import EfiPay from '@bruno-valero/gerencianet-sdk-typescript'
EfiPay.generateBase64FromCertificate({
certificadoHomologacaoPath: 'caminho/ate/o-certificado/de/homologacao.p12',
certificadoProducaoPath: 'caminho/ate/o-certificado/de/producao.p12',
})Caso o arquivo .env não exista na raiz do seu projeto, o SDK irá criá-lo após a execução do script de conversão, preenchendo todas as variáveis de ambiente com valores dummy padrão, exceto as variáveis que irão conter o conteúdo dos seus certificados convertidos em base64.
Caso o arquivo .env já exista na raiz do seu projeto, ao executar o script de conversão, o SDK irá preencher todas as variáveis de ambiente com valores já existentes (as variáveis de ambiente que não existirem no .env, serão preenchidas com valores dummy padrão), exceto as variáveis que irão conter o conteúdo dos seus certificados convertidos em base64.
Após criar o script que irá converter os certificados em em formato base64 conforme o exemplo de código acima, será necessário executá-lo para que os certificados sejam efetivamente convertidos.
Então para facilitar o trabalho, escreva o script em um arquivo na raiz do seu projeto chamado certificates-to-base64.js, agora basta abrir o terminal no diretório raiz do projeto e digitar o comando node ./certificates-to-base64.js
Para receber uma transação PIX é necessário criar uma chave PIX, que pode ser seu CPF, Número de Celular, Email ou uma Chave Aleatória.
Entre em sua conta da Efí Pay, vá até a aba Pix e escolha a opção Minhas Chaves então clique no botão Cadastrar Chave, escolha o tipo de chave, exemplo CPF, Email, etc. Por fim alimente a Variável de Ambiente PIX_KEY com o valor de sua chave.
Após cumprir estes passos, todas as credenciais necessárias para o funcionamento do sdk estão configuradas.
Para utilizar o SDK integrado ao typescript, basta importá-lo no arquivo e instanciar a classe EfiPay passando como parâmetro o tipo da conexão que pode ser "PRODUCTION" ou "SANDBOX", da seguinte forma:
import EfiPay from '@bruno-valero/gerencianet-sdk-typescript'
const efi = new EfiPay('SANDBOX')- Tipo "PRODUCTION": É a conexão com as APIs de Produção, ou seja, destinado a transações financeiras reais
- Tipo "SANDBOX": É a conexão com as APIs de Homologação, ou seja, destinado a transações financeiras fictícias
Agora é possível instanciar a classe EfiPay configurada para aceitar certificados em formato base64.
Caso você não tenha os certificados, veja como obtê-los e como convertê-los em formato base64.
Para utilizar o SDK com certificados em formato base64, basta ter feito o processo de conversão e instanciar a classe EfiPay passando a propriedade certificateType: "base64" da seguinte forma:
import EfiPay from '@bruno-valero/gerencianet-sdk-typescript'
const efi = new EfiPay('SANDBOX', { certificateType: 'base64' })Agora é possível instanciar a classe EfiPay configurada para aceitar certificados em formato Buffer.
Esta opção é útil, caso você não queira deixar o certificado salvo em sua aplicação, deixando-o hospedado num Amazon S3, Google Cloud Storage, entre outros.
Há duas formas de utilizar os certificados em formato Buffer:
-
- Instanciar a classe
EfiPaypassando diretamente o certificado em formato buffer, sem a utilização das variáveis de ambiente. Execute o código abaixo para obter oBufferde seu certificado através doconsole.log.
import EfiPay from '@bruno-valero/gerencianet-sdk-typescript' const efi = new EfiPay('SANDBOX', { client_id: 'meu_client_id', client_secret: 'meu_client_secret', // passe o Buffer aqui certificate: bufferDoCertificado, // indique que os certificados serão passados em formato Buffer certificateType: 'buffer', })
- Instanciar a classe
-
- Salvar o Buffer em formato
base64através do método estáticoEfiPay.generateBase64FromBufferCertificate. Esse método irá gerar um arquivo.envda mesma forma que é explicado aqui. Abaixo há um exemplo de como obter os dados a partir da url de download, transformar a resposta emBuffere com isso utilizar o métodoEfiPay.generateBase64FromBufferCertificate.
async function generateBase64FromBuffer() { const downloadUrlHomologacao = `your-certificate-download-url` const downloadUrlProducao = `your-certificate-download-url` const { data: dataHomologacao } = await axios.get(downloadUrlHomologacao, { responseType: 'blob', }) const { data: dataProducao } = await axios.get(downloadUrlProducao, { responseType: 'blob', }) const certificates = { homologacaoBuffer: Buffer.from(await dataHomologacao.arrayBuffer()), producaoBuffer: Buffer.from(await dataProducao.arrayBuffer()), } EfiPay.generateBase64FromBufferCertificate({ certificadoHomologacaoBuffer: certificates.homologacaoBuffer, certificadoProducaoBuffer: certificates.producaoBuffer, }) } generateBase64FromBuffer()
- Salvar o Buffer em formato
Agora é possível utilizar o SDK sem as variáveis de ambiente. Basta passar as credenciais manualmente, da seguinte forma:
import EfiPay from '@bruno-valero/gerencianet-sdk-typescript'
const efi = new EfiPay('SANDBOX', {
client_id: 'meu_client_id',
client_secret: 'meu_client_secret',
certificate: 'certificado de Homologacao em formato "base64"',
certificateType: 'base64',
})A API Pix Efí oferece recursos avançados para integração com sua aplicação, permitindo que você crie soluções personalizadas e ofereça opções de pagamento inovadoras aos seus clientes. É possível criar cobranças, verificar os Pix recebidos, devolver e enviar Pix.
Responsável pela gestão de cobranças imediatas. As cobranças, no contexto da API Pix representam uma transação financeira entre um pagador e um recebedor, cuja forma de pagamento é o Pix.
É possível dividir o recebimento do pix em até 20 pessoas, um exemplo de contexto onde isto seria útil é em casos que uma comissão deve ser pagada para um dos contribuintes de um serviço.
A divisão do recebimento pode ser feita após criar a cobrança imediata e antes do pagador realizar o envio. Para dividir, basta utilizar o split de pagamento pix
- Testes de Integração Realizados
Para entender mais sobre as cobranças imediatas, leia as anotações typescript do SDK ou visite a documentação oficial
Para utilizar as cobranças imediatas através do SDK acesse a propriedade imediateCharge da api PIX, dessa forma:
import EfiPay from '@bruno-valero/gerencianet-sdk-typescript'
const efi = new EfiPay('SANDBOX')
efi.pix.imediateCharge.create({
// passe os parâmetros necessários
})
efi.pix.imediateCharge.update({
// passe os parâmetros necessários
})
efi.pix.imediateCharge.findUnique({
// passe os parâmetros necessários
})
efi.pix.imediateCharge.findMany({
// passe os parâmetros necessários
})Responsável pela gestão de cobranças com vencimento. As cobranças, no contexto da API Pix, representam uma transação financeira entre um pagador e um recebedor, cuja forma de pagamento é o Pix.
É possível dividir o recebimento do pix em até 20 pessoas, um exemplo de contexto onde isto seria útil é em casos que uma comissão deve ser pagada para um dos contribuintes de um serviço.
A divisão do recebimento pode ser feita após criar a cobrança com vencimento e antes do pagador realizar o envio. Para dividir, basta utilizar o split de pagamento pix
- Testes de Integração Realizados
Para entender mais sobre as cobranças com vencimento, leia as anotações typescript do SDK ou visite a documentação oficial
Para utilizar as cobranças com vencimento através do SDK acesse a propriedade dueCharge da api PIX, dessa forma:
import EfiPay from '@bruno-valero/gerencianet-sdk-typescript'
const efi = new EfiPay('SANDBOX')
efi.pix.dueCharge.create({
// passe os parâmetros necessários
})
efi.pix.dueCharge.update({
// passe os parâmetros necessários
})
efi.pix.dueCharge.findUnique({
// passe os parâmetros necessários
})
efi.pix.dueCharge.findMany({
// passe os parâmetros necessários
})Traz as funcionalidades disponíveis para a gestão do Envio de Pix e do Pagamento de QR Codes Pix
- Testes de Integração Não Realizados
Para entender mais sobre as envio e pagamento pix, leia as anotações typescript do SDK ou visite a documentação oficial
Para utilizar as envio e pagamento pix através do SDK acesse a propriedade sendAndPayment da api PIX, dessa forma:
import EfiPay from '@bruno-valero/gerencianet-sdk-typescript'
const efi = new EfiPay('SANDBOX')
efi.pix.sendAndPayment.send({
// passe os parâmetros necessários
})Gerenciamento de notificações por parte do PSP recebedor a pessoa usuária recebedora.
- Testes de Integração Realizados
Para entender mais sobre as webhooks, leia as anotações typescript do SDK ou visite a documentação oficial
Para utilizar as webhooks através do SDK acesse a propriedade webhooks da api PIX, dessa forma:
import EfiPay from '@bruno-valero/gerencianet-sdk-typescript'
const efi = new EfiPay('SANDBOX')
efi.pix.webhooks.add({
// passe os parâmetros necessários
})
efi.pix.webhooks.findUnique({
// passe os parâmetros necessários
})
efi.pix.webhooks.findMany({
// passe os parâmetros necessários
})
efi.pix.webhooks.delete({
// passe os parâmetros necessários
})Gestão das transações Pix, isto é, a manutenção dos recebimentos e devoluções Pix.
- Testes de Integração Não Realizados
Para entender mais sobre as gestão de pix, leia as anotações typescript do SDK ou visite a documentação oficial
Para utilizar as gestão de pix através do SDK acesse a propriedade manage da api PIX, dessa forma:
import EfiPay from '@bruno-valero/gerencianet-sdk-typescript'
const efi = new EfiPay('SANDBOX')
efi.pix.manage.consult({
// passe os parâmetros necessários
})
efi.pix.manage.consultMany({
// passe os parâmetros necessários
})
efi.pix.manage.return({
// passe os parâmetros necessários
})
efi.pix.manage.consultReturn({
// passe os parâmetros necessários
})Destinado a lidar com configuração e remoção de locations para uso dos payloads.
- Testes de Integração Realizados
Para entender mais sobre as payload locations, leia as anotações typescript do SDK ou visite a documentação oficial
Para utilizar as payload locations através do SDK acesse a propriedade payloadLocations da api PIX, dessa forma:
import EfiPay from '@bruno-valero/gerencianet-sdk-typescript'
const efi = new EfiPay('SANDBOX')
efi.pix.payloadLocations.create({
// passe os parâmetros necessários
})
efi.pix.payloadLocations.findUnique({
// passe os parâmetros necessários
})
efi.pix.payloadLocations.findMany({
// passe os parâmetros necessários
})
efi.pix.payloadLocations.generateQrCode({
// passe os parâmetros necessários
})
efi.pix.payloadLocations.detachTxId({
// passe os parâmetros necessários
})Responsável pela gestão de cobranças em lote. As cobranças, no contexto da API Pix, representam uma transação financeira entre um pagador e um recebedor, cuja forma de pagamento é o Pix.
- Testes de Integração Realizados
Atenção - Ainda não foram realizados corretamente para o método updateDueChargeBatch
Para entender mais sobre as Cobranças em Lote, leia as anotações typescript do SDK ou visite a documentação oficial
Para utilizar as Cobranças em Lote através do SDK acesse a propriedade batchCollections da api PIX, dessa forma:
import EfiPay from '@bruno-valero/gerencianet-sdk-typescript'
const efi = new EfiPay('SANDBOX')
efi.pix.batchCollections.createOrUpdateDueChargeBatch({
// passe os parâmetros necessários
})
efi.pix.batchCollections.updateDueChargeBatch({
// passe os parâmetros necessários
})
efi.pix.batchCollections.findUniqueDueChargeBatch({
// passe os parâmetros necessários
})
efi.pix.batchCollections.findManyDueChargeBatch({
// passe os parâmetros necessários
})Realização do Split de pagamento na API Pix Efí. Responsável pela configuração dos Splits de pagamento na API Pix. As cobranças, no contexto da API Pix representam uma transação financeira entre um pagador e um recebedor, cuja forma de pagamento é o Pix.
É possível realizar a divisão do pagamento depois de criar uma cobrança imediata ou uma cobrança com vencimento.
O Split de pagamento Pix só pode ser realizado entre contas Efí, com limite máximo de 20 contas para o repasse.
Uma mesma configuração de Split pode ser utilizada em várias cobranças. Isso significa que você pode definir uma divisão de valores para um parceiro e aplicá-la em todas as cobranças relacionadas.
Você tem a flexibilidade de dividir o pagamento dos QR Codes e copia e cola estático entre diferentes contas Efí. Isso significa que, ao gerar um QR Code ou um código copia e cola estáticos para pagamento, você pode especificar como o valor recebido será distribuído, facilitando a gestão financeira e assegurando que os fundos sejam alocados corretamente desde o início.
No processo de split de pagamento, é essencial fornecer uma conta digital EFÍ válida. É importante destacar que não é possível realizar o split para a própria conta. Portanto, se estiver realizando testes em ambiente de homologação e não possuir uma conta válida para os repasses, será necessário criar uma subconta. Veja como fazer isso aqui.
- Testes de Integração Realizados
Para entender mais sobre as Split de pagamento Pix, leia as anotações typescript do SDK ou visite a documentação oficial
Para utilizar as Split de pagamento Pix através do SDK acesse a propriedade paymentSplit da api PIX, dessa forma:
import EfiPay from '@bruno-valero/gerencianet-sdk-typescript'
const efi = new EfiPay('SANDBOX')
efi.pix.paymentSplit.create({
// passe os parâmetros necessários
})
efi.pix.paymentSplit.findUnique({
// passe os parâmetros necessários
})
efi.pix.paymentSplit.attachImediateCharge({
// passe os parâmetros necessários
})
efi.pix.paymentSplit.findUniqueImediateChargeAttachment({
// passe os parâmetros necessários
})
efi.pix.paymentSplit.deleteImediateChargeAttachment({
// passe os parâmetros necessários
})
efi.pix.paymentSplit.attachDueCharge({
// passe os parâmetros necessários
})
efi.pix.paymentSplit.findUniqueDueChargeAttachment({
// passe os parâmetros necessários
})
efi.pix.paymentSplit.deleteDueChargeAttachment({
// passe os parâmetros necessários
})A API Cobranças Efí oferece recursos avançados que permitem emitir diferentes tipos de cobranças, tais como Boleto, Cartão de crédito, Carnê, Links de pagamento, Assinaturas (Recorrência) e Marketplace (Split de pagamento).
As transações online via cartão de crédito exigem apenas a numeração de face e o código no verso do cartão, o que pode resultar em transações suspeitas. Por isso, é importante adotar procedimentos de segurança para evitar prejuízos financeiros, como o Chargeback.
Quando uma transação com cartão de crédito é realizada, ela passa por três etapas: autorização da operadora, análise de segurança e captura. Cada transação é analisada para identificar possíveis riscos. Se for aprovada, o valor é debitado na fatura do cliente. Caso contrário, o valor fica reservado até que a comunicação reversa seja concluída e o limite do cartão seja reestabelecido.
As funcionalidades estão em desenvolvimento
- Visa
- Master
- AmericanExpress
- Elo
- Hipercard
Para fazer o pagamento com cartão de crédito, é necessário obter o payment_token da transação. Portanto, é imprescindível seguir os procedimentos para obter o payment_token conforme descrito no documento antes de criar a cobrança com cartão de crédito. Outra informação importante é você precisa cadastrar o ramo de atividade em sua conta. Confira mais detalhes aqui.
Se você precisa reutilizar o payment_token para fins de recorrência, utilize o atributo reuse com o valor booleano true. Dessa forma, o payment_token pode ser usado em mais de uma transação de forma segura, sem a necessidade de salvar os dados do cartão
A simulação de cobranças de cartão em ambiente de Homologação funciona com base na análise imediata de acordo com o último dígito do número do cartão de crédito utilizado:
- Cartão com final 1 retorna:
"reason":"Dados do cartão inválidos." - Cartão com final 2 retorna:
"reason":"Transação não autorizada por motivos de segurança." - Cartão com final 3 retorna:
"reason":"Transação não autorizada, tente novamente mais tarde." - Demais finais têm transação aprovada.
- Testes de Integração Não Realizados
Para entender mais sobre o Cartão, leia as anotações typescript do SDK ou visite a documentação oficial
Para utilizar o Cartão através do SDK acesse a propriedade card da api Cobranca, dessa forma:
import EfiPay from '@bruno-valero/gerencianet-sdk-typescript'
const efi = new EfiPay('SANDBOX')
efi.cobranca.card.['in development']({
// passe os parâmetros necessários
})