> ## Documentation Index
> Fetch the complete documentation index at: https://docs.spherepay.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Fluxos Próprios (First-Party)

> Caminhos de implementação quando a mesma entidade legal possui ambos os lados da movimentação: transferências avulsas, Onramper Accounts e Offloader Wallets.

**Quando o Sphere direciona você aqui:** A descoberta confirmou que a mesma entidade legal possui origem e destino — por exemplo, on-ramp de tesouraria, off-ramp de tesouraria ou financiamento/saque reutilizável para a própria conta bancária e carteira dessa entidade.

Esta página define o **padrão de implementação próprio (first-party)** a construir. Para definições de objetos e payloads de API, siga os links para [Conceitos](/pt-BR/concepts/overview) e [Referência da API](/pt-BR/api-reference/customer/post).

<Note>
  Pagando funcionários, fornecedores, vendedores de marketplace ou outras terceiras partes? Use [Fluxos de Terceiros](/pt-BR/implementation-guides/third-party-flows).
</Note>

## Output de escopo

Ao final da descoberta, você e o SpherePay devem concordar em:

* Tipo de cliente — pessoa física ou jurídica
* Entidade legal que possui **ambos** origem e destino
* Primeira movimentação — on-ramp, off-ramp ou ambos
* Padrão — transferência avulsa, Onramper Account ou Offloader Wallet
* Moeda fiat e rail
* Stablecoin e rede
* Transferências avulsas vs. instruções reutilizáveis
* Apenas movimentação/conversão vs. manutenção de saldo fiat
* Volume mensal esperado, tamanho médio e máximo de transação
* Perfil de verificação e requisitos de habilitação de corredor
* Campos de reconciliação que sua equipe financeira precisa

## Escolha seu padrão

<CardGroup cols={3}>
  <Card title="Transferência avulsa" icon="arrow-left-right" href="#padrão-transferência-avulsa">
    Controle explícito de API por on-ramp ou off-ramp. Melhor quando cada movimentação é iniciada individualmente.
  </Card>

  <Card title="Onramper Account" icon="landmark" href="#padrão-onramper-account">
    Instruções reutilizáveis de depósito fiat que convertem automaticamente para stablecoin na carteira do cliente.
  </Card>

  <Card title="Offloader Wallet" icon="wallet" href="#padrão-offloader-wallet">
    Endereço de depósito de stablecoin reutilizável que converte automaticamente para fiat na conta bancária do cliente.
  </Card>
</CardGroup>

