Copy page

Documentação

Casos de uso

Este documento explora aplicações e casos de uso do mundo real para implementar pagamentos seguros com Fluxis API e o protocolo NASPIP, demonstrando como integrar pagamentos blockchain em suas aplicações usando o fluxo de API de comerciante compatível.

::::tip Authentication pattern Todos os exemplos abaixo assumem que você já trocou sua chave API e segredo por um token Bearer via POST /v1/auth/token. Rotas protegidas exigem ambos Authorization: Bearer <token> e x-fluxis-api-key: <api_key>. Nunca exponha segredos API em código client-side. ::::

E-commerce e varejo

Pagamentos em loja online

Cenário: Uma plataforma de e-commerce quer aceitar pagamentos com criptomoedas junto com métodos de pagamento tradicionais.

Solução Fluxis API:

Code
const API_BASE = "https://api.fluxis.us/v1";
const POS_ID = "YOUR_POINT_OF_SALE_ID";

// 1) Troque chave API + segredo por um token de acesso (somente server-side)
const authRes = await fetch(`${API_BASE}/auth/token`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    api_key: process.env.FLUXIS_API_KEY,
    api_secret: process.env.FLUXIS_API_SECRET,
  }),
});
const { data: auth } = await authRes.json();

// 2) Crie uma solicitação de pagamento para um checkout
const prRes = await fetch(`${API_BASE}/pos/${POS_ID}/payment-request`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${auth.token}`,
    "x-fluxis-api-key": process.env.FLUXIS_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    amount: "299.99",
    unique_asset_id: "npolygon_t0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359",
    reference_id: "order-12345",
  }),
});
const { data: paymentRequest } = await prRes.json();

// 3) Apresente paymentRequest.token ao pagador (QR / deep link / checkout hospedado)
// Opcional: POST /pos/:posID/payment-request-checkout para uma URL de checkout hospedado

Benefícios:

• 🚀 Integração rápida: Comece em minutos com Fluxis API
• 🔐 Segurança empresarial: Instruções de pagamento NASPIP assinadas (PASETO v4) e verificação de assinatura de webhooks
• 🌐 Multirrede: Suporte a ativos EVM configurados (UAIs) em redes habilitadas como Polygon, Base, Avalanche e Arbitrum
• 📱 Checkout flexível: Token NASPIP QR, deep links ou checkout hospedado
• ⚡ Alto desempenho: Infraestrutura escalável para aplicações de produção

Sistemas de ponto de venda (POS)

Cenário: Uma loja de varejo quer aceitar pagamentos com criptomoedas em locais físicos usando um fluxo estilo caixa.

Implementação Fluxis API:

Code
const API_BASE = "https://api.fluxis.us/v1";

class POSSystem {
  constructor(apiKey, apiSecret, posId) {
    this.apiKey = apiKey;
    this.apiSecret = apiSecret;
    this.posId = posId;
    this.accessToken = null;
  }

  async authenticate() {
    const res = await fetch(`${API_BASE}/auth/token`, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        api_key: this.apiKey,
        api_secret: this.apiSecret,
      }),
    });
    const { data } = await res.json();
    this.accessToken = data.token;
  }

  authHeaders() {
    return {
      Authorization: `Bearer ${this.accessToken}`,
      "x-fluxis-api-key": this.apiKey,
      "Content-Type": "application/json",
    };
  }

  async createPaymentIntention(amount, coinCode = "USD") {
    const res = await fetch(
      `${API_BASE}/pos/${this.posId}/payment-intention`,
      {
        method: "POST",
        headers: this.authHeaders(),
        body: JSON.stringify({
          amount,
          coin_code: coinCode,
          external_id: `pos-${Date.now()}`,
        }),
      },
    );
    return (await res.json()).data;
  }

  async getPaymentRequest(paymentRequestId) {
    const res = await fetch(
      `${API_BASE}/pos/${this.posId}/payment-request/${paymentRequestId}`,
      { headers: this.authHeaders() },
    );
    return (await res.json()).data;
  }
}

// Uso
const pos = new POSSystem(
  process.env.FLUXIS_API_KEY,
  process.env.FLUXIS_API_SECRET,
  "YOUR_POS_ID",
);
await pos.authenticate();
const intention = await pos.createPaymentIntention(50.0, "USD");
// Exiba o token de intenção como QR; faça polling ou use webhooks para atualizações de status

Serviços financeiros

Remessas transfronteiriças

Cenário: Um serviço de remessas quer oferecer transferências internacionais rápidas e de baixo custo usando stablecoins.

Implementação Fluxis API:

Code
async function createRemittancePayment({ amount, referenceId, posId }) {
  const auth = await getAccessToken(); // POST /v1/auth/token

  const res = await fetch(
    `https://api.fluxis.us/v1/pos/${posId}/payment-request`,
    {
      method: "POST",
      headers: {
        Authorization: `Bearer ${auth.token}`,
        "x-fluxis-api-key": process.env.FLUXIS_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        amount: amount.toString(),
        unique_asset_id: "npolygon_t0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359",
        reference_id: referenceId,
        order: {
          description: "Cross-border remittance",
        },
      }),
    },
  );

  const { data } = await res.json();
  return {
    paymentRequestId: data.id,
    naspipToken: data.token,
    expiration: data.expiration,
  };
}

