Satim Payment Gateway Integration

Integre com o gateway de pagamento SATIM da Argélia para processar pagamentos com cartões CIB e Edhahabia.

GitHub
15

Documentação

Obviamente, você já deve ter uma conta criada e funcionando para obter as credenciais daqui: https://cibweb.dz/fr/login

Integração com o Gateway de Pagamento Satim

Um servidor Model Context Protocol (MCP) para integração com o gateway de pagamento SATIM na Argélia. O servidor fornece uma interface estruturada para processar pagamentos com cartões CIB/Edhahabia através da plataforma SATIM-ePAY. Este pacote permite que assistentes de IA como Cursor, Claude e Copilot acessem diretamente os dados da sua conta por meio de uma interface padronizada.

Satim Payment Gateway Integration MCP server

Início Rápido

# Clone the repository
git clone https://github.com/zakblacki/Satim-Payment-Gateway-Integration.git
cd satim-payment-gateway-integration

# Install dependencies
npm install

# Run the server
npx tsx satim-mcp-server.ts
or
npm run dev

# Demo 
Launch index.html

image

Sumário

  1. Instalação
  2. Configuração
  3. Fluxo de Pagamento
  4. Ferramentas
  5. Testes
  6. Requisitos de Integração
  7. Tratamento de Erros
  8. Exemplos
  9. Considerações de Segurança

Instalação

Pré-requisitos

  • Node.js 18+
  • npm ou yarn

Configuração Passo a Passo

  1. Clone e entre no diretório do projeto:
git clone https://github.com/zakblacki/Satim-Payment-Gateway-Integration.git
cd satim-payment-gateway-integration
  1. Inicialize o projeto (se o package.json não existir):
npm init -y
  1. Configure o package.json para módulos ES:
npm pkg set type=module
  1. Instale as dependências:
# Core dependencies
npm install @modelcontextprotocol/sdk axios

# Development dependencies
npm install --save-dev typescript @types/node tsx

Executando o Servidor

Opção 1: Execução direta com tsx (Recomendado para desenvolvimento)

npx tsx satim-mcp-server.ts

Opção 2: Compilar e executar

# Compile TypeScript
npm run build

# Run compiled JavaScript
npm start

Opção 3: Modo de desenvolvimento com recarga automática

npm run dev

Configuração

Configuração do Cliente MCP

Para usar este servidor com um cliente MCP (como o Claude Desktop), adicione à sua configuração:

{
  "mcpServers": {
      "satim-payment": {
       "command": "npx",
       "args": ["@devqxi/satim-payment-gateway-mcp"],
       "env": {
        "SATIM_USERNAME": "your_test_username",
        "SATIM_PASSWORD": "your_test_password",
        "NODE_ENV": "development"
      }
    }
  }
}

Configuração Inicial

Antes de usar qualquer ferramenta de pagamento, configure suas credenciais SATIM:

// Configure credentials
await mcp.callTool("configure_credentials", {
  userName: "your_merchant_username",
  password: "your_merchant_password"
});

Variáveis de Ambiente

Para produção, considere usar variáveis de ambiente:

SATIM_USERNAME=your_merchant_username
SATIM_PASSWORD=your_merchant_password
SATIM_TERMINAL_ID=your_terminal_id
SATIM_BASE_URL=https://test.satim.dz/payment/rest  # or https://satim.dz/payment/rest for production

Fluxo de Pagamento

O processo completo de pagamento segue estas etapas:

1. Registro do Pedido

const registrationResult = await mcp.callTool("register_order", {
  orderNumber: "ORDER_001_2024",
  amountInDA: 1500.50,  // Amount in Algerian Dinars
  returnUrl: "https://yoursite.com/payment/success",
  failUrl: "https://yoursite.com/payment/failure",
  force_terminal_id: "E005005097",
  udf1: "merchant_ref_123",
  language: "FR"
});

// Response includes orderId and formUrl
// Redirect customer to formUrl for payment

2. Pagamento do Cliente

  • O cliente preenche os dados do cartão CIB/Edhahabia no formulário SATIM
  • O cliente é redirecionado de volta para o seu returnUrl/failUrl

3. Confirmação do Pedido

const confirmResult = await mcp.callTool("confirm_order", {
  orderId: "received_order_id",
  language: "FR"
});

// Validate the response
const validation = await mcp.callTool("validate_payment_response", {
  response: confirmResult
});

4. Exibição dos Resultados

Com base nos resultados da validação, exiba mensagens apropriadas aos clientes.

Ferramentas

configure_credentials

Configura as credenciais do gateway SATIM.

Parâmetros:

  • userName (string, obrigatório): Login do comerciante
  • password (string, obrigatório): Senha do comerciante

register_order

Registra um novo pedido de pagamento.

