# SpherePay ## Get Started ### Introduction - [SpherePay: Stablecoin payments for global businesses](https://docs.spherepay.co/introduction.md): SpherePay is an API-first platform for on-ramp and off-ramp transfers. Convert between USD, EUR, BRL and USDC, USDT, EURC with built-in KYC/KYB compliance. ### Get Started - [How SpherePay Works: Integration Overview](https://docs.spherepay.co/get-started/how-it-works.md): Learn the three-step integration model behind SpherePay: create a verified customer, register a transfer instrument, then execute a transfer. - [Authenticate with the SpherePay API](https://docs.spherepay.co/get-started/authentication.md): All SpherePay API requests use Bearer token authentication. Learn how to generate your API key and pass it correctly in every request. - [Make Your First SpherePay API Call](https://docs.spherepay.co/get-started/first-api-call.md): Walk through creating a customer, registering a bank account and wallet, then executing your first on-ramp transfer with the SpherePay API. - [SpherePay OpenAPI 3.0 Specification Download](https://docs.spherepay.co/get-started/openapi-spec.md): Download the SpherePay OpenAPI 3.0 specification to generate API clients, import into Postman or Insomnia, or build custom tooling and integrations. ## Concepts - [SpherePay Concepts and Reference Data Overview](https://docs.spherepay.co/concepts/overview.md): Core mental models and reference data for building on SpherePay — onboarding, transfers, automation, supported rails, and operational details. ### Onboarding - [Customers & Onboarding in SpherePay](https://docs.spherepay.co/concepts/onboarding/overview.md): Before any transfer can occur, customers must be created and verified. Learn about KYC for individuals and KYB for businesses in SpherePay. - [KYC for Individual Customers](https://docs.spherepay.co/concepts/onboarding/individual-kyc.md): Onboard individual customers with KYC identity verification. Choose API or hosted link, with Sphere-Managed or Platform-Managed compliance. - [KYB for Business Customers](https://docs.spherepay.co/concepts/onboarding/business-kyb.md): Onboard business customers through KYB verification. Submit company documents, register UBOs, and complete identity verification via API or hosted link. - [Onboard Customers with a Hosted KYC Link](https://docs.spherepay.co/concepts/onboarding/kyc-via-link.md): Use SpherePay's hosted onboarding link to verify customers without building a custom UI. Redirect customers to complete KYC or KYB in minutes. - [Customer Verification Profile and Statuses](https://docs.spherepay.co/concepts/onboarding/verification-profile.md): The verification profile tracks a customer's KYC or KYB approval state. Learn what each status means and what triggers transitions between states. - [Supported ID and Tax ID Types](https://docs.spherepay.co/concepts/onboarding/identification-types.md): Reference of identity document types and country-specific tax ID number types accepted for individual and business customer onboarding via SpherePay. ### Transfers - [Transfers API: On-Ramp and Off-Ramp Guide](https://docs.spherepay.co/concepts/transfers/overview.md): Create on-ramp and off-ramp transfers with the SpherePay Transfers API. Covers integration workflow, request examples for USD and BRL/PIX, and status tracking. - [Transfer Lifecycle and Status Reference](https://docs.spherepay.co/concepts/transfers/lifecycle.md): Understand how SpherePay transfers move through each status — from pendingFunding through succeeded, returned, or failed — and how to handle each state. - [Register Bank Accounts for Fiat Transfers](https://docs.spherepay.co/concepts/transfers/bank-accounts.md): Link a customer's fiat bank account to SpherePay to enable on-ramp and off-ramp transfers via ACH, Wire, SEPA, or PIX payment rails. - [Register Crypto Wallets for Stablecoin Transfers](https://docs.spherepay.co/concepts/transfers/wallets.md): Link a customer's existing blockchain wallet address to SpherePay to enable on-ramp and off-ramp transfers across supported stablecoin networks. - [Supported Payment Rails and Stablecoins](https://docs.spherepay.co/concepts/transfers/supported-rails.md): View all supported source and destination rails, currencies, and stablecoin networks for SpherePay Transfers, Onramper Accounts, and Offloader Wallets. ### Automation - [Onramper Accounts: Automated Fiat-to-Stablecoin](https://docs.spherepay.co/concepts/automation/onramper-accounts.md): Onramper Accounts give each customer a dedicated virtual bank account that automatically converts fiat deposits to stablecoins on-chain. - [Offloader Wallets: Automated Crypto-to-Fiat](https://docs.spherepay.co/concepts/automation/offloader-wallets.md): Offloader Wallets give each customer a dedicated on-chain address that automatically converts incoming stablecoins to fiat bank payouts. ### Webhooks - [Webhooks Overview](https://docs.spherepay.co/concepts/webhooks/overview.md): Receive real-time notifications when customers, transfers, and other SpherePay resources change state — instead of polling for updates. - [Managing Webhook Endpoints](https://docs.spherepay.co/concepts/webhooks/managing-endpoints.md): Register webhook endpoints, subscribe to events, and understand endpoint limits, states, and the delete-and-recreate update model. - [Webhook Event Payloads](https://docs.spherepay.co/concepts/webhooks/event-payloads.md): The structure of every webhook payload — the envelope fields, how the sequence field orders events, and how applicationId scopes each event. - [Webhook Event Catalog](https://docs.spherepay.co/concepts/webhooks/event-catalog.md): Every webhook event subject you can subscribe to — customer and transfer events, with their triggers and example payloads. - [Verifying Webhook Signatures](https://docs.spherepay.co/concepts/webhooks/verifying-signatures.md): Authenticate every webhook delivery by validating its HMAC-SHA256 signature — with reference implementations in Python, JavaScript, Go, Java, and C#. - [Browsing Events and Replaying Deliveries](https://docs.spherepay.co/concepts/webhooks/events-and-replays.md): Look through every event SpherePay has recorded, inspect delivery attempts and responses, and replay a failed delivery on demand. ### Reference data - [Country Codes Reference for SpherePay API](https://docs.spherepay.co/concepts/reference/supported-countries.md): SpherePay uses ISO 3166-1 alpha-3 country codes in customer address fields. Reference common country codes used when creating customers and bank accounts. - [Prohibited Countries and Sanctioned Regions](https://docs.spherepay.co/concepts/reference/prohibited-countries.md): Reference list of countries and jurisdictions where SpherePay accounts cannot be opened, plus the regional restrictions that apply for sanctioned regions. - [Supported Currency Codes in SpherePay](https://docs.spherepay.co/concepts/reference/supported-assets.md): Reference for all fiat and stablecoin currency codes used in SpherePay API requests. Includes USD, EUR, BRL, USDC, USDT, and EURC with supported networks. - [Payment Channel Codes in SpherePay](https://docs.spherepay.co/concepts/reference/channel-codes.md): Reference for network and channel codes used in SpherePay transfer requests, including ach, wire, sepa, pix, and blockchain network identifiers. ### Operational - [API Rate Limits and Best Practices](https://docs.spherepay.co/concepts/operational/rate-limits.md): SpherePay enforces 100 RPS for read and write operations. Learn how to handle rate limit errors, implement retry logic, and request temporary increases. ## Guides ### Introduction - [Implementation Guides](https://docs.spherepay.co/implementation-guides/overview.md): Post-discovery routing for SpherePay integrations — choose the implementation path, pattern, and docs to use after your funds flow is scoped. ### Flow types - [First-Party Flows](https://docs.spherepay.co/implementation-guides/first-party-flows.md): Post-discovery implementation paths when the same legal entity owns both sides of the movement — one-off transfers, Onramper Accounts, and Offloader Wallets. - [Third-Party Flows](https://docs.spherepay.co/implementation-guides/third-party-flows.md): Post-discovery implementation paths when funds move to or from another legal entity, or when a platform serves downstream customers. ## Solutions ### Introduction - [SpherePay Solutions: Use Case Integration Guides](https://docs.spherepay.co/solutions/overview.md): Outcome-shaped guides for common SpherePay use cases — payroll, payment acceptance, trading, cross-border trade finance, and treasury management. ### Money movement - [Stablecoin and Fiat Payroll for Global Teams](https://docs.spherepay.co/solutions/payroll.md): Pay W-2 employees and 1099 contractors in stablecoins or fiat. Cover both crypto-native and traditional payroll models with a single integration. - [Accept Fiat Payments and Settle in Stablecoins](https://docs.spherepay.co/solutions/payment-acceptance.md): Accept fiat payments from end users and settle them as on-chain stablecoins automatically, with no per-payment API call. Built on Onramper virtual accounts. - [Fiat Currency Trading with Stablecoin Settlement](https://docs.spherepay.co/solutions/trading.md): Trade between fiat currency pairs using stablecoins as the settlement bridge — BRL ↔ USD, USD ↔ EUR, and other corridors as SpherePay's rails expand. - [Cross-Border Trade Finance](https://docs.spherepay.co/solutions/cross-border-trade-finance.md): Settle international invoices and receivables across currencies using stablecoins as the bridge — built for importers, exporters, and trade finance platforms. - [Treasury Management with Fiat-to-Stablecoin Conversion](https://docs.spherepay.co/solutions/treasury-management.md): Convert company funds between fiat and stablecoins for treasury operations — yield, faster settlement, or multi-currency strategy. ## API Reference ### Onboarding #### Customers - [Create an Individual or Business Customer](https://docs.spherepay.co/api-reference/customer/post.md): Create a new customer. - [List Customers with Filters and Pagination](https://docs.spherepay.co/api-reference/customer/get.md): List customers with optional server-side search, filters, and sort. - [Retrieve a Customer with Verification Status](https://docs.spherepay.co/api-reference/customer/get-id.md): Get information about a customer by their ID - [Update Customer Address, Phone, or Email](https://docs.spherepay.co/api-reference/customer/patch-id.md): Update a customer by their ID. (This endpoint only allows updates of personal information for individual customers) #### Onboarding Links - [Create Customer via Link](https://docs.spherepay.co/api-reference/customer/kyc-link.md): Create a customer via the hosted onboarding link flow. Returns a KYC link and its expiry. - [Regenerate a Customer's KYC Link](https://docs.spherepay.co/api-reference/customer/kyc.md): Regenerate a hosted KYC link for an existing customer. Only customers created via the onboarding link flow are supported. #### Documents & Verification - [Upload KYC and KYB Identity Documents](https://docs.spherepay.co/api-reference/document/post.md): Upload a document for a customer. - [Generate a Customer Face Verification Link](https://docs.spherepay.co/api-reference/enhanced-due-diligence/face-verification-link.md): Generate a face verification link for a customer. - [Generate a UBO Face Verification Link for KYB](https://docs.spherepay.co/api-reference/enhanced-due-diligence/ubo-face-verification-link.md): Generate a face verification link for a business representative. - [Send an OTP Code for Customer Verification](https://docs.spherepay.co/api-reference/enhanced-due-diligence/send-verification-code.md): Send an OTP code to a customer's contact information. - [Verify a Customer OTP Code for Email or Phone](https://docs.spherepay.co/api-reference/enhanced-due-diligence/verify-verification-code.md): Verify an OTP code for customer's contact information. - [Record Customer Terms of Service Acceptance](https://docs.spherepay.co/api-reference/enhanced-due-diligence/tos.md): Create a TOS link for a customer. #### Business Representatives - [Register a Business UBO for KYB Verification](https://docs.spherepay.co/api-reference/business-representative/post.md): Create a new business representative for a customer. - [List All Business Representatives and UBOs](https://docs.spherepay.co/api-reference/business-representative/get.md): List all business representatives for a customer - [Retrieve a Business Representative by ID](https://docs.spherepay.co/api-reference/business-representative/get-id.md): Retrieve a business representative by their ID - [Update a Business Representative Before KYB](https://docs.spherepay.co/api-reference/business-representative/patch-id.md): Update an existing business representative - [Remove a Business Representative or UBO](https://docs.spherepay.co/api-reference/business-representative/delete-id.md): Delete a business representative by their ID ### Accounts #### Bank Accounts - [Register a Customer Bank Account for Transfers](https://docs.spherepay.co/api-reference/bank-account/post.md): Create a new bank account for a customer. Requires at least one of the customer's verification profiles to be approved. - [List All Registered Customer Bank Accounts](https://docs.spherepay.co/api-reference/bank-account/get.md): List all bank accounts for a customer with pagination - [Retrieve a Bank Account by ID](https://docs.spherepay.co/api-reference/bank-account/get-id.md): Get information about a bank account by its ID - [Update Bank Account Payment Rail Settings](https://docs.spherepay.co/api-reference/bank-account/patch-id.md): Update a bank account by its ID. Update either the networks on a non-SWIFT account, or the intermediary BIC on a USD SWIFT account that does not already have one. - [Delete a Registered Customer Bank Account](https://docs.spherepay.co/api-reference/bank-account/delete-id.md): Delete a bank account by its ID. #### Wallets - [Register a Customer Crypto Wallet for Transfers](https://docs.spherepay.co/api-reference/wallet/post.md): Create a new wallet and associate it with a customer. - [List All Registered Customer Crypto Wallets](https://docs.spherepay.co/api-reference/wallet/get.md): List all wallets with pagination. Optionally filter by customer. - [Retrieve a Customer Crypto Wallet by ID](https://docs.spherepay.co/api-reference/wallet/get-id.md): Get information about a wallet by its ID - [Remove a Registered Customer Crypto Wallet](https://docs.spherepay.co/api-reference/wallet/delete-id.md): Delete a wallet by its ID ### Money movement #### Transfers - [Create an On-Ramp or Off-Ramp Transfer](https://docs.spherepay.co/api-reference/transfer/post.md): Create a new transfer. - [List On-Ramp and Off-Ramp Transfers](https://docs.spherepay.co/api-reference/transfer/get.md): List all transfers - [Retrieve a Transfer with Deposit Instructions](https://docs.spherepay.co/api-reference/transfer/get-id.md): Retrieve a specific transfer - [Cancel an Unfunded Pending Transfer](https://docs.spherepay.co/api-reference/transfer/delete-id.md): Cancel a specific transfer. #### Quotes - [Create a Rate-Locked Quote](https://docs.spherepay.co/api-reference/quote/post.md): Create a locked exchange rate quote. The quote is valid for the specified duration and can be used once to create a transfer. - [List All Rate-Locked Quotes for Your Account](https://docs.spherepay.co/api-reference/quote/get.md): List quotes for the application. Repeat a currency parameter to match any supplied value; source and destination filters combine. - [Retrieve a Quote by ID](https://docs.spherepay.co/api-reference/quote/get-id.md): Retrieve a single quote by its ID. - [Update Quote Status](https://docs.spherepay.co/api-reference/quote/put-id.md): Mark an active quote as used or expired. Only active quotes can be updated. #### Virtual Accounts - [Create a Virtual Bank Account for Fiat On-Ramp](https://docs.spherepay.co/api-reference/virtual-account/post.md): Create a new virtual account that converts incoming fiat deposits to crypto. - [List All Onramper Virtual Bank Accounts](https://docs.spherepay.co/api-reference/virtual-account/get.md): List all active virtual accounts for the authenticated application. - [Retrieve an Onramper Account by ID](https://docs.spherepay.co/api-reference/virtual-account/get-id.md): Retrieve a virtual account by its ID. - [Update an Onramper Account Destination Wallet](https://docs.spherepay.co/api-reference/virtual-account/patch.md): Update the destination, network, or fee configuration of a virtual account. - [List Transfers for an Onramper Account](https://docs.spherepay.co/api-reference/virtual-account/list-transfers.md): List the transfer history for a specific virtual account. Deprecated: the main `GET /v2/transfer` endpoint already returns virtual account transfers and will support filtering to the same effect. - [Deactivate an Onramper Virtual Bank Account](https://docs.spherepay.co/api-reference/virtual-account/deactivate.md): Deactivate a virtual account so it no longer accepts deposits. - [Reactivate a Deactivated Onramper Account](https://docs.spherepay.co/api-reference/virtual-account/reactivate.md): Reactivate a previously deactivated virtual account. #### Offloader Wallets - [Create an Offloader Wallet for Crypto Payouts](https://docs.spherepay.co/api-reference/offloader-wallet/post.md): Create a new offloader wallet. - [List All Offloader Wallets for Your Account](https://docs.spherepay.co/api-reference/offloader-wallet/get.md): List all offloader wallets - [Retrieve an Offloader Wallet by ID](https://docs.spherepay.co/api-reference/offloader-wallet/get-id.md): Get an offloader wallet by id - [Update an Offloader Wallet Bank Destination](https://docs.spherepay.co/api-reference/offloader-wallet/patch-id.md): Update an offloader wallet by id ### Webhooks #### Webhook Endpoints - [Register a Webhook Endpoint for Event Delivery](https://docs.spherepay.co/api-reference/webhook-endpoints/post.md): Register a new webhook endpoint to receive event deliveries for the specified subscribed events. - [List All Registered Webhook Endpoints](https://docs.spherepay.co/api-reference/webhook-endpoints/get.md): List all webhook endpoints for the authenticated application, with optional filtering by status and subscribed event types. - [Retrieve a Webhook Endpoint by ID](https://docs.spherepay.co/api-reference/webhook-endpoints/get-id.md): Retrieve a webhook endpoint by its ID. - [Delete a Webhook Endpoint](https://docs.spherepay.co/api-reference/webhook-endpoints/delete-id.md): Delete a webhook endpoint by its ID. Future events will no longer be delivered to it. #### Events - [List Events and Their Delivery Status](https://docs.spherepay.co/api-reference/events/get.md): List events for the authenticated application, with optional filtering by webhook endpoint, event type, delivery status, and creation date range. - [Retrieve an Event with Full Delivery History](https://docs.spherepay.co/api-reference/events/get-id.md): Retrieve an event by its ID. - [Replay a Failed Event Delivery](https://docs.spherepay.co/api-reference/events/replay.md): Redeliver an event to its webhook endpoint by the ID of a prior delivery attempt. ## Releases - [SpherePay API Release Notes and Changelog](https://docs.spherepay.co/changelog.md): Latest SpherePay API updates, including new features, breaking changes, deprecations, compliance updates, and newly supported payment rails and assets. ## OpenAPI Specs - [spherepay](/openapi/spherepay.yaml) ## Optional - [FAQ](https://spherepay-knowledge-base.help.usepylon.com/) > The links below point to documentation indexes. Follow each `/_llms/` index recursively until you reach documentation pages. ## Indexes - [Spanish (92 pages)](https://docs.spherepay.co/_llms/es.md): Documentation for Spanish. - [Brazilian Portuguese (92 pages)](https://docs.spherepay.co/_llms/pt-br.md): Documentation for Brazilian Portuguese.