Changelog

​

Week of September 14

​

What is new

• Simulated payments. The new endpoint needs no Sepolia transaction, no faucet balance and no waiting for confirmations. The deposit runs through the same pipeline a real one does, so transactions, status transitions, events and webhook deliveries are unchanged. See simulate a payment
• Five outcomes. scenario produces exact, underpaid, overpaid, unconfirmed or failed. The underpaid, overpaid and failed paths were previously awkward to reach, because each needed a real transaction of a carefully chosen size.
• Amounts in the currency you priced the payment in. settlement_amount takes 12.50, amount takes the asset’s own units, and amount_atomic stays for a test that asserts on a precise figure. The endpoint previously took atomic units only, which meant knowing the asset’s decimals before you could test an underpayment.
• Partial deposits and confirmations. reference names the simulated deposit. Distinct references credit several deposits against one payment; reusing a reference updates the deposit it already created, which is how you take a deposit from confirming to confirmed.
• In the dashboard. Developers → Test payments now has a Simulate tab, which is the quickest way to drive a payment to a given state by hand. The section was previously called Test wallet and only sent Sepolia transfers.

​

Still available

​

Corrections

• The Sepolia test wallet page said there was no merchant-facing simulator. That is no longer true and the page has been updated.

​

Week of August 18

​

What changed

• Higher limits. POST /api/v2/payments goes from 120 to 1,200 requests per minute in live mode, with a burst of 200. The agentic surface goes from 120 to 600 per minute per credential. The OAuth token endpoint goes from 60 to 300 per minute. See rate limits
• Token buckets instead of fixed windows. Buckets refill continuously, so there are no window boundaries to time and sustained traffic under the rate never throttles.
• Retry-After on every 429. Wait the number of seconds it names. Authenticated responses also carry X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset, plus the RateLimit and RateLimit-Policy pair from the IETF draft, so you can pace a batch job without waiting to be throttled. X-RateLimit-Limit reports the burst bucket that X-RateLimit-Remaining counts down; the sustained rate is in RateLimit-Policy.
• The budget is per store. Issuing more API keys no longer multiplies your allowance, and rotating a key no longer resets it. Platforms are budgeted per sub-merchant, so one busy sub-merchant cannot exhaust the budget the others depend on.
• Consistent 429 body. Throttled requests now return the standard {"error": {"message": ..., "code": "rate_limited"}} envelope. The old bare-string body is gone.
• Checkout traffic is budgeted per checkout, not per IP address. Mobile carrier and office networks put many unrelated shoppers behind one address, and the old per-IP key let strangers throttle each other mid-payment. A shopper’s checkout now has its own budget, with a high per-IP ceiling behind it purely to stop abuse. The onramp limits are keyed per checkout and caller for the same reason. See rate limits
• The dashboard has its own budget. People signed in to the dashboard are counted separately from your API keys, and connected OAuth apps separately again. A batch job that exhausts your API budget can no longer lock a colleague out of the dashboard.
• Repeated authentication failures are now throttled per address. After 40 failed attempts in quick succession an address gets 429 with code too_many_failed_attempts instead of unlimited 401s. Valid credentials are never affected.

​

Corrections

• The agentic limit was documented as 120 per minute across all agentic paths. Each agentic endpoint in fact kept its own counter, so the effective limit was far higher. It is now genuinely one shared budget per credential, at 600 per minute.
• This page previously listed throttles on sign-in, sign-up and session refresh endpoints. Those endpoints are not part of this API and the entries have been removed.

​

Week of July 14

​

New features

• Subscription items: A subscription can bill several prices at once (a base plan plus add-ons), each with its own quantity, on a single cycle invoice. Pass items: [{ price_id, quantity }, ...] when you create or update a subscription. Read the guide
• Annual and multi-interval prices: Prices support a yearly interval and an interval_count, so you can bill every N days, weeks, months, or years (for example quarterly). See recurring
• Free trials: Set trial_period_days to start a subscription in a trialing status; the first invoice is issued when the trial ends.
• Change plan: PATCH /billing/subscriptions/:id swaps a subscription’s items and quantities from the next cycle.
• Scheduled cancellation: Cancel at_period_end to let the current cycle finish, then uncancel to undo it.
• New webhook events: subscription.created and subscription.updated. See webhooks