Parâmetros:

  • orderNumber (string, obrigatório): Identificador único do pedido
  • amountInDA (número, obrigatório): Valor em Dinares Argelinos (mín: 50 DA)
  • returnUrl (string, obrigatório): URL de redirecionamento em caso de sucesso
  • failUrl (string, opcional): URL de redirecionamento em caso de falha
  • force_terminal_id (string, obrigatório): ID do terminal atribuído pelo banco
  • udf1 (string, obrigatório): Parâmetro específico do SATIM
  • currency (string, opcional): Código da moeda (padrão: "012" para DZD)
  • language (string, opcional): Idioma da interface ("AR", "FR", "EN")
  • description (string, opcional): Descrição do pedido
  • udf2-udf5 (string, opcional): Parâmetros adicionais

Resposta:

{
  "orderId": "123456789AZERTYUIOPL",
  "formUrl": "https://test.satim.dz/payment/merchants/merchant1/payment_fr.html?mdOrder=123456789AZERTYUIOPL"
}

confirm_order

Confirma o status do pedido após a tentativa de pagamento.

Parâmetros:

  • orderId (string, obrigatório): ID do pedido do registro
  • language (string, opcional): Idioma da resposta

Resposta:

{
  "orderNumber": "ORDER_001_2024",
  "actionCode": 0,
  "actionCodeDescription": "Votre paiement a été accepté",
  "amount": 150050,
  "errorCode": "0",
  "orderStatus": 2,
  "approvalCode": "303004",
  "params": {
    "respCode": "00",
    "respCode_desc": "Votre paiement a été accepté"
  }
}

refund_order

Processa um reembolso para um pedido concluído.

Parâmetros:

  • orderId (string, obrigatório): ID do pedido a ser reembolsado
  • amountInDA (número, obrigatório): Valor do reembolso em DA
  • currency (string, opcional): Código da moeda
  • language (string, opcional): Idioma da resposta

Resposta:

{
  "errorCode": 0
}

validate_payment_response

Valida e interpreta a resposta do pagamento.

Parâmetros:

  • response (objeto, obrigatório): Resposta da confirmação do pedido

Resposta:

{
  "status": "ACCEPTED",
  "displayMessage": "Votre paiement a été accepté",
  "shouldShowContactInfo": false,
  "contactNumber": "3020 3020"
}

Testes

Método 1: Teste Rápido

Crie um arquivo de teste simples test-simple.js:

import { spawn } from 'child_process';

// Start the MCP server
const server = spawn('npx', ['tsx', 'satim-mcp-server.ts'], {
  stdio: ['pipe', 'pipe', 'inherit']
});

console.log('SATIM MCP Server started for testing');

// Let it run for a few seconds then exit
setTimeout(() => {
  server.kill();
  console.log('Test completed');
}, 5000);

Execute com:

node test-simple.js

Método 2: Teste de Integração Completo

Crie test-client.ts seguindo o exemplo na documentação e execute:

npm run test

Método 3: Wrapper HTTP para Testes de API

Use o exemplo de wrapper HTTP fornecido na documentação para criar endpoints de API REST para facilitar os testes com ferramentas como Postman ou curl.

Solução de Problemas

Problemas Comuns e Soluções

  1. "Cannot use import statement outside a module"

    # Make sure package.json has "type": "module"
npm pkg set type=module

  2. Erros de "Module not found"

    # Reinstall dependencies
rm -rf node_modules package-lock.json
npm install

  3. Erros de compilação TypeScript

    # Check tsconfig.json configuration
# Make sure all dependencies are installed
npm install --save-dev @types/node

  4. Problemas de conexão com o servidor

    # Check if server is running
ps aux | grep tsx

# Check for port conflicts
lsof -i :3000  # if using HTTP wrapper

Modo de Depuração

Ative o registro de depuração:

DEBUG=true npx tsx satim-mcp-server.ts

Requisitos de Integração

Segurança SSL

  • Obrigatório: Seu site deve ter certificado SSL
  • Todas as chamadas de API devem usar HTTPS

Requisitos de Interface do Usuário

Página de Pagamento

  • Exiba o valor final em destaque (negrito, fonte maior)
  • Inclua CAPTCHA para evitar envios automatizados
  • Mostre o logotipo CIB no botão de pagamento
  • Exiba os termos e condições com confirmação do cliente
  • Redirecione para a página SATIM em uma janela independente do navegador

Exibição da Página de Sucesso

Para pagamentos aceitos, mostre:

  • Mensagem da transação (respCode_desc)
  • ID da transação (orderId)
  • Número do pedido (orderNumber)
  • Código de autorização (approvalCode)
  • Data/hora da transação
  • Valor do pagamento com moeda
  • Método de pagamento (CIB/Edhahabia)
  • Contato SATIM: 3020 3020

