Skip to main content

​
API Changelog

Stay informed about new features, improvements, and breaking changes to the 123hub API.
Subscribe to our developer newsletter to receive changelog updates via email.

​
2026

​
April 2026

​
v2.2.2 - Webhook Resend & Routing Reliability

​
2026-04-24
Webhook Resend & Routing ReliabilityAdded merchant-facing recovery controls and improved payment routing reliability.
  • Added POST /payments/{paymentId}/webhook/resend to re-queue webhook delivery for a specific payment
  • Added a 10 requests/minute throttle to webhook resend requests
  • Improved deposit routing reliability with automatic provider fallback when cascade routing is enabled
  • Expanded accepted MultiHub request fields for payer, receiver, bank, redirect, identifiers, and per-payment webhook_url
  • Tightened per-payment webhook_url validation to require a valid public HTTP(S) URL
  • Fixed webhook consumer handling for queued delivery payloads
Breaking changes:
  • Per-payment webhook_url now must be a valid public HTTP(S) URL

​
v2.2.1 - Documentation Contract Sync

​
2026-04-24
Documentation Contract SyncPublic documentation was reconciled with the current gateway contracts.
  • Added dedicated reference pages for MultiHub methods, outgoing webhooks, webhook management, and public payment pages
  • Corrected payment.status and payment.notification lookup identifiers to c_id and h_id; p_id is returned for reconciliation and is not a lookup key
  • Corrected Mexico payout examples: CLABE is sent in receiver.bank.account.id; receiver.bank.clabe is not accepted by the DTO
  • Reworked webhook payload docs to use data.result.payment, omit internal _payment_id, and document X-Data-Hash plus replay-protection headers
  • Documented actual webhook delivery defaults: timeout 30s, max_retries default 3, retry_delay_seconds default 1, jittered exponential retry with a 24h cap
  • Expanded the error code reference to cover every current MultihubErrorCode
  • Documented successful API response signing with X-Data-Hash

​
v2.2.0 - Turkey Direction & Payment Method Expansion

​
2026-04-02
v2.2.0 — Turkey (TRY) Payment Direction & Documentation RefreshNew payment direction for Turkey and updated documentation to reflect actual system capabilities.New: Turkey (TRY) deposits:
  • Currency: TRY (Turkish Lira)
  • Payment methods: havale (bank transfer), papara (e-wallet), kredikarti (credit/debit card)
  • Deposits: havale (bank transfer), papara (e-wallet), kredikarti (credit/debit card)
  • Withdrawals: bank_transfer with IBAN
New: Additional currencies:
  • AUD (Australian Dollar) — deposit & withdrawal
  • LKR (Sri Lankan Rupee) — deposit & withdrawal
New payment methods documented:
  • upi — Unified Payments Interface (India, primary deposit method)
  • havale — Turkish bank transfer (Havale/EFT)
  • papara — Papara e-wallet (Turkey)
  • kredikarti — Turkish credit/debit card
  • imps — Immediate Payment Service (India)
New: payment.notification method documented:
  • Re-send webhook notification for a specific payment
Webhook documentation corrected:
  • Webhook payload now documents the delivered outer envelope (id, data, created_at, merchant_id) and keeps internal _payment_id out of merchant-facing examples
  • Documented fields absent in webhooks vs API (service_id, description, redirect, receiver.bank)
Response documentation expanded:
  • Added operations[] and operation fields to response reference
  • Added receiver.bank_account format for deposit responses (TRY, ARS)
  • Documented redirect.to type variations by region (array for UPI, string for Havale)
  • Clarified status.error type as integer | string | null
  • Noted h_id format varies by provider (numeric string or UUID)
  • Documented that receiver.bank is not returned in payment.status or webhooks
Documentation corrections:
  • Removed currencies with no active provider: BRL, CNY, COP, EUR, GEL, USD
  • Changed INR default method from bank_transfer to upi
  • Turkey (TRY) supports both deposits and withdrawals (not deposit-only)
  • Added region-specific bank fields: IFSC (India), CLABE (Mexico), bank code (Argentina), IBAN (Turkey)
Breaking changes:
  • None (additive only; removed currencies were never functional)

​
February 2026

​
v2.1.0 - Error Handling & Response Format Improvements

​
2026-02-12
v2.1.0 — Error Handling, Balance, and Validation ImprovementsImproved API compatibility with the 123hub specification. Error handling, response formats, and validation have been updated.HTTP status codes (breaking change):
  • Error responses now return HTTP 400 (previously HTTP 200)
  • Unknown method errors (1002) return HTTP 404
  • Successful responses continue to return HTTP 200
  • Always check the success field to determine the outcome
