INTOPAYS SDK

Para mais informações, visite nosso site: Intopays

Contato

Como usar

npm install intopays

bun install intopays

Inicialização

Você pode inicializar a SDK da seguinte maneira:

import { Intopays } from "intopays";

const intopays = new Intopays({
  token: String(environment.test.TOKEN),
  mode: "production"
});

Parâmetros:

• token: (string): Token de autenticação fornecido pela Intopays.
• mode: (string): Ambiente da aplicação. Pode ser:
  • production: Ambiente de produção.
  • development: Ambiente de testes.

Retorno:

• IntopaysInstance: Objeto Intopays com acesso às funcionalidades do SDK, como pix, webhooks, etc.

Documentaçāo

• Pix
  • Criar Pix
  • Encontrar Pix
  • Pesquisar Pix
• Boleto
  • Criar Boleto
  • Encontrar Boleto
  • Pesquisar Boleto
  • Cancelar Boleto
• Webhook
  • Criar Webhook
  • Listar Webhooks
  • Pesquisar Webhooks
  • Excluir Webhooks
  • Webhook Signature
  • Recebimento de Evento de Boleto via Webhook
  • Recebimento de Evento PIX via Webhook

Pix

Criar pix

Você pode criar cobranças Pix utilizando o SDK de forma simples. para bancos Sicredi, Sicoob, Santander, Banco do Brasil enter outros.

Exemplo de Uso

import { Intopays, IntegrationEnum } from "intopays";

const intopays = new Intopays();
const payload = {
  calendarExpiration: 86400,
  debtorName: "Lucas Lopes",
  debtorDocument: "12345678901",
  amountOriginal: "10.99",
  amountModificationType: 0,
  payerRequest: "Cobrança de serviço",
  additionalInfos: [
    {
      name: "Campo 1",
      value: "Informação Adicional do PSP-Recebedor"
    }
  ],
  integrationType: IntegrationEnum.SICOOB
};

try {
  const response = await intopays.pix.create(payload);
  console.log("Pix gerado com sucesso:", response);
} catch (error) {
  console.error("Erro ao gerar Pix:", error);
}

Parâmetros:

• amountOriginal: O valor do pix (em reais).
• debtorName: Nome do pagador.
• debtorDocument: CPF/CNPJ do pagador.
• payerRequest: Descrição da cobrança.
• calendarExpiration: Tempo em segundos para expirar
• amountModificationType: Tipo de modificação no valor da cobrança.
• additionalInfos: Informações adicionais da cobrança, contendo nome e valor.
• integrationType: Tipo de integração (use o enum IntegrationEnum para escolher).

Retorno:

• Pix: Objeto com os dados da cobrança Pix, incluindo qrcode, location, status e url.

Encontrar Pix

Você pode encontrar um Pix existente usando o ID de pagamento.

Exemplo de Uso

import { Intopays } from "intopays";

const intopays = new Intopays();
const pixId = 123;

try {
  const response = await intopays.pix.find(pixId);
  console.log("Pix encontrado:", response);
} catch (error) {
  console.error("Erro ao encontrar Pix:", error);
}

Parâmetros:

• pixId: ID do Pix gerado anteriormente.

Retorno:

• Pix: Objeto com os dados da cobrança Pix, incluindo qrcode, location, status e url.

Pesquisar Pix

Você pode pesquisar um Pix por CPF/CNPJ, status ou data.

Exemplo de Uso

import { Intopays } from "intopays";

const intopays = new Intopays();

try {
  const response = await intopays.pix.search({
    debtorDocument: "12345678901",
    status: "ACTIVE"
  });
  console.log("Resultados da pesquisa:", response);
} catch (error) {
  console.error("Erro ao pesquisar Pix:", error);
}

Parâmetros:

• debtorDocument: (opcional): CPF ou CNPJ do pagador.
• status: (opcional): Status da cobrança (ex: ACTIVE, COMPLETED).

Retorno:

• Pix: Lista de cobranças Pix que atendem aos critérios. Objeto com os dados da cobrança Pix, incluindo qrcode, location, status e url.

Boleto

Criar boleto

Você pode criar boletos utilizando o SDK, com opções de integração com bancos como Banco do Brasil, Bradesco, Itaú, entre outros.

Exemplo de Uso

import { Intopays, StateEnum, DiscountEnum, InterestEnum, FineTypeEnum, IntegrationEnum } from "intopays";

const intopays = new Intopays();