​

Week of June 2

​

New features

• Publishable API keys: A new key type (sp_pk_live_... / sp_pk_test_...) is safe to use in browser and client-side code. Publishable keys can only create checkouts. Create one from Settings → API Keys by choosing the Publishable type, or via the API with "key_type": "publishable". See authentication
• Scoped secret keys: Secret keys now carry scopes (payments:write, refunds:read, payouts:write, and more). Restrict a key to least privilege by passing a scopes array when you create it. A request missing a required scope returns 403 with code insufficient_scope. See scopes
• Checkout widget (SouthPay.js): Embed the hosted checkout inline or as a modal with a few lines of JavaScript, using a publishable key. Create checkouts in the browser, or mount a checkout your server created. Load it from https://integrate.southpay.io/widgets/v2.js. It ships as a hosted bundle, not an npm package. Read the guide

​

Week of April 28

​

New features

• Automatic refunds for failed underpaid payments: When an underpaid payment expires and your store does not accept underpayments, SouthPay now automatically initiates an on-chain refund of the partial amount to the sender. Refunds are recorded against the payment intent and the refunded amount is debited from your balance. No integration changes required. Learn more about payment intents
• List refunds for a payment: A new GET /payments/{id}/refunds endpoint returns every refund associated with a payment intent, including status (pending, submitted, confirmed, failed), reason, destination address, amount, and on-chain transaction hash. Use it to surface refund progress in your own dashboards. See the API reference
• Shopify and Magento webhook platforms: When creating a webhook endpoint, you can now set the platform to shopify or magento. The full set is woocommerce, prestashop, shopify, magento and custom. The legacy whmcs option has been removed.

​

Updates

• OAuth live mode chosen at authorization: OAuth applications now request live or test mode at authorization time by passing livemode=true to /oauth/authorize. The resulting access token is permanently scoped to that mode, so the previous X-Livemode header on OAuth requests is no longer required (or honored). Update your authorization URLs to include livemode if your application needs production access. See authentication
• New processing_underpaid state reason: Payment intents that are in processing but have not yet received the full required amount now report a state_reason of processing_underpaid, making it easier to distinguish partially-funded payments from those that have already met the required total. View the full lifecycle
• failed → refunded transition: Payment intents that ended in failed (for example, due to underpayment) can now move to refunded once the automatic refund completes on-chain. Listen for payment_intent.refunded to update order state in your system. See webhooks

​

Bug fixes

• Accurate confirmation handling for in-flight transactions: Fixed an issue where transactions reported as confirming by the upstream chain provider were marked as fully confirmed before reaching the required number of block confirmations. Transactions now stay in confirming until confirmations >= required_confirmations, preventing payments from completing prematurely.
• Processing transition only on real on-chain activity: Payment intents now move from pending to processing only when at least one transaction for the deposit address is confirming or confirmed. Stray webhook events without on-chain activity no longer flip an intent into processing. View the full lifecycle
• Webhook delivery blocked for private addresses: Outbound webhook deliveries to private, loopback, link-local, and unique-local IP addresses are now rejected before the request is sent, and the endpoint is automatically marked as error. This prevents misconfigured endpoints from causing requests to internal networks.
• Google sign-in rejects mismatched identities: Fixed an issue where signing in with Google could attach the Google identity to an existing account that had registered with the same email through a different method. Sign-in now fails with a clear error if the email is already registered to a different identity. See authentication
• Refund destination address resolution: Fixed an issue where source addresses delivered as a list (instead of a single value) were not parsed, which could prevent automatic refunds from finding a valid destination. Refunds now correctly extract the sender address from list-style provider payloads.

​

Week of April 27

​

New features

• Customer-paid processing fees: Enable customer_pays_fee on your store (or override per payment) and the checkout amount is grossed up so the customer covers the fee. Each crypto payment option on the hosted checkout now includes a base_crypto_atomic and fee_crypto_atomic breakdown alongside the total crypto_amount_atomic, and the fee percentage is locked in at intent creation time so customers always pay the rate they were quoted. Toggle it from store settings or pass customer_pays_fee when creating a payment intent. Learn more

​

Week of April 27

​

New features