Error response format:
  • error.details and error.context are now always present in error responses (value is null when not applicable)
  • Missing required field errors now use code 1005 with descriptive details object
  • Wrong hash/signature errors now return code 3000 (Authentication error)
  • next field removed from response envelope
New validation errors:
  • 6001 — Incorrect transaction amount (zero or negative)
  • 6002 — Incorrect currency code (mismatch with service_id)
  • 6009 — Payment already exists (duplicate c_id)
  • Missing payer object in payment.in now returns 1005 with specific description
gateway.ping format change (breaking change):
  • Response changed from "result": "pong" to "result": {"message": "pong"}
balance.get format change (breaking change):
  • Response restructured from result.balances[] to result.balance.{id, amounts[], enabled}
  • Balance fields renamed: available → value, frozen → value_freezing, added value_blocking and enabled
Redirect URLs:
  • Provider HTTPS payment page URLs are no longer included in redirect.to
  • Only UPI deep-link URLs (for India) are returned in redirect.to
Breaking changes:
  • HTTP status codes for errors changed from 200 to 400/404
  • next field removed from response envelope
  • gateway.ping response format changed
  • balance.get response structure completely changed
  • Error code for missing fields changed from 9000 to 1005
  • Error code for wrong hash changed from 3002 to 3000

​
January 2026

​
v2.0.0 - 123hub API Migration

​
2026-01-31
v2.0.0 — 123hub API Migration (Breaking Change)Complete API redesign to 123hub.pro format. This is a breaking change — all integrations must be updated.New API format:
  • Single endpoint: POST /public/api/multihub/v1 replaces all previous REST endpoints
  • Method-based routing via body.method: payment.in, payment.out, payment.status, balance.get, gateway.ping
  • Standardized response envelope: { success, result, error, request_id, processing_time }
  • Success returns HTTP 200, errors return HTTP 400/404
New authentication:
  • X-Data-Application-Id (integer) + X-Data-Hash (SHA512) replaces X-API-Key
  • Webhook signatures changed from HMAC-SHA256 to SHA512 with X-Data-Hash header
New concepts:
  • service_id — integer mapping to provider + payment method combination
  • c_id / h_id / p_id — structured payment identifiers
  • Numeric error codes (1000-9000) replace HTTP status code-based errors
Removed:
  • REST endpoints (POST /api/v1/payments, GET /api/v1/balance, etc.)
  • X-API-Key authentication
  • P2P payment infrastructure (account-service, sms-service, qr-service)
  • Team management functionality
  • Device management functionality

​
v1.5.0 - In-Request Webhooks

​
2026-01-30
Per-Payment Webhook URLYou can now pass a webhook URL directly in the payment creation request, enabling per-payment notification routing without pre-configuring webhooks.New Features
  • webhook_url: Optional field in POST /payments — specify a URL to receive webhook events for this specific payment
  • webhook_events: Optional array to choose which events to subscribe to (defaults to payment.created, payment.completed, payment.failed)
  • Automatic deduplication: If the same merchant sends the same webhook_url across multiple payments, the system reuses the existing webhook configuration
  • Default webhook secret: In-request webhooks are signed using a per-merchant default secret, visible in the merchant settings panel
How it works
  • Pass webhook_url (and optionally webhook_events) when creating a payment
  • The system automatically creates (or reuses) a webhook endpoint for your merchant
  • Events are delivered to both admin-configured webhooks and in-request webhooks in parallel
  • In-request webhooks use SHA512 signature verification (updated in v2.0.0 from HMAC-SHA256)
API Changes
  • POST /payments now accepts optional webhook_url (string, max 2048 chars) and webhook_events (string array)
  • In-request webhooks are excluded from GET /webhooks listing by default (use ?source=in_request to view them)
  • Merchant detail response now includes default_webhook_secret field
Breaking changes
  • None (backwards compatible)

​
v1.4.0 - Webhook Security & Contract Stabilization

​
2026-01-20
Webhook Payload WhitelistImproved security and API contract stability for webhook payloads.Changes
  • customer_data in webhook payloads now uses a whitelist approach — only specific, documented fields are included
  • Internal processing data (IP addresses, user agents, internal IDs, processing metadata) is no longer sent to merchant webhooks
  • payout object is now only included for withdrawal type payments (not for deposits)
