Tutoriais

Guia de integração API

Este guia descreve os passos recomendados para integrar com a API da Fluxis, do provisionamento de credenciais à conciliação de transações.

Visão geral da integração

Uma integração típica com a Fluxis segue estes passos:

Provisionamento de credenciais — Criar uma chave de API no dashboard (papéis read + write)
Autenticação — Trocar credenciais por um token de acesso Bearer
Descoberta de recursos — Recuperar suas contas padrão e pontos de venda padrão (criados no cadastro)
Criar seu POS online — Configurar o POS para pagamentos online, para gerar várias solicitações de pagamento em paralelo
Configuração de liquidação — Configurar o endereço cripto onde os ativos cobrados serão entregues. Pode ser feito no dashboard ou via API.
Criação de solicitações de pagamento — Criar uma solicitação por tentativa de checkout
Monitorar status de pagamento — Webhooks (push) ou polling (pull) — escolha um ou ambos
Conciliação — Consultar transações periodicamente para capturar eventos perdidos

Antes de começar

Ambientes

Ambiente	Host
Staging	`https://api.stgfluxis.us`
Production	`https://api.fluxis.us`

Credenciais de produção serão geradas após sua integração em staging estar completa e aprovada pela Fluxis.

Cabeçalhos obrigatórios

Todos os endpoints protegidos da Fluxis exigem ambos os cabeçalhos:

Authorization: Bearer <access_token>
x-fluxis-api-key: <your_api_key>

Trate seu API Secret como credencial sensível. Nunca o exponha em código client-side, navegadores ou apps móveis.

Etapa 1 — Provisionamento de credenciais

Antes de qualquer chamada à API, crie credenciais de API no Dashboard da Fluxis.

Novo na Fluxis? Conclua o Cadastro de comerciante (criação de conta + 2FA) antes desta etapa.

Criar uma chave de API no dashboard

Faça login no Dashboard da Fluxis (staging ou production).
Abra Developers → API Keys (ou navegue até /app/api-keys).
Clique em Create (ou equivalente) para adicionar uma nova chave.
Atribua os papéis read e write para listar recursos e criar solicitações de pagamento.
Conclua o desafio 2FA quando solicitado (Autenticação de dois fatores deve estar cadastrada antes).
Copie o API Secret imediatamente — é exibido uma vez e não pode ser recuperado depois.

Você receberá:

API Key ID (ex.: fxs.stg.<uuid> para staging, fxs.prd.<uuid> para production)
API Secret — armazene em gerenciador de segredos ou variáveis de ambiente

Consulte Credenciais de API para papéis, lista de IP e ciclo de vida.

Se você opera várias marcas ou regiões, alinhe cedo com a Fluxis a estrutura de Accounts e Points of Sale. Isso simplifica relatórios e conciliação.

Etapa 2 — Autenticação

Troque suas credenciais por um token de acesso que deve ser incluído em todas as requisições API subsequentes.

Endpoint: POST /v1/auth/token

Consulte o formato completo de requisição/resposta em nossa Referência API - Authentication.

Uso do token

Inclua o token de acesso em todas as requisições protegidas:

Code
Authorization: Bearer <access_token>
x-fluxis-api-key: <your_api_key>

Ciclo de vida do token

Expiração: Tokens de acesso expiram (consulte o campo expired_at na resposta)
Renovação: Implemente um mecanismo para renovar o token antes da expiração
Rotação: Rotacione sua API Key/Secret imediatamente se suspeitar de comprometimento

Etapa 3 — Descoberta de recursos

Após autenticar, recupere informações sobre suas contas e pontos de venda padrão, ou crie novos.

3.1 Recuperar contas

Contas representam as contas financeiras do comerciante na Fluxis.

Endpoint: GET /v1/account

Consulte o formato completo da resposta em nossa Referência API - Accounts.

3.2 Recuperar pontos de venda