• Four new settlement currencies: You can now settle payments in Danish Krone (DKK), Swiss Franc (CHF), Swedish Krona (SEK), and Norwegian Krone (NOK), in addition to the existing USD, EUR, GBP, HKD, SGD, and JPY. Pass any supported code as the currency when creating a payment intent or as the minimum_fiat_currency on a payout schedule. Learn more about payment intents
• List supported payment currencies endpoint: A new GET /payment_currencies endpoint returns every fiat currency you can use for payments and settlement, along with a human-readable label for each (for example, USD → “US Dollar”). Use it to populate currency pickers in your own UI without hard-coding the list. See the API reference

​

Updates

• Clearer payment notification emails: Payment status notification emails now show the settlement amount as a formatted decimal (for example, 12.50) instead of a raw integer in cents, so amounts in your inbox match what customers see at checkout.

​

Bug fixes

• Google sign-in captures first and last name: Fixed an issue where signing in with Google could leave a new account’s first and last name set to “Unknown”. Names are now pulled from your Google profile (given_name and family_name) when available, with a sensible fallback to the full name on the account. Existing accounts keep any name you’ve already set. See authentication
• Underpayment ledger entries on expiry: Fixed an issue where stores that accept underpayments could complete an expired payment without recording a ledger receipt for the partial amount. Confirmed funds are now always credited to your store’s balance when an underpaid payment is accepted.
• Expired checkout sessions in test mode: Fixed an issue where expiring a pending payment from the hosted checkout page could be evaluated against the wrong environment. Test-mode payments now expire correctly without affecting live data.
• Manual payouts honor idempotency keys: Manual payouts created from the dashboard or API now accept an idempotency key, so retrying the same request returns the original payout instead of creating a duplicate. Learn more about payouts

​

Week of April 27

​

Updates

• Binance fallback for exchange rates: Rate lookups for BTC, SOL, and TRX now automatically fall back to Binance if the primary provider is briefly unavailable. Checkout pricing and payout valuations stay accurate during upstream provider issues. No integration changes required. Learn more about payment intents
• Stale-rate recovery for exchange rates: If a fresh exchange rate cannot be fetched, the last known good rate (up to 24 hours old) is used as a fallback so payments and payouts keep working through provider outages. No integration changes required.
• Resilient payment creation across multiple assets: When creating a payment intent that accepts multiple crypto assets, a temporary rate lookup failure on a single asset no longer fails the entire request. The unavailable asset is dropped from the payment and the remaining assets are offered to the customer.

​

Bug fixes

• Live and test assets correctly scoped at address allocation: Fixed an issue where a store could see test-mode assets in live mode (or vice versa) when allocating deposit addresses or listing active store assets. Asset selection now strictly respects the environment of the API key making the request.
• Avalanche and testnet Ethereum webhook handling: Fixed an issue where incoming webhooks for Avalanche (AVAXC) and Sepolia testnet Ethereum (SETH) payments could be misrouted due to internal asset ID remapping. Webhooks for these assets are now matched to the correct payment.
• TRX exchange rate caching: Fixed a cache key collision that could cause TRX rates to be fetched or cached incorrectly. TRX pricing is now consistent across checkout and payouts.
• Testnet rate handling for stablecoins: Stablecoins in test mode now resolve to their real peg value instead of a generic testnet mock rate, so test payments using USDC and USDT match production behavior more closely.

​

Week of April 27

​

Updates

• Refreshed transactional emails: Welcome, email verification, payment completed, payment overpaid, payment expired, payout disbursed, and webhook delivery failure emails now use a unified SouthPay-branded template with a friendlier, more consistent tone across every message. Sign-up verification codes are delivered through the same system, so verification emails arrive with the same look and feel as the rest of your account notifications. No integration changes required. See authentication
• Auto-swap to USDC or USDT enabled by default for new stores: New stores are now created with USDT (Ethereum) pre-selected as the auto-swap target asset. You can change the target asset, or turn auto-swap off entirely, from your store settings at any time. Existing stores are unaffected.
• Store asset settings scoped to live or test mode: The list of active assets returned for your store now matches the environment of the API key making the request. Live keys see live-mode assets and test keys see test-mode assets, preventing cross-environment mismatches when configuring which crypto assets your store accepts.

​

Week of April 26

