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

​
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 the same HMAC-SHA256 signature verification as admin webhooks
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.

​
December 2025 (planned)

  • Support Tickets API - create and manage support tickets programmatically
  • Payment Disputes - dispute management and resolution endpoints
  • Enhanced Error Codes - more granular error codes for better debugging

​
Q1 2026 (planned)

  • Refunds API - programmatic refund management
  • Transaction Reports - export transaction history and analytics
  • Merchant Settings API - configure merchant preferences via API

​
Q2 2026 (planned)

  • Additional currencies - BRL (Brazilian real), CLP (Chilean peso)
  • 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.