Registre um webhook de conta para receber atualizações de status completed, underpaid ou overpaid e execute a transferência após confirmação do pagamento.

Integração de pagamentos DeFi

Cenário: Um protocolo DeFi quer integrar instruções de pagamento seguras para yield farming e provisão de liquidez.

Code
async function createPoolDepositPayment({ poolAddress, amount, posId }) {
  const auth = await getAccessToken();

  const res = await fetch(
    `https://api.fluxis.us/v1/pos/${posId}/payment-request`,
    {
      method: "POST",
      headers: {
        Authorization: `Bearer ${auth.token}`,
        "x-fluxis-api-key": process.env.FLUXIS_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        amount: amount.toString(),
        unique_asset_id: "npolygon_t0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359",
        reference_id: `pool-${poolAddress.slice(0, 8)}`,
        order: {
          description: `Yield farming deposit — ${poolAddress}`,
        },
      }),
    },
  );

  const { data } = await res.json();
  return { paymentRequest: data, naspipToken: data.token };
}

Gaming e entretenimento

Compras dentro do jogo

Cenário: Um jogo mobile quer aceitar pagamentos com criptomoedas para itens do jogo e recursos premium.

Code
async function createInGamePurchase({ itemId, price, playerId, posId }) {
  const auth = await getAccessToken();

  const res = await fetch(
    `https://api.fluxis.us/v1/pos/${posId}/payment-request`,
    {
      method: "POST",
      headers: {
        Authorization: `Bearer ${auth.token}`,
        "x-fluxis-api-key": process.env.FLUXIS_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        amount: price.toString(),
        unique_asset_id: "npolygon_t0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359",
        reference_id: `player-${playerId}-item-${itemId}`,
        order: {
          description: `In-game purchase: ${itemId}`,
        },
      }),
    },
  );

  const { data } = await res.json();

  // Opcional: checkout hospedado em vez do token NASPIP bruto
  // POST /v1/pos/:posID/payment-request-checkout

  return {
    paymentRequestId: data.id,
    naspipToken: data.token,
    referenceId: data.reference_id,
  };
}

// No webhook `completed` (ou polling GET /pos/:posID/payment-request/:id):
// conceda o item ao jogador identificado por reference_id

Por que escolher Fluxis API para estes casos de uso?

🚀 Desenvolvimento rápido

• 5 minutos até o primeiro pagamento: Comece imediatamente
• API REST simples: Integração fácil com qualquer stack tecnológico
• Documentação abrangente: Exemplos e guias claros

🔒 Segurança empresarial

• Instruções de pagamento assinadas: Tokens NASPIP com payloads verificáveis
• Autenticidade de webhooks: Assinaturas HMAC-SHA256 em eventos de saída
• Credenciais server-side: Segredos API nunca pertencem a apps client-side

📈 Pronto para produção

• Infraestrutura de produção: Projetada para alta disponibilidade (confirme os termos de SLA com a equipe comercial do Fluxis)
• CDN global: Tempos de resposta rápidos em todo o mundo
• Autoescaling: Lida com picos de tráfego automaticamente

🛠️ Experiência do desenvolvedor

• Playground interativo da API: Teste endpoints diretamente no navegador
• Guias de integração: Onboarding de comerciantes passo a passo
• Suporte especializado: Entre em contato com [email protected] quando precisar de ajuda

Primeiros passos

Pronto para implementar qualquer um destes casos de uso? Comece com o Guia de integração da API ou explore nossa Referência da API.

Próximos passos

1. Cadastre-se no Fluxis - Crie sua conta
2. Obtenha sua chave API - Gere sua primeira chave
3. Siga o Guia de integração da API - Faça sua primeira chamada à API
4. Primeiros passos - Início rápido em 6 etapas

---

Pronto para transformar sua experiência de pagamento? Comece a integrar com Fluxis API hoje!