​

Updates

• Unified error handling on resource endpoints: Payments, payouts, balances, payout schedules, and webhook endpoints now share the same error-handling behavior as the rest of the API. Unexpected server errors are returned as structured JSON with a clear message and code instead of generic responses, making failures easier to detect and surface in your integration. No integration changes required.

​

Week of April 25

​

New features

• Auto-swap to USDC or USDT: Stores can now opt in to automatically swap incoming crypto payments into a stablecoin on Ethereum. Enable auto-swap from your store settings and pick either USDC or USDT (Ethereum) as your target asset; SouthPay handles the on-chain swap and credits the converted balance back to your store. Use it to reduce exposure to crypto price volatility without managing swaps yourself.

​

Updates

• Faster, more resilient exchange rates: Exchange rates are now pre-fetched on a rolling schedule and served from an in-process cache, with automatic fallback if the upstream rate provider is briefly unavailable. Checkout pricing and payout valuations stay fast and accurate even during provider hiccups. No integration changes required. Learn more about payment intents

​

Week of April 25

​

Bug fixes

• End-to-end payout reliability: Fixed an issue where outgoing payouts and fee sweeps could fail to broadcast on-chain due to incorrect source address routing. Payouts and sweeps now consistently complete and confirm. No integration changes required. Learn more about payouts
• Automatic recovery for insufficient on-chain liquidity: Payouts that previously failed when funds needed to be consolidated across deposit addresses now trigger an automatic on-chain consolidation and retry. Scheduled and one-off payouts complete without manual intervention.
• Permanent failure handling for stuck payouts: Payouts that exhaust their retry budget are now marked as permanently failed and the reserved balance is released back to your store. Funds no longer remain locked when a payout cannot be completed.
• Live and test balances kept separate during payouts: Fixed an issue where automated payouts could read from the wrong environment’s balance. Live and test mode balances are now strictly isolated when payouts are evaluated and executed.

​

Week of April 24

​

Updates

• Fiat-denominated minimum thresholds on payout schedules: Payout schedules now accept minimum_fiat_cents and minimum_fiat_currency (one of USD, EUR, GBP, HKD, SGD, JPY) in place of the previous crypto-denominated minimum_threshold. SouthPay converts the threshold to the asset’s value at payout time using live exchange rates, so a schedule set to “skip payouts below $10” behaves consistently across assets without needing to recalculate atomic amounts. Update any payout schedule requests to send the new fields. Learn more about payouts

​

Week of April 24

​

Updates

• Financial breakdown on payment intents: Retrieving a payment intent now includes a financials object with gross_amount, fee_amount, net_amount, fee_percentage, and currency. Use it to reconcile payouts, display fee details to your team, or surface net proceeds in your own dashboards. The amount_paid field is now computed from the same source, making it more accurate across partial and overpaid payments. Learn more about payment intents

​

Week of April 24

​

Updates

• Faster payment link generation: Creating a payment now generates deposit addresses and fetches exchange rates in parallel. Payment links are noticeably quicker to open, especially for payments that accept multiple crypto assets. No integration changes required. Learn more about payment intents
• OAuth store selection for multi-store users: When a user with multiple stores authorizes a third-party application without specifying a store_id, they are now shown a consent screen to choose which store to grant access to. Previously, access defaulted to the first store. Users with a single store continue to be auto-authorized as before. See authentication

​

Week of April 24

​

Updates

• Live mode for OAuth tokens: OAuth access tokens now honor the X-Livemode header. Send X-Livemode: true on requests authorized with an OAuth token (spo_...) to operate against live data; omit the header or send false to stay in test mode. Previously, OAuth tokens were always scoped to test mode. See authentication

​

Week of April 23

​

Updates

• One active token per app per store: Authorizing a third-party application now automatically revokes any previous active token that app held for the same store. Each connected app holds at most one active token per store, making it easier to reason about which credentials are in use. See authentication

​

Bug fixes

• Connected apps list scoped to your user: Fixed an issue where the connected apps list and revoke action were scoped to the current store instead of the user who granted access. You now see every third-party application you’ve authorized, and revoking a connection works regardless of which store is currently selected.

​

Week of April 23

​

Bug fixes