Allowed customer_data fields
  • Top-level: note, customer_email, customer_phone, customer_name, external_id, reference, description, expires_at, requested_payment_type
  • commission: currency, total_minor
  • payout (withdrawals only): bank_code, bank_account, recipient_name, bank_name
Breaking changes
  • Webhook payloads no longer include internal fields that were previously exposed unintentionally
  • If your integration relied on undocumented fields in customer_data, you may need to update your webhook handler

​
2025

​
December 2025

​
v1.3.0 - Customer Management System

​
2025-12-22
Customer Base & Payment LinkingNew customer management system that enables tracking and analytics across payments.New Features
  • Customer ID: Merchants can optionally pass customer_id when creating payments to link to an existing customer
  • Auto-linking: When customer_id is not provided, customers are automatically created/matched by email or phone
  • Customer Data in Response: Payment responses now include customer object with id, email, phone, name
API Changes
  • POST /payments now accepts optional customer_id field (integer)
  • Payment responses include customer_id and customer object
  • customer object in request body remains required (name, email, phone)
Breaking changes
  • None (backwards compatible)

​
v1.2.2 - Payment Page Enhancements

​
2025-12-03
Standalone Payment Page & Return URL SupportMajor improvements to the hosted payment page experience.New Features
  • Return URLs: Merchants can now provide success_url and cancel_url for merchant settings for automatic redirect after payment completion
  • Mercado Pago Integration: Quick-pay button with deep link support (mobile devices only)
Technical Changes
  • Improved bundle size and performance
  • Fixed SSE event handling for real-time payment status updates
  • Payment page now correctly updates UI when payment status changes via SSE
API Changes
  • GET /payment-pages/:token/details now returns return_urls object with success_url and cancel_url
Breaking changes
  • None (backwards compatible)

​
v1.2.1 - API Consistency & Validation

​
2025-12-02
API key format alignment and validation improvementsThis release fixes inconsistencies between API validation, documentation, and Swagger schemas.API Key Format Changes
  • Standardized API key format validation:
    • Test keys: qp_test_sk_* (e.g., qp_test_sk_abc123...)
    • Production keys: qp_prod_sk_* (e.g., qp_prod_sk_xyz789...)
  • Removed support for deprecated formats: qp_sandbox_sk_*, qp_live_*
  • Updated all documentation and Swagger examples to reflect correct key formats
Payment Status Updates
  • Added refunded and partial_refund statuses to payment API schemas
  • Payment pages now correctly display refund statuses
  • DTOs and filters now support filtering by refund statuses
Withdrawal Validation
  • recipient_name and bank_account are now required fields for withdrawal requests for ARS flow.
  • Improved error messages for missing payout details
  • Consistent validation across all withdrawal types
Documentation Fixes
  • Payment page URLs are now documented as dynamic (vary by currency/method/region)
  • Updated all code examples with correct API key formats
  • Clarified payout field requirements for different countries
Breaking changes
  • API keys using qp_sandbox_sk_* or qp_live_* formats will no longer be accepted
  • Withdrawal requests without recipient_name or bank_account will return 400 Bad Request

​
November 2025

​
v1.2.0 - Production Stability Release

​
2025-11-29
Major improvementsFollowing the successful scaling deployment, we shipped a set of optimizations based on real world usage patterns.Improvements
  • Optimized payment processing pipeline for higher throughput
  • Increased rate limits for payment creation to 5000 requests per minute (burst: 500 requests per 10 seconds)
  • Improved webhook delivery reliability and retry mechanism
  • More descriptive error messages for validation failures
Performance
  • Reduced average API response time by about 40%
  • Faster payment status transitions
Breaking changes
  • None
​
2025-11-25
Enhanced testing and quality of life
  • Improved consistency of API responses across endpoints
Breaking changes
  • None
​
2025-11-18
Optimization and refactors
  • Internal architecture improvements for better scalability
  • Enhanced payment method validation rules
  • Improved balance calculation accuracy
Breaking changes
  • None

​
October 2025

​
v1.1.0 - Webhooks Improvements

​
2025-10-30
Webhook manager improvementsNew features
  • Enhanced webhook signature binding for improved security and verification
Developer note
  • Make sure your webhook handlers are idempotent to safely handle retries.
Breaking changes
  • None
​
2025-10-24
Webhook delivery fixes
  • Fixed webhook signature generation for consistent verification on client side
  • Improved webhook retry logic with exponential backoff
  • Enhanced request binding for webhook payloads
Breaking changes
  • None
​
2025-10-22
Payment limits update
  • Corrected maximum amount validation rules
  • Improved amount formatting in API responses
Breaking changes
  • None