Pontos de Venda (POS) representam seus pontos de entrada de pagamento — locais físicos ou virtuais onde você aceita pagamentos. Você precisará do ID do POS ao criar solicitações de pagamento.

Endpoint: GET /v1/pos?page=1&page_size=20

Parâmetros obrigatórios: page (≥ 1) e page_size (1–100). Chaves de organização podem filtrar com account_id.

Consulte o formato completo da resposta em nossa Referência API — Point of Sale.

Saiba mais sobre o conceito de POS: Ponto de Venda.

Etapa 4 — Configuração de liquidação

Antes de aceitar pagamentos, configure para onde os ativos cripto cobrados serão entregues.

Todos os ativos cobrados de uma rede específica (ex.: USDT, USDC ou outros tokens na Polygon) serão entregues ao endereço de liquidação configurado para essa rede.

Por segurança, a configuração de endereços de liquidação é feita manualmente pela equipe Fluxis. Entre em contato com seu representante para configurar endereços em staging e production.

Etapa 5 — Criação de solicitações de pagamento

Crie uma solicitação de pagamento para cada tentativa de checkout do cliente. A resposta inclui um token NASPIP com todas as informações de pagamento.

Endpoint: POST /v1/pos/:posID/payment-request

Campos principais:

amount — Valor do pagamento (ex.: "49.99")
unique_asset_id — Ativo/rede alvo (saiba mais sobre UAIs)
reference_id — Seu ID interno de pedido para conciliação
order — Dados estruturados opcionais do pedido para recibos/UX

Consulte o formato completo em nossa Referência API - Payment Request.

5.1 Exibir o token NASPIP

O token retornado na resposta é um token NASPIP que você apresenta ao cliente.

Checkout desktop: Exiba o token NASPIP como QR code para o usuário escanear com o app de carteira.

Checkout mobile: Exiba um botão "Pagar com [nome do app de carteira]" que abre o app via deep link:

Code
[wallet app deeplink url]?<custom_query_params>&naspip_token=<NASPIP_TOKEN>

Saiba mais sobre NASPIP: Token NASPIP.

Para lista mantida de apps de carteira, templates de deep link e logos, consulte Registro de apps compatíveis.

5.2 Hosted checkout (opcional)

Para uma página de pagamento hospedada pela Fluxis em vez de incorporar o token NASPIP você mesmo:

Endpoint: POST /v1/pos/:posID/payment-request-checkout

A resposta inclui token e checkout_url para redirecionar clientes diretamente. A página hosted consulta GET /public/checkout/:sessionId e, ao terminar, usa return_url: em um ponto de venda genérico é config.return_url do POS; em uma sessão Tiendanube é o callback por tentativa (success, failure ou cancel) gravado no Process Payment, não a URL do POS.

Consulte API Reference — Create payment request checkout.

Etapa 6 — Escolher como monitorar pagamentos

Após criar uma solicitação de pagamento, você precisa saber quando o cliente paga. Escolha uma ou ambas estratégias:

Estratégia	Entrega	Ideal para	Requisitos
Webhooks (Opção A)	Push — Fluxis faz POST no seu servidor	Integrações em produção, UX em tempo real	Endpoint HTTPS público, verificação de assinatura
Polling (Opção B)	Pull — seu servidor consulta a Fluxis	Backends simples, dev local, sem URL pública	Token Bearer + API key válidos; polling a cada ~3 segundos

Muitas equipes usam webhooks como principal e polling como fallback quando um webhook é perdido ou o endpoint ficou temporariamente fora.

Opção A — Notificações webhook

Webhooks são a forma recomendada de receber atualizações de status em tempo real.

A.1 Configurar seu endpoint webhook

Primeiro, garanta um endpoint HTTPS publicamente acessível pronto para receber POST da Fluxis.

Depois registre um webhook na conta vinculada ao seu POS (use o account_id do POS ou da lista de contas):

Endpoint: POST /v1/account/{accountID}/webhook