// Criação de um boleto
const boleto = new Boleto({
  amount: 2.51,
  dueDate: new Date(),
  daysAfterDueDateForCancellation: 30,
  payerDocument: "000.000.000-00",
  payerName: "Luffrs",
  payerEmail: "[email protected]",
  payerPhone: "51999999999",
  payerZipCode: "91760110",
  payerNumber: "123",
  payerComplement: "Apto 123",
  payerNeighborhood: "Centro",
  payerCity: "Salto",
  payerState: StateEnum.AC,
  payerAddress: "Rua Principal",
  messageLine1: "Message line 1",
  messageLine2: "Message line 2",
  discount1Code: DiscountEnum.NO_DISCOUNT,
  discount1Rate: 0,
  discount1Value: 0,
  discount1Date: new Date(),
  discount2Code: DiscountEnum.NO_DISCOUNT,
  discount2Rate: 0,
  discount2Value: 10,
  discount2Date: new Date(),
  fineCode: FineTypeEnum.NO_FINE,
  fineDate: null,
  fineValue: 0,
  fineRate: 0,
  interestCode: InterestEnum.EXEMPT,
  interestDate: null,
  interestRate: 0,
  interestValue: 0,
  finalBeneficiaryName: "Final Beneficiary",
  finalBeneficiaryDocument: "111.111.111-11",
  finalBeneficiaryZipCode: "98765432",
  finalBeneficiaryAddress: "Rua Final",
  finalBeneficiaryNeighborhood: "Bairro Final",
  finalBeneficiaryCity: "Final City", 
  finalBeneficiaryState: StateEnum.AC,
  integrationType: IntegrationEnum.SICOOB
});

// Envio do boleto para a criação
try {
  const response = await intopays.boleto.create(boleto);
  console.log("Boleto gerado com sucesso:", response);
} catch (error) {
  console.error("Erro ao gerar Boleto:", error);
}

Parâmetros:

• amount: O valor do boleto (em reais).
• dueDate: A data de vencimento do boleto.
• daysAfterDueDateForCancellation: Número de dias após o vencimento para cancelamento do boleto.
• payerDocument: O CPF ou CNPJ do pagador.
• payerName: Nome do pagador.
• payerEmail: E-mail do pagador.
• payerPhone: Telefone do pagador.
• payerZipCode: CEP do pagador.
• payerNumber: Número do endereço do pagador.
• payerComplement: Complemento do endereço do pagador.
• payerNeighborhood: Bairro do pagador.
• payerCity: Cidade do pagador.
• payerState: Estado do pagador (use o enum StateEnum para escolher).
• payerAddress: Endereço do pagador.
• messageLine1: Mensagem personalizada (linha 1).
• messageLine2: Mensagem personalizada (linha 2).
• discount1Code: Código do desconto 1 (use o enum DiscountEnum para escolher).
• discount1Rate: Taxa de desconto 1.
• discount1Value: Valor do desconto 1.
• discount1Date: Data do desconto 1.
• discount2Code: Código do desconto 2 (use o enum DiscountEnum para escolher).
• discount2Rate: Taxa de desconto 2.
• discount2Value: Valor do desconto 2.
• discount2Date: Data do desconto 2.
• fineCode: Código de multa (use o enum FineTypeEnum para escolher).
• fineDate: Data da multa.
• fineValue: Valor da multa.
• fineRate: Taxa da multa.
• interestCode: Código de juros (use o enum InterestEnum para escolher).
• interestDate: Data dos juros.
• interestRate: Taxa de juros.
• interestValue: Valor dos juros.
• finalBeneficiaryName: Nome do beneficiário final.
• finalBeneficiaryDocument: CPF ou CNPJ do beneficiário final.
• finalBeneficiaryZipCode: CEP do beneficiário final.
• finalBeneficiaryAddress: Endereço do beneficiário final.
• finalBeneficiaryNeighborhood: Bairro do beneficiário final.
• finalBeneficiaryCity: Cidade do beneficiário final.
• finalBeneficiaryState: Estado do beneficiário final (use o enum StateEnum para escolher).
• integrationType: Tipo de integração (use o enum IntegrationEnum para escolher).

Retorno:

Boleto: Objeto contendo os dados da cobrança do boleto, incluindo barcode, boletoUrl, dueDate, amount, status, entre outros.

Encontrar Boleto

Você pode encontrar um boleto específico utilizando seu ID com o SDK de forma simples.

Exemplo de Uso

import { Intopays } from "intopays";

const intopays = new Intopays();

try {
  const response = await intopays.boleto.find(123);
  console.log("Boleto encontrado:", response);
} catch (error) {
  console.error("Erro ao encontrar boleto:", error);
}

Parâmetros:

• id: ID do boleto que será encontrado. Este ID é retornado ao criar o boleto.

