Package Exports

membros-sdk
membros-sdk/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (membros-sdk) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

@membros/node-sdk

Official Node.js SDK for Membros - Brazilian payment processing made simple.

Features

🇧🇷 Brazilian-First: Built-in CPF/CNPJ validation and formatting
💳 PIX Support: Native PIX payment creation and QR code generation
🔒 Type Safe: Full TypeScript support with comprehensive type definitions
🚀 Promise-Based: Modern async/await API
🔄 Auto-Retry: Automatic retry logic for failed requests
📱 Multi-Payment: Support for PIX, credit cards, and boleto
🛡️ Error Handling: Descriptive error classes with proper status codes

Installation

npm install @membros/node-sdk
# or
yarn add @membros/node-sdk

Quick Start

import Membros from '@membros/node-sdk';

// Initialize the client
const membros = new Membros('sk_test_...', {
  projectId: 'your-project-id'
});

// Create a PIX payment
const order = await membros.orders.createPix({
  customer: {
    name: 'João Silva',
    email: 'joao@example.com',
    document: '123.456.789-00'
  },
  items: [{
    description: 'Personal Training Session',
    amount: 15000, // R$ 150.00 in cents
    quantity: 1
  }],
  expires_in: 3600 // 1 hour
});

console.log(order.pix_qr_code); // QR code for payment

Configuration

const membros = new Membros('sk_test_...', {
  projectId: 'your-project-id',        // Required
  apiUrl: 'https://api.membros.com',   // Optional (defaults to production)
  timeout: 30000,                      // Optional (30 seconds)
  maxRetries: 3,                       // Optional (3 retries)
  version: 'v1',                       // Optional (API version)
  userAgent: 'my-app/1.0.0'           // Optional (custom user agent)
});

API Reference

Customers

Create Customer

const customer = await membros.customers.create({
  name: 'João Silva',
  email: 'joao@example.com',
  document: '123.456.789-00',
  phones: {
    mobile_phone: {
      country_code: '55',
      area_code: '11',
      number: '999999999'
    }
  },
  address: {
    street: 'Rua das Flores',
    number: '123',
    neighborhood: 'Centro',
    city: 'São Paulo',
    state: 'SP',
    zip_code: '01234-567'
  }
});

Retrieve Customer

const customer = await membros.customers.retrieve('customer_id');

Update Customer

const customer = await membros.customers.update('customer_id', {
  name: 'João Santos Silva',
  email: 'joao.santos@example.com'
});

List Customers

const customers = await membros.customers.list({
  limit: 10,
  offset: 0,
  email: 'joao@example.com'
});

Orders

Create PIX Order

const order = await membros.orders.createPix({
  customer: {
    name: 'João Silva',
    email: 'joao@example.com',
    document: '123.456.789-00'
  },
  items: [{
    description: 'Personal Training Session',
    amount: 15000, // R$ 150.00 in cents
    quantity: 1
  }],
  expires_in: 3600 // 1 hour
});

Create Credit Card Order

const order = await membros.orders.createCreditCard({
  customer: 'customer_id', // or customer object
  items: [{
    description: 'Monthly Subscription',
    amount: 9900, // R$ 99.00 in cents
    quantity: 1
  }],
  card_token: 'card_token_from_frontend',
  installments: 1
});

Create Boleto Order

const order = await membros.orders.createBoleto({
  customer: {
    name: 'João Silva',
    email: 'joao@example.com',
    document: '123.456.789-00'
  },
  items: [{
    description: 'Product Purchase',
    amount: 25000, // R$ 250.00 in cents
    quantity: 1
  }],
  expires_in: 259200 // 3 days
});

Retrieve Order

const order = await membros.orders.retrieve('order_id');

List Orders

const orders = await membros.orders.list({
  limit: 10,
  customer_id: 'customer_id',
  status: 'paid'
});

Cancel Order

const order = await membros.orders.cancel('order_id', 'Customer requested cancellation');

Refund Order

const refund = await membros.orders.refund('order_id', {
  amount: 5000, // Partial refund of R$ 50.00
  reason: 'Partial service not delivered'
});

Get PIX QR Code

const pixData = await membros.orders.getPixQrCode('order_id');
console.log(pixData.qr_code); // QR code string
console.log(pixData.qr_code_url); // URL to QR code image

Get Boleto

const boletoData = await membros.orders.getBoleto('order_id');
console.log(boletoData.boleto_url); // PDF URL
console.log(boletoData.barcode); // Barcode number

Error Handling

The SDK provides comprehensive error handling with specific error types:

import { 
  MembrosError,
  MembrosAPIError,
  MembrosAuthenticationError,
  MembrosValidationError,
  MembrosNetworkError,
  MembrosRateLimitError
} from '@membros/node-sdk';

try {
  const order = await membros.orders.createPix({
    // ... order data
  });
} catch (error) {
  if (error instanceof MembrosAuthenticationError) {
    console.log('Authentication failed:', error.message);
  } else if (error instanceof MembrosValidationError) {
    console.log('Validation error:', error.message);
    console.log('Details:', error.details);
  } else if (error instanceof MembrosRateLimitError) {
    console.log('Rate limit exceeded, retry after:', error.statusCode);
  } else {
    console.log('Unexpected error:', error.message);
  }
}

Brazilian Document Validation

The SDK includes built-in Brazilian document validation:

import { validateCPF, validateCNPJ, formatDocument } from '@membros/node-sdk';

// Validate CPF
const isValidCPF = validateCPF('123.456.789-00'); // true/false

// Validate CNPJ
const isValidCNPJ = validateCNPJ('12.345.678/0001-00'); // true/false

// Format document
const formatted = formatDocument('12345678900'); // '123.456.789-00'

Webhook Handling

Handle webhook events from Membros:

import express from 'express';
import crypto from 'crypto';

const app = express();

app.post('/webhooks/membros', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-membros-signature'];
  const payload = req.body;
  
  // Verify webhook signature
  const expectedSignature = crypto
    .createHmac('sha256', process.env.MEMBROS_WEBHOOK_SECRET)
    .update(payload)
    .digest('hex');
  
  if (signature !== expectedSignature) {
    return res.status(400).send('Invalid signature');
  }
  
  const event = JSON.parse(payload);
  
  switch (event.type) {
    case 'charge.paid':
      console.log('Payment successful:', event.data);
      break;
    case 'charge.payment_failed':
      console.log('Payment failed:', event.data);
      break;
    case 'order.cancelled':
      console.log('Order cancelled:', event.data);
      break;
  }
  
  res.status(200).send('OK');
});

TypeScript Support

The SDK is built with TypeScript and provides comprehensive type definitions:

import { Customer, Order, OrderStatus } from '@membros/node-sdk';

// Full type safety
const customer: Customer = await membros.customers.create({
  name: 'João Silva',
  email: 'joao@example.com',
  document: '123.456.789-00'
});

// Type-safe order status
const status: OrderStatus = 'paid';

Contributing

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

📧 Email: support@membros.com
📖 Documentation: https://docs.membros.com
🐛 Issues: https://github.com/membros/node-sdk/issues

Made with ❤️ by the Membros team