Code
{
  "url": "https://your-server.com/webhooks/fluxis",
  "event_type": "payment_request"
}

A Fluxis retorna um secret uma vez na criação — armazene com segurança para verificação de assinatura.

Consulte API Reference — Create webhook.

A.2 Eventos webhook

A Fluxis envia webhooks payment_request quando o status se torna:

Status	Descrição	Webhook entregue
`processing`	Pagamento detectado, aguardando confirmações blockchain	Sim
`completed`	Pagamento confirmado — atenda o pedido	Sim
`underpaid`	Cliente enviou menos que o valor solicitado	Sim
`overpaid`	Cliente enviou mais que o valor solicitado	Sim
`expired`	Sem pagamento no prazo	Não — use polling
`failed`	Erro inesperado de processamento	Não — polling / suporte

Os estados underpaid e overpaid são casos extremos que podem indicar configuração inadequada no app de carteira, já que tokens NASPIP contêm o valor esperado. Para verificação de assinatura, consulte Verificação de assinatura de webhook.

A.3 Tratar webhooks

Ao receber uma notificação webhook:

Verificar autenticidade — Valide a assinatura HMAC sobre o corpo parseado completo { "data": … } com o segredo da criação — consulte Verificação de assinatura de webhook
Processar o status — Atualize o status interno do pedido e notifique o cliente
Confirmar recebimento — Retorne HTTP 200 OK

Seu endpoint deve responder rápido (< 2 segundos). Enfileire processamento pesado em segundo plano. Falha em confirmar pode fazer a Fluxis reenviar a notificação.

A.4 Idempotência

Você pode receber eventos webhook duplicados. Garanta que o handler seja idempotente — processar o mesmo evento várias vezes deve produzir o mesmo resultado.

A.5 Testar seu handler

Após o registro, dispare uma entrega de amostra assinada:

Endpoint: POST /v1/account/{accountID}/webhook/{webhookID}/test

A Fluxis faz POST de um payload payment_request_status_update com o mesmo caminho de assinatura da produção. Verifique a assinatura e retorne HTTP 200. Consulte Verificação de assinatura de webhook para regras de JSON canônico e exemplo prático.

Você também pode registrar webhooks no dashboard em Developers → Webhooks. Consulte Webhooks para opções API e dashboard.

Opção B — Polling

Se não tiver endpoint HTTPS público — ou preferir uma primeira integração mais simples — faça polling do status da solicitação em intervalo fixo (por exemplo, a cada 3 segundos) até status terminal.

Endpoint: GET /v1/pos/:posID/payment-request/:paymentRequestID

Cabeçalhos obrigatórios: Authorization: Bearer <token> e x-fluxis-api-key: <your_api_key>.

Padrão de polling recomendado

Após criar a solicitação, registre paymentRequestID e posID.
Faça polling a cada ~3 segundos enquanto o status for created, pending, confirmed ou processing.
Pare o polling quando o status for terminal: completed, expired, underpaid, overpaid ou failed.
Em completed, atenda o pedido; em expired, ofereça criar nova solicitação.

Solicitações de pagamento expiram após cerca de 8 minutos. Evite polling mais rápido que uma vez por segundo — 3 segundos é um padrão razoável para UX de checkout.

Exemplo (curl):

Code
curl "https://api.stgfluxis.us/v1/pos/${POS_ID}/payment-request/${PAYMENT_REQUEST_ID}" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "x-fluxis-api-key: ${API_KEY}"

Exemplo (loop Node.js):


Code
const TERMINAL = new Set([
  "completed",
  "expired",
  "underpaid",
  "overpaid",
  "failed",
]);
const POLL_MS = 3000;

async function waitForPayment(posId, paymentRequestId) {
  while (true) {
    const res = await fetch(
      `${API_BASE}/v1/pos/${posId}/payment-request/${paymentRequestId}`,
      {
        headers: {
          Authorization: `Bearer ${accessToken}`,
          "x-fluxis-api-key": apiKey,
        },
      },
    );
    const { data } = await res.json();
    if (TERMINAL.has(data.status)) return data;
    await new Promise((r) => setTimeout(r, POLL_MS));
  }
}