Retorno:

• Boleto: Objeto contendo os dados do boleto, como id, amount, dueDate, status e outros detalhes relacionados.

Cancelar Boleto

Você pode cancelar uma cobrança de boleto utilizando o SDK de forma simples.

Exemplo de Uso

import { Intopays } from "intopays";

const intopays = new Intopays();

try {
  const response = await intopays.boleto.void(123);
  console.log("Boleto cancelado com sucesso:", response);
} catch (error) {
  console.error("Erro ao cancelar boleto:", error);
}

Parâmetros:

• id: ID do boleto que será cancelado. Este ID é retornado ao criar o boleto.

Retorno:

• Boleto: Objeto com a confirmação do cancelamento do boleto, incluindo o status da operação e a mensagem de sucesso ou erro.

Pesquisar Boleto

Você pode pesquisar boletos com base em diferentes critérios usando o SDK de forma simples.

Exemplo de Uso

import { Intopays } from "intopays";

const intopays = new Intopays();

try {
  const response = await intopays.boleto.search({
  payerName: "Luffrs",
  dueDate: "2025-05-01"
});
  console.log("Boletos encontrados:", response);
} catch (error) {
  console.error("Erro ao pesquisar boletos:", error);
}

Parâmetros:

• payerName: Nome do pagador (opcional).
• dueDate: Data de vencimento do boleto (opcional).
• status: Status do boleto, como "PENDENTE", "PAGO", etc. (opcional).

Retorno:

• Array<Boleto>: Lista de objetos que representam os boletos encontrados com os critérios de pesquisa. Cada objeto de boleto pode incluir informações como id, amount, dueDate, payerName, status, entre outros detalhes.

Webhook

Criar Webhook

Você pode criar um webhook usando a função create do objeto intopays.webhooks.

Exemplo de Uso

import { Intopays } from "intopays";

const intopays = new Intopays();
const payload = {
  endpoint: "https://exemple.intopays.com/webhooks"
};

try {
  const response = await intopays.webhook.create(payload);
  console.log("Webhook criado com sucesso:", response);
} catch (error) {
  console.error("Erro ao criar webhook:", error);
}

Parâmetros:

• payload.endpoint: Endpoint responsável por receber eventos via webhook.

Retorno:

• Webhook: Objeto que representa um webhook.

Listar Webhooks

Você pode listar todos os webhooks registrados usando a função find do objeto intopays.webhooks.

Exemplo de Uso

import { Intopays } from "intopays";

const intopays = new Intopays();

try {
  const response = await intopays.webhook.find();
  console.log("Webhooks encontrados:", response);
} catch (error) {
  console.error("Erro ao listar webhooks:", error);
}

Retorno:

• Array<Webhook>: Lista de objetos que representam webhooks.

Pesquisar Webhooks

Você também pode pesquisar webhooks por endpoint usando a função find do objeto intopays.webhooks.

Exemplo de Uso

import { Intopays } from "intopays";

const intopays = new Intopays();
const endpoint = "https://exemple.intopays.com/webhooks";

try {
  const response = await intopays.webhook.find({ endpoint });
  console.log("Webhooks encontrados com o endpoint especificado:", response);
} catch (error) {
  console.error("Erro ao pesquisar webhooks:", error);
}

Parâmetros:

• endpoint: Endpoint a ser especificado durante a consulta..

Retorno:

• Array<Webhook>: Lista de objetos que representam webhooks.

Excluir Webhooks

Você pode excluir um webhook usando a função delete do objeto intopays.webhooks.

Exemplo de Uso

import { Intopays } from "intopays";

const intopays = new Intopays();

try {
  const webhookId = 0;
  const response = await intopays.webhook.delete(webhookId);
  console.log("Webhook excluído com sucesso:", response);
} catch (error) {
  console.error("Erro ao excluir webhook:", error);
}

Parâmetros:

• webhookId: ID do webhook a ser deletado.

Retorno:

• void: Sem retorno após a exclusão do webhook

Verificação da Assinatura do Webhook

Este SDK fornece uma maneira simples de verificar a assinatura de um webhook recebido. Você pode usar a função verifySignature do objeto intopays.webhooks para verificar se a assinatura do webhook é válida.

Webhook Signature:

Exemplo de Uso

import { Intopays } from "intopays";

const intopays = new Intopays();
const xWebhookSignature = request.headers["x-webhook-signature"];
const signature = "c1a4b404-ac83-4378-b60f-9be9bac1fc80";
const isValid = intopays.webhook.verifySignature(request.body, xWebhookSignature, signature);

