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

# Third-Party Flows

> Post-discovery implementation paths when funds move to or from another legal entity, or when a platform serves downstream customers.

**When Sphere routes you here:** Discovery confirmed the sender, customer of record, and beneficiary are not all the same legal entity — or your platform enables downstream customers to move funds.

Third-party flows require **more scoping** than first-party: parties, purpose-of-payment, documents, corridor availability, beneficiary setup, and the correct product endpoint path. This page defines what to validate before engineering starts. It does not replace [Solutions](/solutions/overview) or the [API Reference](/api-reference/customer/post).

<Warning>
  Third-party payment availability depends on geography, rail, customer profile, and compliance approval. Third-party payments are **not available in Texas or Pennsylvania**. Confirm supported corridors and regions with SpherePay before building.
</Warning>

<Note>
  Moving funds between a customer's **own** bank account and **own** wallet? Use [First-Party Flows](/implementation-guides/first-party-flows) instead.
</Note>

## Scoping output

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

* Platform legal entity (if applicable)
* **Customer of record**
* **Sender** and **beneficiary**
* **Funds owner** at each step
* Whether the **platform is in the flow of funds**
* Downstream user type — business, consumer, or both
* Implementation pattern — supplier payout, platform B2B, or consumer embed
* Payment purpose and reason for payment
* Supporting documents and beneficiary relationship context, if required
* Required sender/recipient visibility on the wire or statement
* Fiat currency and rail; stablecoin and network if applicable
* Expected monthly volume, average and maximum transaction size
* **RFI and customer support owner**
* Approved **endpoint and product path** for payment creation and status polling

## Choose your pattern

<CardGroup cols={3}>
  <Card title="Business pays supplier" icon="receipt" href="#pattern-business-pays-supplier">
    Pay a supplier, vendor, contractor, or exporter — purpose-of-payment and documents may apply.
  </Card>

  <Card title="Platform serves business customers" icon="building" href="#pattern-platform-serves-business-customers">
    Fintech or platform enabling downstream business customers to move funds.
  </Card>

  <Card title="Bank or fintech serves consumers" icon="smartphone" href="#pattern-bank-or-fintech-serves-consumers">
    Embedded ramps for individual end users — scope KYC, fraud, and pilot first.
  </Card>
</CardGroup>