Consulte o formato completo em nossa Referência API — Get payment request.

Status expired e failed não disparam webhooks — polling (ou checagens manuais) é necessário para esses resultados.

Etapa 7 — Conciliação

Mesmo com webhooks ou polling no checkout, execute conciliação periódica para garantir que nenhum pagamento foi perdido (downtime, rede ou bugs no handler).

Consultar uma solicitação específica

Se não recebeu webhook (ou o sistema ficou fora), busque o status diretamente:

Endpoint: GET /v1/pos/:posID/payment-request/:paymentRequestID

Listar transações para conciliação

Para conciliação em lote, consulte o endpoint de transações:

Endpoint: GET /v1/transactions?page=1&page_size=50

Parâmetros obrigatórios: page (≥ 1) e page_size (5–100).

Filtros opcionais:

accountID — Filtrar por conta (apenas chaves de API em nível de organização)

A resposta é paginada: { data, total, page, page_size, total_pages }.

Padrão comum: listar periodicamente transações completed e comparar com pedidos internos por ID de referência, valor e timestamp.

Ciclo de vida da solicitação de pagamento

As solicitações passam pelos seguintes estados:

Estado	Descrição	Ação do comerciante
`pending`	Checkout criado, moeda não selecionada	Aguardar ou exibir hosted checkout
`created`	Endereço atribuído, aguardando pagamento	Exibir QR/link ao cliente
`confirmed`	Etapa interna de confirmação	Geralmente sem ação do comerciante
`processing`	Pagamento detectado, aguardando confirmações	Continuar aguardando — não entregar ainda
`completed`	Pagamento confirmado	Atender o pedido
`expired`	Sem pagamento no prazo	Oferecer nova solicitação ao cliente
`underpaid` / `overpaid` / `failed`	Casos extremos	Contatar suporte Fluxis

Saiba mais: Fluxos de pagamento - Caminho feliz e Fluxos de pagamento - Casos extremos.

Checklist para produção

Antes de ir para produção, verifique:

Precisa de ajuda?

Se tiver dúvidas sobre onboarding, credenciais ou prontidão para produção, entre em contato em [email protected].

Last modified on October 12, 2026

Aceitar pagamentos pelo Dashboard Criar e monitorar solicitações de pagamento

Tutoriais

Guia de integração API

Este guia descreve os passos recomendados para integrar com a API da Fluxis, do provisionamento de credenciais à conciliação de transações.

Visão geral da integração

Uma integração típica com a Fluxis segue estes passos:

Provisionamento de credenciais — Criar uma chave de API no dashboard (papéis read + write)
Autenticação — Trocar credenciais por um token de acesso Bearer
Descoberta de recursos — Recuperar suas contas padrão e pontos de venda padrão (criados no cadastro)
Criar seu POS online — Configurar o POS para pagamentos online, para gerar várias solicitações de pagamento em paralelo
Configuração de liquidação — Configurar o endereço cripto onde os ativos cobrados serão entregues. Pode ser feito no dashboard ou via API.
Criação de solicitações de pagamento — Criar uma solicitação por tentativa de checkout
Monitorar status de pagamento — Webhooks (push) ou polling (pull) — escolha um ou ambos
Conciliação — Consultar transações periodicamente para capturar eventos perdidos

Antes de começar

Ambientes

Ambiente	Host
Staging	`https://api.stgfluxis.us`
Production	`https://api.fluxis.us`

Credenciais de produção serão geradas após sua integração em staging estar completa e aprovada pela Fluxis.

Cabeçalhos obrigatórios

Todos os endpoints protegidos da Fluxis exigem ambos os cabeçalhos:

Authorization: Bearer <access_token>
x-fluxis-api-key: <your_api_key>