if (isValid) {
    console.log("Assinatura do webhook válida");
} else {
    console.log("Assinatura do webhook inválida");
}

Parâmetros:

• request.body: O corpo do webhook recebido.
• xWebhookSignature: A assinatura recebida nos cabeçalhos do webhook.
• signature: A assinatura esperada para verificar a validade.

Retorno:

• true: Se a assinatura do webhook for válida.
• false: Se a assinatura do webhook for inválida.

Certifique-se de substituir "c1a4b404-ac83-4378-b60f-9be9bac1fc80" pela sua própria chave de assinatura.

Recebimento de Evento de Boleto via Webhook

{
  "type": "BOLETO",
  "boleto": {
    "id": 22,
    "amount": 120,
    "dueDate": "2024-07-20T00:00:00.000Z",
    "daysAfterDueDateForCancellation": 30,
    "payerDocument": "12345678910",
    "payerName": "Cliente Exemplo",
    "payerEmail": "[email protected]",
    "payerPhone": "(11) 98765-4321",
    "payerZipCode": "12345-678",
    "payerNumber": "123",
    "payerComplement": "Sala 101",
    "payerNeighborhood": "Centro",
    "payerCity": "São Paulo",
    "payerState": "SP",
    "payerAddress": "Rua Exemplo, 123",
    "messageLine1": "Mensagem opcional",
    "messageLine2": "Outra mensagem opcional",
    "discount1Code": "NO_DISCOUNT",
    "discount1Rate": 0,
    "discount1Value": 0,
    "discount1Date": null,
    "discount2Code": "NO_DISCOUNT",
    "discount2Rate": 0,
    "discount2Value": 0,
    "discount2Date": null,
    "fineCode": "NO_FINE",
    "fineDate": null,
    "fineRate": 0,
    "fineValue": 0,
    "interestCode": "EXEMPT",
    "interestDate": null,
    "interestRate": 0,
    "interestValue": 0,
    "finalBeneficiaryName": null,
    "finalBeneficiaryDocument": null,
    "finalBeneficiaryZipCode": null,
    "finalBeneficiaryAddress": null,
    "finalBeneficiaryNeighborhood": null,
    "finalBeneficiaryCity": null,
    "finalBeneficiaryState": null,
    "status": "OPEN",
    "barcode": "12345678901234567890123456789012345678901234",
    "digitableLine": "1234567890123456789012345678901212345678901234",
    "qrcode": "EXAMPLE_QRCODE_STRING",
    "referenceCode": "EXAMPLE_REFERENCE_CODE",
    "integrationBankingCode": 123456,
    "integrationType": "SICOOB",
    "createdAt": "2024-07-01T10:00:00.000Z",
    "updatedAt": "2024-07-01T10:00:00.000Z"
  },
  "updatedAt": "2024-07-01T10:00:00.000Z",
  "integrationError": null,
  "id": 23,
  "createdAt": "2024-07-01T10:00:00.000Z"
}

Recebimento de Evento PIX via Webhook

{
  "type": "PIX",
  "pix": {
    "id": 27,
    "transactionId": "YYYINTOPAYSYYYSICOOBYYYPIXXXXXXXXX27",
    "transactionEndId": null,
    "calendarCreation": "2024-08-20T10:30:45.789Z",
    "calendarExpiration": 86400,
    "revision": null,
    "locId": null,
    "locLocation": null,
    "locType": null,
    "location": "pix.sicoob.com.br/qr/payload/v2/3e9b2c6f-85cd-4fc4-9123-20d5434c38f9",
    "status": "ACTIVE",
    "debtorName": "Cliente Exemplo",
    "debtorDocument": "12345678910",
    "amountOriginal": 100.99,
    "amountModificationType": 0,
    "pixKey": "98765432-1234-5678-90ab-cdef12345678",
    "qrcode": "00020101021226900014br.gov.bcb.pix2568pix.sicoob.com.br/qr/payload/v2/3e9b2c6f-85cd-4fc4-9123-20d5434c38f905204000053039865802BR5923Cliente Exemplo6013Nao_informado62070503***63048315",
    "url": "https://app.intopays.com/v1/pix-payment/YYYINTOPAYSYYYSICOOBYYYPIXXXXXXXXX27",
    "payerRequest": "Pagamento do serviço",
    "integrationType": "SICOOB",
    "createdAt": "2024-08-20T10:30:43.214Z",
    "updatedAt": "2024-08-20T10:30:45.821Z",
    "additionalInfos": []
  },
  "updatedAt": "2024-08-20T10:30:45.874Z",
  "integrationError": null,
  "id": 33,
  "createdAt": "2024-08-20T10:30:45.878Z"
}