• Avalanche (AVAX) payment processing: Fixed an issue where incoming Avalanche payments were not matched to the correct payment due to an asset identifier mismatch. Additionally, AVAX payments in a pending confirmation state are now resolved correctly instead of getting stuck. AVAX payments are now recognized and processed reliably.
• Fee collection resilience: Fee processing for incoming payments no longer blocks payment completion if a fee wallet is unavailable. Payments are credited to your balance even if fee collection is temporarily skipped, and the system retries automatically.
• Webhook processing reliability: Improved how incoming payment webhooks are handled when they reference an unrecognized deposit address. These webhooks are now handled gracefully instead of causing errors, improving overall payment processing reliability.

​

Week of April 22

​

Updates

• All enabled assets available on checkout: Previously, only crypto assets matching your store’s fiat settlement currency were shown as payment options at checkout. Now, all active assets you’ve enabled appear regardless of which settlement currency you use. This means your customers see every crypto payment method you support, giving them more flexibility to pay with their preferred asset. Learn more about payment intents

​

Week of April 21

​

Updates

• Shared deposit addresses for EVM chains: Payments that accept multiple EVM-compatible assets (Ethereum, Polygon and Avalanche C-Chain) now share a single deposit address per payment instead of generating one per chain. This simplifies the checkout experience and reduces the number of addresses your customers see. Match a received payment on the address and the asset, never on the address alone.
• Faster checkout pricing: Exchange rates are now pre-fetched in batch when a payment is created, so pricing loads faster on the hosted checkout page. You don’t need to change anything in your integration.

​

Bug fixes

• Crypto amount precision for high-decimal assets: Fixed an issue where payment amounts for assets with many decimal places could lose precision due to integer overflow. Amounts are now stored with full precision, ensuring accurate pricing across all supported assets.

​

Week of April 20

​

New features

• Email confirmation on sign-up: New accounts now go through an email verification step. After signing up, you receive a confirmation code by email that must be submitted before your account is fully activated. You can also request a new code if the original expires.

​

Updates

• Minimum payout amounts per chain: Automated payouts now enforce a per-chain minimum withdrawal amount to prevent uneconomical “dust” payouts. If your balance is below the minimum for a given chain, the payout is skipped until enough funds accumulate. This ensures you are not charged network fees on tiny transfers. Learn more about payouts
• Live-mode chain validation for assets: When you enable a payment asset in live mode, SouthPay now verifies that the asset’s blockchain is supported by the payment provider before activation. This prevents enabling assets that cannot process real transactions.

​

Bug fixes

• EVM cross-chain payment routing: Fixed an issue where incoming payments on EVM-compatible chains (Ethereum, Polygon and Avalanche C-Chain) could be matched to the wrong payment when the same deposit address was shared across multiple chains. Payments are now resolved using both the deposit address and the asset, ensuring funds are attributed to the correct transaction.
• Deposit address chain mismatch: Fixed an issue where deposit addresses could be generated using an incorrect chain identifier, potentially routing payments to the wrong network. Addresses are now created using the correct chain for each asset.
• Duplicate deposit address prevention: Fixed a race condition where concurrent payment requests could receive the same deposit address. The system now retries address generation to guarantee each payment gets a unique address.
• Idempotent payment creation under concurrency: Fixed a race condition where simultaneous requests with the same idempotency key could fail instead of returning the existing payment. Concurrent requests now resolve correctly.

​

Week of April 19

​

New features

• OAuth 2.0 authorization: SouthPay now supports the OAuth 2.0 authorization code flow with PKCE. Third-party applications can request scoped access to your account (including reading payments, managing webhooks, and creating payment requests) without ever handling your password. See authentication
• Manage connected apps: You can view and revoke access for any third-party application connected to your store. Revoking a connection immediately invalidates the app’s access token.

​

Updates

• Supported assets scoped to environment: The supported assets list now respects your API key’s mode. Live keys return only production-ready assets; test keys return testnet assets. This prevents mismatches when switching between environments.
• Link payout destinations to schedules: When creating a payout schedule, you can now specify a crypto_payout_detail_id or fiat_payout_detail_id to route payouts to a specific destination. This gives you more control over where scheduled payouts are sent. Learn more

​

Bug fixes