Trate seu API Secret como credencial sensível. Nunca o exponha em código client-side, navegadores ou apps móveis.

Etapa 1 — Provisionamento de credenciais

Antes de qualquer chamada à API, crie credenciais de API no Dashboard da Fluxis.

Novo na Fluxis? Conclua o Cadastro de comerciante (criação de conta + 2FA) antes desta etapa.

Criar uma chave de API no dashboard

Faça login no Dashboard da Fluxis (staging ou production).
Abra Developers → API Keys (ou navegue até /app/api-keys).
Clique em Create (ou equivalente) para adicionar uma nova chave.
Atribua os papéis read e write para listar recursos e criar solicitações de pagamento.
Conclua o desafio 2FA quando solicitado (Autenticação de dois fatores deve estar cadastrada antes).
Copie o API Secret imediatamente — é exibido uma vez e não pode ser recuperado depois.

Você receberá:

API Key ID (ex.: fxs.stg.<uuid> para staging, fxs.prd.<uuid> para production)
API Secret — armazene em gerenciador de segredos ou variáveis de ambiente

Consulte Credenciais de API para papéis, lista de IP e ciclo de vida.

Se você opera várias marcas ou regiões, alinhe cedo com a Fluxis a estrutura de Accounts e Points of Sale. Isso simplifica relatórios e conciliação.

Etapa 2 — Autenticação

Troque suas credenciais por um token de acesso que deve ser incluído em todas as requisições API subsequentes.

Endpoint: POST /v1/auth/token

Consulte o formato completo de requisição/resposta em nossa Referência API - Authentication.

Uso do token

Inclua o token de acesso em todas as requisições protegidas:

Code
Authorization: Bearer <access_token>
x-fluxis-api-key: <your_api_key>

Ciclo de vida do token

Expiração: Tokens de acesso expiram (consulte o campo expired_at na resposta)
Renovação: Implemente um mecanismo para renovar o token antes da expiração
Rotação: Rotacione sua API Key/Secret imediatamente se suspeitar de comprometimento

Etapa 3 — Descoberta de recursos

Após autenticar, recupere informações sobre suas contas e pontos de venda padrão, ou crie novos.

3.1 Recuperar contas

Contas representam as contas financeiras do comerciante na Fluxis.

Endpoint: GET /v1/account

Consulte o formato completo da resposta em nossa Referência API - Accounts.

3.2 Recuperar pontos de venda

Pontos de Venda (POS) representam seus pontos de entrada de pagamento — locais físicos ou virtuais onde você aceita pagamentos. Você precisará do ID do POS ao criar solicitações de pagamento.

Endpoint: GET /v1/pos?page=1&page_size=20

Parâmetros obrigatórios: page (≥ 1) e page_size (1–100). Chaves de organização podem filtrar com account_id.

Consulte o formato completo da resposta em nossa Referência API — Point of Sale.

Saiba mais sobre o conceito de POS: Ponto de Venda.

Etapa 4 — Configuração de liquidação

Antes de aceitar pagamentos, configure para onde os ativos cripto cobrados serão entregues.

Todos os ativos cobrados de uma rede específica (ex.: USDT, USDC ou outros tokens na Polygon) serão entregues ao endereço de liquidação configurado para essa rede.

Por segurança, a configuração de endereços de liquidação é feita manualmente pela equipe Fluxis. Entre em contato com seu representante para configurar endereços em staging e production.

Etapa 5 — Criação de solicitações de pagamento

Crie uma solicitação de pagamento para cada tentativa de checkout do cliente. A resposta inclui um token NASPIP com todas as informações de pagamento.

Endpoint: POST /v1/pos/:posID/payment-request

Campos principais:

amount — Valor do pagamento (ex.: "49.99")
unique_asset_id — Ativo/rede alvo (saiba mais sobre UAIs)
reference_id — Seu ID interno de pedido para conciliação
order — Dados estruturados opcionais do pedido para recibos/UX

