Third-Party Flows

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 or the API Reference.

​

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

​

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

Parties to confirm:

​

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

​

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

​

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.

​

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

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

​

Confirm before building

​

Payment creation and status

Third-party payment paths are product-specific. The public API Reference 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.

​

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

​

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