• Settlement currency on payment intents: Fixed an issue where the settlement currency was not applied correctly when creating payment intents, which could cause amounts to be denominated in the wrong currency.
• Payout execution reliability: Resolved a timing issue where scheduled payouts could fail under certain conditions. Payouts now execute more reliably as part of the scheduling flow.

​

Week of April 14-18

​

New features

• SouthPay v2: The platform has been rebuilt from the ground up with a new API, expanded crypto asset support, automated payouts, and white-label checkout.
• Automated payout schedules: Set up recurring payouts on a daily, weekly, or monthly cadence with configurable minimum balance thresholds. Payouts execute automatically to your registered crypto wallet or bank account. Learn more
• Fiat payout destinations: Register bank accounts (IBAN/SWIFT) as payout destinations. SouthPay handles conversion and settlement in USD, EUR, GBP, HKD, SGD, or JPY.
• Crypto payout destinations: Add and manage crypto wallet addresses for direct on-chain payouts. Select a default address per asset and funds are routed automatically.
• White-label checkout: Customize the hosted checkout page with your own logo, brand name, and colors. Optionally remove SouthPay branding entirely. Pair with a custom domain (e.g., pay.yourcompany.com) for a fully branded experience.
• Custom domains: Serve the checkout page from your own domain with DNS-based verification.
• Webhook endpoint management: Create, update, and delete webhook endpoints via the API. Subscribe to specific event types, rotate signing secrets, send test events, and redeliver failed deliveries.
• PDF invoices: Generate and download PDF invoices for any payment, including a full fee breakdown.
• Google OAuth sign-in: Authenticate with Google in addition to email and password. New OAuth users are automatically provisioned with a default store. See authentication
• Checkout redirect URLs: Pass success_url and failed_url when creating a payment intent. Customers are automatically redirected after completing or failing a payment.
• Test mode: Develop against test data without affecting live data. There is no separate sandbox host. Test and live mode share https://api.southpay.io and are selected by the credential you send. See environments
• Live and test mode API keys: Generate separate API keys for live and test environments from the dashboard or via the API. Live keys (sp_live_) process real payments; test keys (sp_test_) operate against sandbox data. All resources (payments, webhooks, balances) are automatically scoped to the key’s mode, so live and test data never mix. See authentication
• API key management endpoints: Create, list, and revoke API keys programmatically. Use the API to generate new keys for live or test mode, view active keys, and revoke keys you no longer need.

​

Updates

• Expanded crypto asset support: Accept deposits on Ethereum, Bitcoin, Solana, Avalanche C-Chain, Tron, Polygon, Litecoin, Ethereum Classic, Stellar, SUI and TON, including USDC and USDT on multiple chains. See the full catalog

• Multi-currency settlement: Set your store’s settlement currency to USD, EUR, GBP, HKD, SGD, or JPY. Amounts and balances are denominated in your chosen currency with live exchange rates.
• Idempotent payment creation: Pass an Idempotency-Key header when creating payments to safely retry requests without creating duplicates.
• Payment status reasons: The state_reason field on payment intents now explains why a payment reached its current state (e.g., completed_exact, failed_underpaid, expired_timeout). View the full lifecycle
• Real-time balance tracking: Per-asset balances for your store update automatically as payments confirm and payouts execute.
• Email notifications: Receive automatic emails when payments are completed, overpaid, or expired.
• Real-time checkout status: The hosted checkout page now uses server-sent events for instant payment status updates, replacing polling. Customers see confirmation faster with no extra integration work.
• Improved checkout payment options: The checkout page now displays available payment methods in a flat list, making it easier for customers to select their preferred crypto asset.
• Pre-flight balance validation: Payment options on checkout are validated against available liquidity before being shown, reducing failed payment attempts.
• Stricter webhook URL validation: Webhook endpoint URLs are now validated more strictly. URLs with trailing characters after the domain and path are no longer accepted.
• Improved payment and payout reliability: Concurrent operations are now handled more reliably under high load, reducing the chance of race conditions during busy periods.

​

Bug fixes

• API key authentication on all endpoints: Fixed an issue where API key authentication (sp_live_ / sp_test_) did not work consistently across all resource endpoints. API keys now authenticate correctly on payments, payouts, balances, payout schedules, and webhook endpoints. See authentication