| Pattern                                                                           | Discovery signals                                             | Primary scoping focus                 |
| --------------------------------------------------------------------------------- | ------------------------------------------------------------- | ------------------------------------- |
| [Business pays supplier](#pattern-business-pays-supplier)                         | Different legal entity receives funds; invoice/vendor payment | Beneficiary setup, purpose, documents |
| [Platform serves business customers](#pattern-platform-serves-business-customers) | Platform + downstream businesses; customer ID mapping         | Customer of record, onboarding scope  |
| [Bank or fintech serves consumers](#pattern-bank-or-fintech-serves-consumers)     | Individual end users; embedded UX                             | User classification, compliance model |

## Pattern: Business pays supplier

**Use when:** An onboarded business pays a supplier, vendor, contractor, exporter, or other third-party beneficiary.

**Discovery signals:**

* Recipient is **not** the same legal entity as the sender
* Payment tied to an invoice, purchase order, contract, or service relationship
* Purpose-of-payment, memo, or supporting documents may be required
* Cross-border settlement may apply — see [Cross-border trade finance](/solutions/cross-border-trade-finance)

**Parties to confirm:**

| Party              | Scoping question                                                  |
| ------------------ | ----------------------------------------------------------------- |
| Customer of record | Who is onboarded with SpherePay — payer, platform, or other?      |
| Sender             | Who initiates and funds the payment?                              |
| Beneficiary        | Who receives funds — and how must they be registered or reviewed? |
| Funds owner        | Whose money is moving at each step?                               |

<Steps>
  <Step title="Onboard required parties">
    Register the payer via [POST /v2/customer](/api-reference/customer/post) and complete [business KYB](/concepts/onboarding/business-kyb) or [individual KYC](/concepts/onboarding/individual-kyc) as applicable.
  </Step>

  <Step title="Register the payer's source instrument">
    Link the payer's [bank account](/api-reference/bank-account/post) or [wallet](/api-reference/wallet/post).
  </Step>

  <Step title="Confirm beneficiary setup">
    Depending on the flow, the beneficiary may need to be onboarded as a SpherePay customer or otherwise reviewed/registered before funds can be sent. Confirm with SpherePay before implementation.
  </Step>

  <Step title="Collect purpose and documents">
    Gather payment purpose, reason for payment, relationship context, and supporting documents — see [Additional requirements](#additional-requirements-for-third-party-payments). For **SWIFT** payouts a supporting document is required — see [Supporting documents for SWIFT third-party payments](#supporting-documents-for-swift-third-party-payments).
  </Step>

  <Step title="Create the payment">
    Use the **supported endpoint for your approved third-party flow** — confirm the path with SpherePay before engineering starts.
  </Step>

  <Step title="Track and reconcile">
    Poll status using the retrieval path confirmed for your flow. Reconcile against invoice or purchase-order records.
  </Step>
</Steps>

<Note>
  Third-party payments are not "first-party transfer with a different recipient." Endpoint path, beneficiary model, compliance fields, and status handling can all differ. Do not assume [POST /v2/transfer](/api-reference/transfer/post) applies.
</Note>

## Pattern: Platform serves business customers

**Use when:** A fintech or platform enables its business customers to move funds through SpherePay.

**Discovery signals:**

* Your customer is a **platform**, not only an end payer
* Downstream businesses send or receive funds through your product
* Internal customer IDs must map to SpherePay customer IDs
* RFI and support ownership must be defined before go-live

<Steps>
  <Step title="Confirm onboarding scope">
    Decide whether the platform entity, each downstream business, or both must be onboarded — confirm with SpherePay.
  </Step>

  <Step title="Choose an onboarding model">
    If using [Platform-Managed onboarding](/concepts/onboarding/overview#onboarding-models), confirm eligibility with Sphere Compliance before building.
  </Step>

  <Step title="Create and map customer records">
    Use [POST /v2/customer](/api-reference/customer/post) for each entity that must be verified. Map internal IDs to SpherePay customer IDs.
  </Step>

  <Step title="Register instruments per party">
    Register [bank accounts](/concepts/transfers/bank-accounts) and [wallets](/concepts/transfers/wallets) on the correct customer records.
  </Step>

  <Step title="Define payment path">
    Confirm endpoint path for payment creation and status polling. For fiat-acceptance outcomes, see [Payment acceptance](/solutions/payment-acceptance).
  </Step>
</Steps>

<Warning>
  Do not assume onboarding only the platform is enough. Depending on the flow, each underlying business may also need to be onboarded and verified before it can send or receive funds.
</Warning>

## Pattern: Bank or fintech serves consumers

**Use when:** A regulated institution or fintech exposes ramps to individual end users at scale.

**Discovery signals:**

* Downstream users include **consumers** (not only businesses)
* Embedded on-ramp/off-ramp or hosted UX is required
* KYC ownership, fraud controls, and chargeback considerations differ from B2B
* A limited pilot on one corridor and user segment is appropriate before broad rollout

<Steps>
  <Step title="Classify downstream users">
    Separate business users from consumer users — onboarding paths and partner requirements differ.
  </Step>

  <Step title="Confirm onboarding responsibility">
    Define whether SpherePay, your platform, or a hybrid model handles KYC/KYB, RFIs, and support.
  </Step>

  <Step title="Define data handoff">
    Document which fields you collect upstream vs. which SpherePay collects via API or [hosted link](/concepts/onboarding/kyc-via-link).
  </Step>

  <Step title="Choose your UX">
    API integration vs [Ramp Widget](/widget/overview) — based on who owns the frontend experience.
  </Step>

  <Step title="Start with a limited pilot">
    Validate one corridor, one rail, and one user type before scaling volume or user segments.
  </Step>
</Steps>

<Warning>
  Consumer flows may require different onboarding, fraud, and partner considerations than B2B. Confirm eligibility with SpherePay before assuming a business third-party pattern scales to consumers.
</Warning>

## Additional requirements for third-party payments

Plan to collect and pass the following when your approved corridor requires them:

* **Payment purpose** — classification for compliance and bank partners
* **Reason for payment** — plain-language description of why funds are moving
* **Payment purpose code** — allowed values vary by corridor; confirm the set with SpherePay before building
* **Supporting documents** — contracts, invoices, or relationship evidence when required
* **Beneficiary relationship information** — supplier, contractor, marketplace seller, etc.
* **Sender/recipient visibility** — what the beneficiary sees on the wire or statement
* **Review before settlement** — some flows require document or manual review; plan status UX accordingly

Use only fields and statuses documented in the public API for your approved product path.

## Supporting documents for SWIFT third-party payments

SWIFT payouts (USD delivered to an international bank account) are frequently **third-party payments** — the beneficiary is a different legal entity than your onboarded customer. A third-party SWIFT payment must carry a **supporting document** (typically the invoice it settles) along with a payment reason and description. The payment is rejected if any of these are missing.

<Warning>
  SWIFT requires **verification profile C** — a USD SWIFT bank account cannot be created until profile C is approved. Register the beneficiary as a USD SWIFT bank account (`currency: "usd"`, `networks: ["swift"]`) with an `accountNumber` (IBAN or BBAN) and `bic`, plus up to three optional `intermediaryBics`. Confirm profile C is enabled with SpherePay before building.
</Warning>

### Eligible documents

Upload the single document that best evidences the payment — most commonly the **invoice** it settles. Other acceptable evidence includes purchase orders, signed contracts, and service agreements. Accepted formats are **PDF, JPEG, and PNG**, up to **10 MB**.

### How it works

<Steps>
  <Step title="Upload the supporting document">
    Call [POST /v2/document](/api-reference/document/post) with `target: "transfer"` and attach the file. No `documentType` is needed for this target. The response returns the document's `id` (for example, `document_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6`).
  </Step>

  <Step title="Create the payment with the document and third-party fields">
    Create the SWIFT transfer with `isThirdParty: true` and include `documentId` (the `id` from step 1), `paymentReason`, and `paymentDescription`. For a third-party payment **all three are required** — the request is rejected with a `422` if any are missing, and the document must belong to your application.
  </Step>

  <Step title="Track and reconcile">
    Poll status as usual and reconcile against the invoice or purchase-order the document represents.
  </Step>
</Steps>

<Tip>
  **Reuse the same document across payments.** A `documentId` is not consumed when you reference it — you can pass the same one on multiple transfers. This is useful for **recurring payments against a single contract or purchase order**: upload the supporting document once, then reference its `documentId` on each payment in the series instead of re-uploading it every time.
</Tip>

`paymentReason` accepts one of: `personal`, `investment`, `real_estate`, `tax`, `loan`, `bills`, `reimbursement`, `professional_services`, `family_support`, `education`, `rent`, `donation`, `gift`, `insurance`, `medical`, `savings`, `travel`, `mortgage`, `fine`, `dividend`, `agriculture`, `import_export`, `art`, or `other`.

### What to put in the document description

When you upload the document, use the optional `description` field to give SpherePay **context it can use to review and route the payment faster** — not just a restatement of the file name. Include, where relevant:

* What the document is — e.g., "Commercial invoice INV-2024-0098"
* The purpose of the payment — e.g., "Payment for Q2 manufacturing services"
* The parties and their relationship — e.g., "From Acme Inc. to Shenzhen Supplier Co., contracted manufacturer"
* The invoice or PO number the payment settles, and the amount if it differs from the full invoice total

<Tip>
  Clear, specific descriptions reduce the chance of a compliance RFI and speed up review. The document `description` and the payment's `paymentDescription` (1–500 characters) are separate fields — use both to give full context.
</Tip>

## Confirm before building

<Steps>
  <Step title="Identify the parties">
    Confirm customer of record, sender, beneficiary, and funds owner at each step.
  </Step>

  <Step title="Scope the platform role">
    Determine whether the platform is in the flow of funds and whether downstream users are businesses, consumers, or both.
  </Step>

  <Step title="Validate corridor and geography">
    Confirm rail, currency, and region availability — including TX/PA restrictions for third-party payments.
  </Step>

  <Step title="Confirm compliance inputs">
    Define payment purpose, required documents, beneficiary setup model, and sender/recipient visibility.
  </Step>

  <Step title="Confirm endpoint path">
    Verify the approved path for payment creation and status polling with SpherePay — see [Payment creation and status](#payment-creation-and-status).
  </Step>

  <Step title="Assign operational ownership">
    Define who handles RFIs and customer support before go-live.
  </Step>
</Steps>

## Payment creation and status

Third-party payment paths are **product-specific**. The public [API Reference](/api-reference/transfer/post) documents `POST /v2/transfer` for on-ramp/off-ramp and quoted transfer flows. **Third-party B2B payment creation may use a different endpoint path** — confirm with SpherePay before implementation.

| Flow type                                   | Guidance                                                                                                              |
| ------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| First-party on-ramp/off-ramp                | [POST /v2/transfer](/api-reference/transfer/post) — see [First-Party Flows](/implementation-guides/first-party-flows) |
| Quoted fiat-to-fiat corridor (when enabled) | [POST /v2/quote](/api-reference/quote/post) then transfer creation with `quoteId` — confirm applicability             |
| Approved third-party B2B payments           | Use the endpoint path confirmed by SpherePay — do not assume first-party v2 transfer                                  |

<Tip>
  Poll status using the retrieval path confirmed for your approved flow. Third-party responses may include fields and statuses beyond the [first-party transfer lifecycle](/concepts/transfers/lifecycle) — confirm the full set with SpherePay.
</Tip>

## What to send Sphere before kickoff

* Platform legal entity (if applicable)
* Customer of record
* Sender and beneficiary
* Funds ownership at each step
* Whether the platform is in the flow of funds
* Downstream user type: business, consumer, or both
* Selected pattern: supplier payout, platform B2B, or consumer embed
* Payment purpose code and reason for payment
* Supporting documentation type, if required
* Beneficiary relationship / recipient context
* Required sender/recipient visibility
* Fiat currency and rail; stablecoin and network if applicable
* Expected monthly volume
* Average and maximum transaction size
* RFI/support owner
* Related Solution guide, if identified

## Validate before engineering starts

| Blocker                                        | Why it matters                                                                                     |
| ---------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| Verification profile not approved              | Required KYC/KYB profile is incomplete, pending, missing, or rejected                              |
| Provider/corridor not enabled                  | Customer approved generally but not enabled for the specific corridor or rail                      |
| Geography / corridor restriction               | Third-party payments are not available in **Texas or Pennsylvania**; other regions may have limits |
| Customer of record unclear                     | SpherePay cannot determine who must be onboarded                                                   |
| Platform in the flow of funds                  | May change onboarding, compliance, and partner requirements                                        |
| Beneficiary unidentified                       | Payout cannot be evaluated or routed                                                               |
| Missing or unsupported payment purpose         | Required purpose code or reason missing or not enabled for corridor                                |
| Missing supporting documents                   | Settlement may block until documents are provided                                                  |
| Third-party flow using first-party assumptions | Treasury/on-ramp patterns may not apply to supplier or platform payouts                            |
| Wrong endpoint assumed                         | Payment creation path must match your approved third-party product                                 |
| Consumer scale with B2B pattern                | Consumer embed may require a different path                                                        |

## Pre-kickoff checklist

* [ ] Customer of record, sender, and beneficiary identified
* [ ] Funds ownership and platform role documented
* [ ] Pattern selected and confirmed with SpherePay
* [ ] Required parties onboarded or beneficiary setup confirmed for corridor
* [ ] Provider/corridor and geography validated (including TX/PA)
* [ ] Payment purpose, reason, and documents collected if required
* [ ] For SWIFT: verification profile C approved, USD SWIFT beneficiary account registered, and (for third-party) `paymentReason`, `paymentDescription`, and an uploaded `documentId` ready
* [ ] Endpoint path for create and status confirmed with SpherePay
* [ ] RFI/support owner defined
* [ ] Reconciliation plan 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 [RFI and customer support owner](#scoping-output) 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="Payroll" icon="banknote" href="/solutions/payroll">
    Third-party disbursements to employees and contractors.
  </Card>

  <Card title="Cross-border trade finance" icon="ship" href="/solutions/cross-border-trade-finance">
    Importer–exporter and invoice settlement patterns.
  </Card>

  <Card title="Payment acceptance" icon="hand-coins" href="/solutions/payment-acceptance">
    Platform-mediated fiat acceptance with stablecoin settlement.
  </Card>

  <Card title="First-Party Flows" icon="landmark" href="/implementation-guides/first-party-flows">
    When source and destination belong to the same legal entity.
  </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>