​
2025-10-17
Production deployment optimizations
  • Enhanced API key handling and validation
  • Improved error responses for invalid credentials
  • Added support for additional payment method configurations
Breaking changes
  • None
Deprecation notice
  • API key formats qp_sandbox_sk_* and qp_live_* are deprecated and will stop working in December 2025
  • Please use the standard formats: qp_test_sk_* for test mode, qp_prod_sk_* for production

​
September 2025

​
v1.0.2 - Integration Fixes

​
2025-09-14
Webhook flow corrections
  • Fixed payment.completed webhook not being sent in some scenarios
  • Improved webhook scheduling reliability
  • Enhanced stale webhook detection and cleanup
Breaking changes
  • None
​
2025-09-10
Balance and withdrawal improvements
  • Resolved issues with balance calculations
  • Fixed withdrawal validation edge cases
  • Improved payment and requisite lock expiry handling
Breaking changes
  • None
​
2025-09-08
API key and proxy compatibility
  • Fixed API key validation in specific edge cases
  • Improved proxy compatibility by handling X-Forwarded-Host headers
  • Strengthened request validation
Breaking changes
  • None
​
2025-09-05
Documentation updates
  • Updated API documentation with corrected parameters
  • Removed redundant request parameters
  • Improved example payloads
Breaking changes
  • None

​
August 2025

​
v1.0.1 - Private Beta Improvements

​
2025-08-28
Payment processing enhancements
  • Improved SPEI transfer handling
  • Enhanced bank account validation (CLABE format)
  • More informative error messages for invalid bank accounts
Breaking changes
  • None
​
2025-08-15
Webhook reliability improvements
  • Added automatic retry for failed webhook deliveries
  • Implemented webhook event deduplication
  • Enhanced HMAC-SHA256 signature verification
Developer note
  • Webhook receivers should remain idempotent due to retries and deduplication.
Breaking changes
  • None
​
2025-08-05
Balance API enhancements
  • Added /balance/all endpoint for multi-currency support
  • Improved balance precision handling
  • Added available and pending balance breakdown
Breaking changes
  • None

​
July 2025

​
v1.0.0 - Initial Release

​
2025-07-25
Public API v1.0.0 releasePublic release of the 123hub Payment Gateway API.Core features
  • Payment creation (deposits and withdrawals)
  • Multiple payment methods support
  • Hosted payment pages (deposit_pp, withdrawal_pp)
  • Real time webhook notifications
  • Balance inquiry API
  • Test and production modes via API key prefixes (qp_test_sk_*, qp_prod_sk_*)
Supported payment methods
  • bank_transfer - bank transfers (Argentina, Uruguay)
  • spei - Mexican interbank transfers (SPEI)
  • oxxo - cash payments at OXXO stores
  • card - credit and debit cards (tokenized)
  • cash - cash payments
  • crypto - cryptocurrency payments
Supported currencies
  • ARS - Argentine peso
  • UYU - Uruguayan peso
  • MXN - Mexican peso
Webhook events
  • payment.created - payment initialized
  • payment.processing - payment is being processed
  • payment.completed - payment successful
  • payment.failed - payment failed
  • payment.cancelled - payment cancelled
  • payout.created - payout initiated
  • payout.completed - payout successful
  • payout.failed - payout failed
​
2025-07-10
Private beta launch
  • Initial API endpoints for selected partners
  • Core payment functionality
  • Basic webhook support
  • Authentication via API keys

​
Versioning Policy

The 123hub API uses semantic versioning:
  • Major versions (v1, v2) indicate breaking changes
  • Minor versions add new features that are backwards compatible
  • Patches include bug fixes and minor improvements

​
Breaking changes

We strive to minimize breaking changes. When they occur:
  1. We announce them at least 1 month in advance
  2. We provide migration guides
  3. We support the previous version during a transition period

​
Deprecation policy

Deprecated features will:
  • Be announced in the changelog
  • Continue working for at least 3 months
  • Return deprecation warnings in API responses when possible

​
Upcoming Changes

These features are planned but not yet released. Timelines may change.

​
Q2 2026 (planned)

  • Refunds API - programmatic refund management
  • Transaction Reports - export transaction history and analytics
  • Merchant Settings API - configure merchant preferences via API
  • Batch Payouts - bulk payout operations (up to 1000 payouts per request)
  • Webhook Filtering - subscribe to specific event types and filter by criteria

​
Migration Guides

When breaking changes occur, we will publish detailed migration guides here.

API Status

Check current API status and subscribe to incident updates.