| Padrão                                               | Sinais de descoberta                                                                                             | Objetos primários                                                                                                                                                      |
| ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Transferência avulsa](#padrão-transferência-avulsa) | Controle de API por movimentação; conversões avulsas; rastreamento de status por transferência                   | Cliente, [carteira](/pt-BR/concepts/transfers/wallets), [conta bancária](/pt-BR/concepts/transfers/bank-accounts), [transferência](/pt-BR/concepts/transfers/overview) |
| [Onramper Account](#padrão-onramper-account)         | Depósitos fiat reutilizáveis; conversão automática para stablecoin; sem chamada de transferência por depósito    | Cliente, carteira, [Onramper Account](/pt-BR/concepts/automation/onramper-accounts)                                                                                    |
| [Offloader Wallet](#padrão-offloader-wallet)         | Depósitos de stablecoin reutilizáveis; conversão automática para fiat; sem chamada de transferência por depósito | Cliente, conta bancária, [Offloader Wallet](/pt-BR/concepts/automation/offloader-wallets)                                                                              |

## Como o fluxo funciona

<Tabs>
  <Tab title="On-ramp">
    Conta bancária do cliente ou conta de financiamento reutilizável → SpherePay → Carteira do cliente

    ```mermaid theme={"dark"}
    flowchart LR
        BA["Customer<br/>bank account"] -->|Fiat deposit| SP["SpherePay"]
        SP -->|Stablecoin| W["Customer<br/>wallet"]
    ```
  </Tab>

  <Tab title="Off-ramp">
    Carteira do cliente → SpherePay → Conta bancária do cliente

    ```mermaid theme={"dark"}
    flowchart LR
        W["Customer<br/>wallet"] -->|Stablecoin| SP["SpherePay"]
        SP -->|Fiat payout| BA["Customer<br/>bank account"]
    ```
  </Tab>
</Tabs>

Para um exemplo de round-trip de tesouraria, consulte [Gestão de tesouraria](/pt-BR/solutions/treasury-management).

## Padrão: Transferência avulsa

**Use quando:** O cliente inicia cada on-ramp ou off-ramp individualmente e precisa de controle explícito por transferência.

**Sinais de descoberta:**

* Cada movimentação é iniciada em um ponto no tempo — não acionada por um endereço de depósito permanente
* O integrador possui retry, idempotência e UX de status por transferência
* O cliente pode precisar cotar ou executar transferências uma de cada vez

<Steps>
  <Step title="Criar ou recuperar o cliente">
    Registre a entidade legal via [POST /v2/customer](/pt-BR/api-reference/customer/post).
  </Step>

  <Step title="Completar KYC ou KYB">
    Conclua o [KYC individual](/pt-BR/concepts/onboarding/individual-kyc) ou o [KYB empresarial](/pt-BR/concepts/onboarding/business-kyb) até que o [perfil de verificação](/pt-BR/concepts/onboarding/verification-profile) atinja `approved`.
  </Step>

  <Step title="Registrar instrumentos">
    Vincule a [carteira](/pt-BR/api-reference/wallet/post) e a [conta bancária](/pt-BR/api-reference/bank-account/post) do cliente no mesmo registro de cliente.
  </Step>

  <Step title="Bloquear uma taxa (opcional)">
    Se o cliente precisar de uma taxa garantida, crie uma cotação com taxa bloqueada via [POST /v2/quote](/pt-BR/api-reference/quote/post) (válida por 30, 60 ou 300 segundos, resgatável uma vez) e referencie seu `quoteId` ao criar a transferência.
  </Step>

  <Step title="Criar cada transferência">
    Chame [POST /v2/transfer](/pt-BR/api-reference/transfer/post) com cliente, origem e destino.
  </Step>

  <Step title="Rastrear e reconciliar">
    Consulte [GET /v2/transfer/{transferId}](/pt-BR/api-reference/transfer/get-id) até um status terminal — consulte [Ciclo de vida da transferência](/pt-BR/concepts/transfers/lifecycle).
  </Step>
</Steps>

<Note>
  Confirme que os instrumentos de origem e destino pertencem ao **mesmo** cliente cadastrado. Alguns corredores requerem habilitação específica do provedor além do KYC/KYB padrão — confirme o acesso com o SpherePay antes de construir.
</Note>

**Solução relacionada:** [Gestão de tesouraria](/pt-BR/solutions/treasury-management)

## Padrão: Onramper Account

**Use quando:** O cliente precisa de instruções reutilizáveis de depósito fiat que convertem automaticamente para stablecoin em uma carteira de sua propriedade.

**Sinais de descoberta:**

* O cliente enviará fiat para as mesmas instruções de depósito repetidamente
* Nenhuma chamada `POST /v2/transfer` deve ocorrer a cada depósito
* O destino é uma carteira de stablecoin pertencente à mesma entidade legal

<Steps>
  <Step title="Criar ou recuperar o cliente">
    Registre a entidade legal via [POST /v2/customer](/pt-BR/api-reference/customer/post).
  </Step>

  <Step title="Completar KYC ou KYB">
    Atinja `approved` no perfil de verificação obrigatório.
  </Step>

  <Step title="Registrar a carteira de destino">
    O cliente já deve possuir o endereço on-chain. Registre via [POST /v2/wallet](/pt-BR/api-reference/wallet/post).
  </Step>

  <Step title="Criar um Onramper Account">
    Chame [POST /v2/virtual-account](/pt-BR/api-reference/virtual-account/post). Consulte [Onramper Accounts](/pt-BR/concepts/automation/onramper-accounts).
  </Step>

  <Step title="Compartilhar instruções de depósito">
    Forneça `depositInstructions` da resposta. O SpherePay converte o fiat recebido e entrega a stablecoin automaticamente.
  </Step>

  <Step title="Rastrear depósitos e conversões">
    Consulte [GET /v2/transfer](/pt-BR/api-reference/transfer/get) filtrado por cliente (use `type=microdeposit` para depósitos de verificação) para listar transferências processadas pela conta. Cada depósito fiat aparece como uma transferência após detecção — reconcilie com seus depósitos esperados. Não há chamada de API por depósito para ancorar o status; defina sua cadência de polling e chaves de reconciliação antes do lançamento.
  </Step>
</Steps>

<Warning>
  Onramper Accounts são um produto adicional. Crie **uma conta por cliente** — contas compartilhadas quebram a atribuição de depósito. Confirme se o produto está habilitado para seu rail e região.
</Warning>

**Soluções relacionadas:** [Aceitação de pagamentos](/pt-BR/solutions/payment-acceptance), [Gestão de tesouraria](/pt-BR/solutions/treasury-management)

## Padrão: Offloader Wallet

**Use quando:** O cliente precisa de um endereço on-chain reutilizável que converte automaticamente stablecoin recebida para fiat em uma conta bancária de sua propriedade.

**Sinais de descoberta:**

* O cliente enviará stablecoin para o mesmo endereço repetidamente
* Nenhuma chamada `POST /v2/transfer` deve ocorrer a cada depósito
* O destino fiat é uma conta bancária pertencente à mesma entidade legal

<Steps>
  <Step title="Criar ou recuperar o cliente">
    Registre a entidade legal via [POST /v2/customer](/pt-BR/api-reference/customer/post).
  </Step>

  <Step title="Completar KYC ou KYB">
    Atinja `approved` no perfil de verificação obrigatório.
  </Step>

  <Step title="Registrar a conta bancária de destino">
    Vincule a conta existente do cliente via [POST /v2/bank-account](/pt-BR/api-reference/bank-account/post).
  </Step>

  <Step title="Criar um Offloader Wallet">
    Chame [POST /v2/offloader-wallet](/pt-BR/api-reference/offloader-wallet/post). Consulte [Offloader Wallets](/pt-BR/concepts/automation/offloader-wallets).
  </Step>

  <Step title="Compartilhar o endereço do offloader">
    Forneça o endereço on-chain da resposta. O SpherePay converte a stablecoin e paga o fiat automaticamente.
  </Step>

  <Step title="Rastrear depósitos e pagamentos">
    Consulte [GET /v2/transfer](/pt-BR/api-reference/transfer/get) filtrado por cliente para rastrear depósitos de stablecoin e os pagamentos fiat resultantes até um status terminal — consulte o [ciclo de vida da transferência](/pt-BR/concepts/transfers/lifecycle).
  </Step>
</Steps>

<Warning>
  Offloader Wallets são um produto adicional. Crie **uma carteira por cliente**. Para alterar moeda de origem/destino ou tipo de rail, crie uma nova carteira — outros campos podem ser atualizados via PATCH em [Atualizar Offloader Wallet](/pt-BR/api-reference/offloader-wallet/patch-id). Verifique o nome legal e o endereço físico do titular da conta bancária (sem caixas postais) antes de criar a carteira — parceiros rejeitam endereços com caixa postal, e os caminhos de correção para uma conta bancária vinculada são limitados.
</Warning>

**Solução relacionada:** [Gestão de tesouraria](/pt-BR/solutions/treasury-management)

## O que enviar ao Sphere antes do kickoff

* Tipo de cliente: pessoa física ou jurídica
* Entidade legal que possui origem e destino
* Primeiro fluxo: on-ramp, off-ramp ou ambos
* Padrão selecionado: transferência avulsa, Onramper Account ou Offloader Wallet
* Moeda fiat e rail
* Stablecoin e rede
* Volume mensal esperado
* Tamanho médio e máximo de transação
* Instruções avulsas vs. reutilizáveis
* Apenas movimentação/conversão vs. manutenção de saldo fiat
* Requisitos de reconciliação

## Validar antes de iniciar a engenharia

| Bloqueador                         | O que normalmente significa                                                                                                                  |
| ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| Perfil de verificação não aprovado | O perfil de KYC/KYB obrigatório está incompleto, pendente, ausente ou rejeitado                                                              |
| Provedor/corredor não habilitado   | O cliente pode estar aprovado em geral, mas não habilitado para o corredor ou rail específico                                                |
| Rail, moeda ou rede não suportados | Combinação não disponível para seu produto — [Rails suportados](/pt-BR/concepts/transfers/supported-rails)                                   |
| Incompatibilidade de propriedade   | O instrumento de origem ou destino não pertence ao cliente cadastrado                                                                        |
| Confusão com carteira              | [POST /v2/wallet](/pt-BR/api-reference/wallet/post) registra um endereço existente — o SpherePay não gera nem custodia chaves privadas       |
| Confusão com Onramper Account      | Automatiza conversão de fiat para stablecoin via instruções de depósito — confirme requisitos de apenas movimentação vs. manutenção de saldo |
| Atualizações de Offloader Wallet   | Alterar moeda de origem/destino ou tipo de rail requer uma nova carteira; outros campos podem ser atualizados via PATCH                      |

## Lista de verificação pré-kickoff

* [ ] A mesma entidade legal possui origem e destino
* [ ] Padrão selecionado e confirmado com o SpherePay
* [ ] Cliente criado ou recuperado; perfil de verificação `approved` para o corredor alvo
* [ ] Provedor/corredor habilitado se necessário
* [ ] Carteira e/ou conta bancária registradas no cliente correto
* [ ] Rail, moeda e rede confirmados
* [ ] Reconciliação e mapeamento de status definidos
* [ ] Inputs de kickoff enviados ao SpherePay

## Antes de entrar em produção

O SpherePay não possui sandbox separado — os testes de integração rodam em produção com dados de identidade reais. Execute uma transferência ao vivo de baixo valor em cada corredor antes do lançamento.

A primeira transferência para um novo beneficiário pode acionar um RFI de conformidade do parceiro bancário. Defina essa expectativa com seu cliente desde o início e garanta que seu responsável de RFI designado esteja pronto para responder.

Para dúvidas de liquidação de usuários finais, compartilhe os artigos da Base de Conhecimento do SpherePay [When will the funds land in my account?](https://spherepay-knowledge-base.help.usepylon.com/articles/9934878291-when-will-the-funds-land-in-my-account) e [My funds are missing or have not landed in my account](https://spherepay-knowledge-base.help.usepylon.com/articles/9884755317-my-funds-are-missing-or-have-not-landed-in-my-account-what-should-i-do) para que os usuários se autoatendam em vez de abrir tickets de suporte com você.

## Aprofundar

<CardGroup cols={2}>
  <Card title="Gestão de tesouraria" icon="landmark" href="/pt-BR/solutions/treasury-management">
    Resultado de tesouraria própria — exemplos de round-trip on-ramp/off-ramp.
  </Card>

  <Card title="Transferências" icon="arrow-left-right" href="/pt-BR/concepts/transfers/overview">
    Ciclo de vida de transferência avulsa, restrições BRL/PIX e referência de status.
  </Card>

  <Card title="Fluxos de Terceiros" icon="users" href="/pt-BR/implementation-guides/third-party-flows">
    Quando origem e destino não são a mesma entidade legal.
  </Card>

  <Card title="Onboarding" icon="user-check" href="/pt-BR/concepts/onboarding/overview">
    Requisitos de KYC, KYB e perfil de verificação.
  </Card>

  <Card title="Base de Conhecimento e FAQ" icon="book-open" href="https://spherepay-knowledge-base.help.usepylon.com/">
    Artigos de suporte para usuários finais — prazos de liquidação, fundos ausentes, mínimos e guias do painel — para repassar aos seus usuários.
  </Card>
</CardGroup>