Consulte o formato completo em nossa Referência API - Payment Request.

5.1 Exibir o token NASPIP

O token retornado na resposta é um token NASPIP que você apresenta ao cliente.

Checkout desktop: Exiba o token NASPIP como QR code para o usuário escanear com o app de carteira.

Checkout mobile: Exiba um botão "Pagar com [nome do app de carteira]" que abre o app via deep link:

Code
[wallet app deeplink url]?<custom_query_params>&naspip_token=<NASPIP_TOKEN>

Saiba mais sobre NASPIP: Token NASPIP.

Para lista mantida de apps de carteira, templates de deep link e logos, consulte Registro de apps compatíveis.

5.2 Hosted checkout (opcional)

Para uma página de pagamento hospedada pela Fluxis em vez de incorporar o token NASPIP você mesmo:

Endpoint: POST /v1/pos/:posID/payment-request-checkout

Consulte API Reference — Create payment request checkout.

Etapa 6 — Escolher como monitorar pagamentos

Após criar uma solicitação de pagamento, você precisa saber quando o cliente paga. Escolha uma ou ambas estratégias:

Estratégia	Entrega	Ideal para	Requisitos
Webhooks (Opção A)	Push — Fluxis faz POST no seu servidor	Integrações em produção, UX em tempo real	Endpoint HTTPS público, verificação de assinatura
Polling (Opção B)	Pull — seu servidor consulta a Fluxis	Backends simples, dev local, sem URL pública	Token Bearer + API key válidos; polling a cada ~3 segundos

Muitas equipes usam webhooks como principal e polling como fallback quando um webhook é perdido ou o endpoint ficou temporariamente fora.

Opção A — Notificações webhook

Webhooks são a forma recomendada de receber atualizações de status em tempo real.

A.1 Configurar seu endpoint webhook

Primeiro, garanta um endpoint HTTPS publicamente acessível pronto para receber POST da Fluxis.

Depois registre um webhook na conta vinculada ao seu POS (use o account_id do POS ou da lista de contas):

Endpoint: POST /v1/account/{accountID}/webhook


Code
{
  "url": "https://your-server.com/webhooks/fluxis",
  "event_type": "payment_request"
}

A Fluxis retorna um secret uma vez na criação — armazene com segurança para verificação de assinatura.

Consulte API Reference — Create webhook.

A.2 Eventos webhook

A Fluxis envia webhooks payment_request quando o status se torna:

Status	Descrição	Webhook entregue
`processing`	Pagamento detectado, aguardando confirmações blockchain	Sim
`completed`	Pagamento confirmado — atenda o pedido	Sim
`underpaid`	Cliente enviou menos que o valor solicitado	Sim
`overpaid`	Cliente enviou mais que o valor solicitado	Sim
`expired`	Sem pagamento no prazo	Não — use polling
`failed`	Erro inesperado de processamento	Não — polling / suporte

A.3 Tratar webhooks

Ao receber uma notificação webhook:

Verificar autenticidade — Valide a assinatura HMAC sobre o corpo parseado completo { "data": … } com o segredo da criação — consulte Verificação de assinatura de webhook
Processar o status — Atualize o status interno do pedido e notifique o cliente
Confirmar recebimento — Retorne HTTP 200 OK

Seu endpoint deve responder rápido (< 2 segundos). Enfileire processamento pesado em segundo plano. Falha em confirmar pode fazer a Fluxis reenviar a notificação.

A.4 Idempotência

Você pode receber eventos webhook duplicados. Garanta que o handler seja idempotente — processar o mesmo evento várias vezes deve produzir o mesmo resultado.

A.5 Testar seu handler

Após o registro, dispare uma entrega de amostra assinada:

Endpoint: POST /v1/account/{accountID}/webhook/{webhookID}/test

Você também pode registrar webhooks no dashboard em Developers → Webhooks. Consulte Webhooks para opções API e dashboard.

Opção B — Polling

