> ## 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.

# First-Party Flows

> Post-discovery implementation paths when the same legal entity owns both sides of the movement — one-off transfers, Onramper Accounts, and Offloader Wallets.

**When Sphere routes you here:** Discovery confirmed the same legal entity owns both the source and destination — for example, treasury on-ramp, treasury off-ramp, or reusable funding/cash-out for that entity's own bank account and wallet.

This page scopes the **first-party implementation pattern** to build. For object definitions and API payloads, follow the links into [Concepts](/concepts/overview) and [API Reference](/api-reference/customer/post).

<Note>
  Paying employees, suppliers, marketplace sellers, or other third parties? Use [Third-Party Flows](/implementation-guides/third-party-flows) instead.
</Note>

## Scoping output

By the end of discovery, you and SpherePay should agree on:

* Customer type — individual or business
* Legal entity that owns **both** source and destination
* First motion — on-ramp, off-ramp, or both
* Pattern — one-off transfer, Onramper Account, or Offloader Wallet
* Fiat currency and rail
* Stablecoin and network
* One-off transfers vs reusable instructions
* Movement/conversion only vs fiat balance holding
* Expected monthly volume, average and maximum transaction size
* Verification profile and corridor enablement requirements
* Reconciliation fields your finance team needs

## Choose your pattern

<CardGroup cols={3}>
  <Card title="One-off transfer" icon="arrow-left-right" href="#pattern-one-off-transfer">
    Explicit API control per on-ramp or off-ramp. Best when each movement is initiated individually.
  </Card>

  <Card title="Onramper Account" icon="landmark" href="#pattern-onramper-account">
    Reusable fiat deposit instructions that auto-convert to stablecoin in the customer's wallet.
  </Card>

  <Card title="Offloader Wallet" icon="wallet" href="#pattern-offloader-wallet">
    Reusable stablecoin deposit address that auto-converts to fiat in the customer's bank account.
  </Card>
</CardGroup>

