Moving funds between a customer’s own bank account and own wallet? Use First-Party Flows instead.
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
Business pays supplier
Pay a supplier, vendor, contractor, or exporter — purpose-of-payment and documents may apply.
Platform serves business customers
Fintech or platform enabling downstream business customers to move funds.
Bank or fintech serves consumers
Embedded ramps for individual end users — scope KYC, fraud, and pilot first.
| Pattern | Discovery signals | Primary scoping focus |
|---|---|---|
| Business pays supplier | Different legal entity receives funds; invoice/vendor payment | Beneficiary setup, purpose, documents |
| Platform serves business customers | Platform + downstream businesses; customer ID mapping | Customer of record, onboarding scope |
| 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
| 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? |
Onboard required parties
Register the payer via POST /v2/customer and complete business KYB or individual KYC as applicable.
Register the payer's source instrument
Link the payer’s bank account or wallet.
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.
Collect purpose and documents
Gather payment purpose, reason for payment, relationship context, and supporting documents — see Additional requirements.
Create the payment
Use the supported endpoint for your approved third-party flow — confirm the path with SpherePay before engineering starts.
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 applies.
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
Confirm onboarding scope
Decide whether the platform entity, each downstream business, or both must be onboarded — confirm with SpherePay.
Choose an onboarding model
If using Platform-Managed onboarding, confirm eligibility with Sphere Compliance before building.
Create and map customer records
Use POST /v2/customer for each entity that must be verified. Map internal IDs to SpherePay customer IDs.
Register instruments per party
Register bank accounts and wallets on the correct customer records.
Define payment path
Confirm endpoint path for payment creation and status polling. For fiat-acceptance outcomes, see Payment acceptance.
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
Classify downstream users
Separate business users from consumer users — onboarding paths and partner requirements differ.
Confirm onboarding responsibility
Define whether SpherePay, your platform, or a hybrid model handles KYC/KYB, RFIs, and support.
Define data handoff
Document which fields you collect upstream vs. which SpherePay collects via API or hosted link.
Choose your UX
API integration vs Ramp Widget — based on who owns the frontend experience.
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
Confirm before building
Scope the platform role
Determine whether the platform is in the flow of funds and whether downstream users are businesses, consumers, or both.
Validate corridor and geography
Confirm rail, currency, and region availability — including TX/PA restrictions for third-party payments.
Confirm compliance inputs
Define payment purpose, required documents, beneficiary setup model, and sender/recipient visibility.
Confirm endpoint path
Verify the approved path for payment creation and status polling with SpherePay — see Payment creation and status.
Payment creation and status
Third-party payment paths are product-specific. The public API Reference documentsPOST /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 — see First-Party Flows |
| Quoted fiat-to-fiat corridor (when enabled) | POST /v2/quote 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 |
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
- 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 is ready to respond. For end-customer settlement questions, share the SpherePay Knowledge Base articles When will the funds land in my account? and My funds are missing or have not landed in my account so users can self-serve instead of opening support tickets with you.Go deeper
Payroll
Third-party disbursements to employees and contractors.
Cross-border trade finance
Importer–exporter and invoice settlement patterns.
Payment acceptance
Platform-mediated fiat acceptance with stablecoin settlement.
First-Party Flows
When source and destination belong to the same legal entity.
Knowledge Base & FAQ
End-customer support articles — settlement times, missing funds, minimums, and dashboard guides — to hand to your users.