Ações da Página de Sucesso

  • Opção de imprimir recibo
  • Baixar recibo em PDF
  • Enviar recibo em PDF por e-mail para terceiros

Página de Rejeição

  • Exiba a mensagem de rejeição em três idiomas
  • Mostre as informações de contato do SATIM

Tratamento de Valores

Os valores devem ser multiplicados por 100 ao serem enviados ao SATIM:

  • 50,00 DA → enviar 5000
  • 806,50 DA → enviar 80650

O servidor MCP lida com essa conversão automaticamente.

Tratamento de Erros

Erros de Registro de Pedido

  • Credenciais inválidas
  • Número de pedido duplicado
  • Valor inválido (< 50 DA)
  • Parâmetros obrigatórios ausentes

Erros de Confirmação

Código de ErroDescrição
0Confirmado com sucesso
1ID do pedido vazio
2Já confirmado
3Acesso negado
5Acesso negado
6Pedido desconhecido
7Erro do sistema

Erros de Reembolso

Código de ErroDescrição
0Sem erro do sistema
5Alteração de senha necessária / ID do pedido vazio
6Número do pedido incorreto
7Erro no estado do pagamento / Erro de valor / Erro do sistema

Exemplos

Fluxo de Pagamento Completo

// 1. Configure credentials
await mcp.callTool("configure_credentials", {
  userName: "test_merchant",
  password: "test_password"
});

// 2. Register order
const order = await mcp.callTool("register_order", {
  orderNumber: `ORDER_${Date.now()}`,
  amountInDA: 250.75,
  returnUrl: "https://mystore.dz/payment/success",
  failUrl: "https://mystore.dz/payment/failure",
  force_terminal_id: "E005005097",
  udf1: "customer_ref_456",
  language: "FR",
  description: "Achat produit électronique"
});

// 3. Redirect customer to order.formUrl
// Customer completes payment and returns

// 4. Confirm payment
const confirmation = await mcp.callTool("confirm_order", {
  orderId: order.orderId,
  language: "FR"
});

// 5. Validate response
const validation = await mcp.callTool("validate_payment_response", {
  response: confirmation
});

// 6. Handle result
if (validation.status === "ACCEPTED") {
  // Process successful payment
  console.log("Payment successful:", validation.displayMessage);
} else if (validation.status === "REJECTED") {
  // Handle rejection
  console.log("Payment rejected");
} else {
  // Handle error
  console.log("Payment error:", validation.displayMessage);
}

Processando Reembolsos

// Full refund
const refund = await mcp.callTool("refund_order", {
  orderId: "123456789AZERTYUIOPL",
  amountInDA: 250.75,  // Full original amount
  language: "FR"
});

// Partial refund
const partialRefund = await mcp.callTool("refund_order", {
  orderId: "123456789AZERTYUIOPL",
  amountInDA: 100.00,  // Partial amount
  language: "FR"
});

Considerações de Segurança

Gerenciamento de Credenciais

  • Armazene as credenciais com segurança (variáveis de ambiente, cofre de chaves)
  • Use HTTPS para todas as comunicações
  • Implemente autenticação adequada para seus endpoints de API

Segurança do Número do Pedido

  • Use números de pedido únicos e não sequenciais
  • Inclua carimbo de data/hora ou elementos aleatórios
  • Valide a propriedade do pedido antes da confirmação

Validação de Dados

  • Sempre valide os valores no lado do servidor
  • Verifique o status do pedido antes de processar confirmações
  • Implemente idempotência para operações de reembolso

Registro e Monitoramento

  • Registre todas as transações de pagamento
  • Monitore atividades suspeitas
  • Implemente limite de taxa para chamadas de API

Implantação em Produção

Configuração do Ambiente

# Production endpoints
SATIM_BASE_URL=https://satim.dz/payment/rest

# Development/Testing endpoints  
SATIM_BASE_URL=https://test.satim.dz/payment/rest

Verificações de Integridade

Implemente endpoints de verificação de integridade para monitorar a conectividade do gateway:

// Add to your server
app.get('/health/satim', async (req, res) => {
  try {
    // Test connection to SATIM
    const response = await axios.get(`${SATIM_BASE_URL}/health`);
    res.json({ status: 'healthy', satim: 'connected' });
  } catch (error) {
    res.status(503).json({ status: 'unhealthy', error: error.message });
  }
});

Suporte e Contato

  • Suporte SATIM: 3020 3020 (ligação gratuita)
  • Problemas Técnicos: Entre em contato com seu especialista em integração
  • Documentação: Consulte os guias oficiais de integração do SATIM

Esta implementação do servidor MCP segue as especificações oficiais da API do SATIM e inclui todos os pontos de integração necessários para plataformas de e-commerce argelinas.