| Pattern                                       | Discovery signals                                                                | Primary objects                                                                                                                              |
| --------------------------------------------- | -------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| [One-off transfer](#pattern-one-off-transfer) | Per-movement API control; ad-hoc conversions; per-transfer status tracking       | Customer, [wallet](/concepts/transfers/wallets), [bank account](/concepts/transfers/bank-accounts), [transfer](/concepts/transfers/overview) |
| [Onramper Account](#pattern-onramper-account) | Reusable fiat deposits; auto-convert to stablecoin; no transfer call per deposit | Customer, wallet, [Onramper Account](/concepts/automation/onramper-accounts)                                                                 |
| [Offloader Wallet](#pattern-offloader-wallet) | Reusable stablecoin deposits; auto-convert to fiat; no transfer call per deposit | Customer, bank account, [Offloader Wallet](/concepts/automation/offloader-wallets)                                                           |

## How the flow works

<Tabs>
  <Tab title="On-ramp">
    Customer bank account or reusable funding account → SpherePay → Customer wallet

    ```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">
    Customer wallet → SpherePay → Customer bank account

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

For a treasury round-trip example, see [Treasury management](/solutions/treasury-management).

## Pattern: One-off transfer

**Use when:** The customer initiates each on-ramp or off-ramp individually and needs explicit per-transfer control.

**Discovery signals:**

* Each movement is initiated at a point in time — not triggered by a standing deposit address
* Integrator owns retry, idempotency, and status UX per transfer
* Customer may need to quote or execute transfers one at a time

<Steps>
  <Step title="Create or retrieve the customer">
    Register the legal entity via [POST /v2/customer](/api-reference/customer/post).
  </Step>

  <Step title="Complete KYC or KYB">
    Finish [individual KYC](/concepts/onboarding/individual-kyc) or [business KYB](/concepts/onboarding/business-kyb) until the [verification profile](/concepts/onboarding/verification-profile) reaches `approved`.
  </Step>

  <Step title="Register instruments">
    Link the customer's [wallet](/api-reference/wallet/post) and [bank account](/api-reference/bank-account/post) on the same customer record.
  </Step>

  <Step title="Lock a rate (optional)">
    If the customer needs a guaranteed rate, create a rate-locked quote via [POST /v2/quote](/api-reference/quote/post) (valid for 30, 60, or 300 seconds, redeemable once) and reference its `quoteId` when creating the transfer.
  </Step>

  <Step title="Create each transfer">
    Call [POST /v2/transfer](/api-reference/transfer/post) with customer, source, and destination.
  </Step>

  <Step title="Track and reconcile">
    Poll [GET /v2/transfer/{transferId}](/api-reference/transfer/get-id) until a terminal status — see [Transfer lifecycle](/concepts/transfers/lifecycle).
  </Step>
</Steps>

<Note>
  Confirm source and destination instruments belong to the **same** onboarded customer. Some corridors require provider-specific enablement beyond standard KYC/KYB — confirm access with SpherePay before building.
</Note>

**Related Solution:** [Treasury management](/solutions/treasury-management)

## Pattern: Onramper Account

**Use when:** The customer needs reusable fiat deposit instructions that automatically convert to stablecoin in a wallet they own.

**Discovery signals:**

* Customer will send fiat to the same deposit instructions repeatedly
* No `POST /v2/transfer` call should fire on each deposit
* Destination is a stablecoin wallet owned by the same legal entity

<Steps>
  <Step title="Create or retrieve the customer">
    Register the legal entity via [POST /v2/customer](/api-reference/customer/post).
  </Step>

  <Step title="Complete KYC or KYB">
    Reach `approved` on the required verification profile.
  </Step>

  <Step title="Register the destination wallet">
    The customer must already own the on-chain address. Register via [POST /v2/wallet](/api-reference/wallet/post).
  </Step>

  <Step title="Create an Onramper Account">
    Call [POST /v2/virtual-account](/api-reference/virtual-account/post). See [Onramper Accounts](/concepts/automation/onramper-accounts).
  </Step>

  <Step title="Share deposit instructions">
    Provide `depositInstructions` from the response. SpherePay converts incoming fiat and delivers stablecoin automatically.
  </Step>

  <Step title="Track deposits and conversions">
    Poll [GET /v2/transfer](/api-reference/transfer/get) filtered by customer (use `type=microdeposit` for verification deposits) to list transfers processed through the account. Each fiat deposit appears as a transfer once detected — reconcile against your expected deposits. There is no per-deposit API call to anchor status on, so design your polling cadence and reconciliation keys before launch.
  </Step>
</Steps>

<Warning>
  Onramper Accounts are an add-on product. Create **one account per customer** — shared accounts break deposit attribution. Confirm the product is enabled for your rail and region.
</Warning>

**Related Solutions:** [Payment acceptance](/solutions/payment-acceptance), [Treasury management](/solutions/treasury-management)

## Pattern: Offloader Wallet

**Use when:** The customer needs a reusable on-chain address that automatically converts incoming stablecoin to fiat in a bank account they own.

**Discovery signals:**

* Customer will send stablecoin to the same address repeatedly
* No `POST /v2/transfer` call should fire on each deposit
* Fiat destination is a bank account owned by the same legal entity

<Steps>
  <Step title="Create or retrieve the customer">
    Register the legal entity via [POST /v2/customer](/api-reference/customer/post).
  </Step>

  <Step title="Complete KYC or KYB">
    Reach `approved` on the required verification profile.
  </Step>

  <Step title="Register the destination bank account">
    Link the customer's existing account via [POST /v2/bank-account](/api-reference/bank-account/post).
  </Step>

  <Step title="Create an Offloader Wallet">
    Call [POST /v2/offloader-wallet](/api-reference/offloader-wallet/post). See [Offloader Wallets](/concepts/automation/offloader-wallets).
  </Step>

  <Step title="Share the offloader address">
    Provide the on-chain address from the response. SpherePay converts stablecoin and pays out fiat automatically.
  </Step>

  <Step title="Track deposits and payouts">
    Poll [GET /v2/transfer](/api-reference/transfer/get) filtered by customer to track stablecoin deposits and the resulting fiat payouts through to a terminal status — see [Transfer lifecycle](/concepts/transfers/lifecycle).
  </Step>
</Steps>

<Warning>
  Offloader Wallets are an add-on product. Create **one wallet per customer**. To change source/destination currency or rail type, create a new wallet — other fields may be PATCHable via [Update Offloader Wallet](/api-reference/offloader-wallet/patch-id). Verify the bank account holder's legal name and physical address (no PO boxes) before creating the wallet — partners reject PO box addresses, and correction paths for an attached bank account are limited.
</Warning>

**Related Solution:** [Treasury management](/solutions/treasury-management)

## What to send Sphere before kickoff

* Customer type: individual or business
* Legal entity owning source and destination
* First flow: on-ramp, off-ramp, or both
* Selected pattern: one-off transfer, Onramper Account, or Offloader Wallet
* Fiat currency and rail
* Stablecoin and network
* Expected monthly volume
* Average and maximum transaction size
* One-off vs reusable instructions
* Movement/conversion only vs fiat balance holding
* Reconciliation requirements

## Validate before engineering starts

| Blocker                                | What it usually means                                                                                                             |
| -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| Verification profile not approved      | Required KYC/KYB profile is incomplete, pending, missing, or rejected                                                             |
| Provider/corridor not enabled          | Customer may be approved generally but not enabled for the specific corridor or rail                                              |
| Unsupported rail, currency, or network | Combination not available for your product — [Supported rails](/concepts/transfers/supported-rails)                               |
| Ownership mismatch                     | Source or destination instrument does not belong to the onboarded customer                                                        |
| Wallet confusion                       | [POST /v2/wallet](/api-reference/wallet/post) registers an existing address — SpherePay does not generate or custody private keys |
| Onramper Account confusion             | Automates fiat-to-stablecoin conversion via deposit instructions — confirm movement-only vs balance-holding requirements          |
| Offloader Wallet updates               | Changing source/destination currency or rail type requires a new wallet; other fields may be PATCHable                            |

## Pre-kickoff checklist

* [ ] Same legal entity owns source and destination
* [ ] Pattern selected and confirmed with SpherePay
* [ ] Customer created or retrieved; verification profile `approved` for target corridor
* [ ] Provider/corridor enabled if required
* [ ] Wallet and/or bank account registered on the correct customer
* [ ] Rail, currency, and network confirmed
* [ ] Reconciliation and status mapping defined
* [ ] Kickoff inputs sent to SpherePay

## Before go-live

SpherePay has no separate sandbox — integration testing runs against production with real identity data. Run a small-dollar live transfer on each corridor before launch.

The first transfer to a new beneficiary may trigger a compliance RFI from the banking partner. Set this expectation with your customer up front, and make sure your designated RFI owner is ready to respond.

For end-customer settlement questions, share the SpherePay Knowledge Base articles [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) and [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) so users can self-serve instead of opening support tickets with you.

## Go deeper

<CardGroup cols={2}>
  <Card title="Treasury management" icon="landmark" href="/solutions/treasury-management">
    First-party treasury outcome — round-trip on-ramp/off-ramp examples.
  </Card>

  <Card title="Transfers" icon="arrow-left-right" href="/concepts/transfers/overview">
    One-off transfer lifecycle, BRL/PIX constraints, and status reference.
  </Card>

  <Card title="Third-Party Flows" icon="users" href="/implementation-guides/third-party-flows">
    When source and destination are not the same legal entity.
  </Card>

  <Card title="Onboarding" icon="user-check" href="/concepts/onboarding/overview">
    KYC, KYB, and verification profile requirements.
  </Card>

  <Card title="Knowledge Base & FAQ" icon="book-open" href="https://spherepay-knowledge-base.help.usepylon.com/">
    End-customer support articles — settlement times, missing funds, minimums, and dashboard guides — to hand to your users.
  </Card>
</CardGroup>