Endpoint: GET /v1/pos/:posID/payment-request/:paymentRequestID

Cabeçalhos obrigatórios: Authorization: Bearer <token> e x-fluxis-api-key: <your_api_key>.

Padrão de polling recomendado

Após criar a solicitação, registre paymentRequestID e posID.
Faça polling a cada ~3 segundos enquanto o status for created, pending, confirmed ou processing.
Pare o polling quando o status for terminal: completed, expired, underpaid, overpaid ou failed.
Em completed, atenda o pedido; em expired, ofereça criar nova solicitação.

Solicitações de pagamento expiram após cerca de 8 minutos. Evite polling mais rápido que uma vez por segundo — 3 segundos é um padrão razoável para UX de checkout.

Exemplo (curl):

Code
curl "https://api.stgfluxis.us/v1/pos/${POS_ID}/payment-request/${PAYMENT_REQUEST_ID}" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "x-fluxis-api-key: ${API_KEY}"

Exemplo (loop Node.js):


Code
const TERMINAL = new Set([
  "completed",
  "expired",
  "underpaid",
  "overpaid",
  "failed",
]);
const POLL_MS = 3000;

async function waitForPayment(posId, paymentRequestId) {
  while (true) {
    const res = await fetch(
      `${API_BASE}/v1/pos/${posId}/payment-request/${paymentRequestId}`,
      {
        headers: {
          Authorization: `Bearer ${accessToken}`,
          "x-fluxis-api-key": apiKey,
        },
      },
    );
    const { data } = await res.json();
    if (TERMINAL.has(data.status)) return data;
    await new Promise((r) => setTimeout(r, POLL_MS));
  }
}

Consulte o formato completo em nossa Referência API — Get payment request.

Status expired e failed não disparam webhooks — polling (ou checagens manuais) é necessário para esses resultados.

Etapa 7 — Conciliação

Mesmo com webhooks ou polling no checkout, execute conciliação periódica para garantir que nenhum pagamento foi perdido (downtime, rede ou bugs no handler).

Consultar uma solicitação específica

Se não recebeu webhook (ou o sistema ficou fora), busque o status diretamente:

Endpoint: GET /v1/pos/:posID/payment-request/:paymentRequestID

Listar transações para conciliação

Para conciliação em lote, consulte o endpoint de transações:

Endpoint: GET /v1/transactions?page=1&page_size=50

Parâmetros obrigatórios: page (≥ 1) e page_size (5–100).

Filtros opcionais:

accountID — Filtrar por conta (apenas chaves de API em nível de organização)

A resposta é paginada: { data, total, page, page_size, total_pages }.

Padrão comum: listar periodicamente transações completed e comparar com pedidos internos por ID de referência, valor e timestamp.

Ciclo de vida da solicitação de pagamento

As solicitações passam pelos seguintes estados:

Estado	Descrição	Ação do comerciante
`pending`	Checkout criado, moeda não selecionada	Aguardar ou exibir hosted checkout
`created`	Endereço atribuído, aguardando pagamento	Exibir QR/link ao cliente
`confirmed`	Etapa interna de confirmação	Geralmente sem ação do comerciante
`processing`	Pagamento detectado, aguardando confirmações	Continuar aguardando — não entregar ainda
`completed`	Pagamento confirmado	Atender o pedido
`expired`	Sem pagamento no prazo	Oferecer nova solicitação ao cliente
`underpaid` / `overpaid` / `failed`	Casos extremos	Contatar suporte Fluxis

Saiba mais: Fluxos de pagamento - Caminho feliz e Fluxos de pagamento - Casos extremos.

Checklist para produção

Antes de ir para produção, verifique:

Precisa de ajuda?

Se tiver dúvidas sobre onboarding, credenciais ou prontidão para produção, entre em contato em [email protected].

Last modified on October 12, 2026

Aceitar pagamentos pelo Dashboard Criar e monitorar solicitações de pagamento