Skip to main content

​
Testing Guide

123hub provides a test mode that allows you to simulate transactions without processing real money. This guide covers how to use test mode effectively.

​
Test vs Production Mode

Test and production use the same API endpoint (POST /public/api/multihub/v1). The environment is determined by your credentials. Your 123hub account manager will provide separate test and production credential pairs.
Credential SetEnvironmentBehavior
Test application_id + secret_keyTestSimulated transactions, no real money
Production application_id + secret_keyProductionReal transactions, actual money movement

​
Getting Test Credentials

Test credentials are provided by the 123hub team during onboarding. You will receive:
  • application_id — an integer identifying your test application
  • secret_key — a private key used to sign requests in test mode
1

Request credentials

Contact your 123hub account manager or [email protected] to request test credentials.
2

Verify connectivity

Use the gateway.ping method to confirm your credentials work.
Contact [email protected] if you need test credentials.

​
Test Mode Behavior

​
Payments

  • Payments are created and go through normal status transitions
  • No actual bank transfers or card charges occur
  • Webhooks are delivered normally
  • All API responses mirror production behavior

​
Balance

  • Test mode uses a separate test balance
  • Initial test balance may be pre-funded for testing
  • Balance changes reflect test transactions only

​
Webhooks

  • Webhooks are delivered to your configured endpoints
  • Use webhook testing to verify your integration
  • Same signature verification as production

​
Simulating Payment Scenarios

​
Successful Deposit

Create a deposit payment using payment.in — it will transition through created to success status: 
curl -X POST "https://api.123hub.pro/public/api/multihub/v1" \
  -H "Content-Type: application/json" \
  -H "X-Data-Application-Id: 1" \
  -H "X-Data-Hash: <sha512_hash>" \
  -d '{
    "method": "payment.in",
    "service_id": 14701,
    "params": {
      "payment": {
        "description": "Test deposit order",
        "identifiers": { "c_id": 99001 },
        "amount": { "value": 10000, "currency": "INR" },
        "payer": {
          "email": "[email protected]",
          "phone": "9876543210",
          "person": { "first_name": "Test", "last_name": "Customer" }
        },
        "client": { "language": "EN", "country": "IN" }
      }
    }
  }'

​
Successful Withdrawal

Create a withdrawal payment using payment.out (requires sufficient test balance): 
curl -X POST "https://api.123hub.pro/public/api/multihub/v1" \
  -H "Content-Type: application/json" \
  -H "X-Data-Application-Id: 1" \
  -H "X-Data-Hash: <sha512_hash>" \
  -d '{
    "method": "payment.out",
    "service_id": 14701,
    "params": {
      "payment": {
        "description": "Test payout",
        "identifiers": { "c_id": 99002 },
        "amount": { "value": 5000, "currency": "INR" },
        "receiver": {
          "bank": {
            "account": { "id": "123456789012" },
            "ifsc": "SBIN0001234"
          },
          "email": "[email protected]",
          "person": { "first_name": "Juan", "last_name": "Perez" }
        },
        "client": { "language": "EN", "country": "IN" }
      }
    }
  }'

​
Check Payment Status

Query the status of a payment using payment.status: 
curl -X POST "https://api.123hub.pro/public/api/multihub/v1" \
  -H "Content-Type: application/json" \
  -H "X-Data-Application-Id: 1" \
  -H "X-Data-Hash: <sha512_hash>" \
  -d '{
    "method": "payment.status",
    "params": {
      "payment": {
        "identifiers": { "h_id": 1001 }
      }
    }
  }'

​
Error Response Example

All errors are returned with HTTP 200 and success: false. Here is an example of an invalid signature error: 
{
  "success": false,
  "error": {
    "code": 3000,
    "message": "Authentication error",
    "details": null,
    "context": null
  },
  "request_id": "f6a7b8c9-d0e1-2345-abcd-456789012345",
  "processing_time": 3
}

​
Testing Webhooks

​
Local Development

For local development, use a tunneling service like ngrok to expose your local server: 
# Start ngrok
ngrok http 3000

# Use the ngrok URL for your webhook endpoint
# https://abc123.ngrok.io/webhooks/123hub

​
Integration Checklist

Before going live, verify your integration handles these scenarios:
  • Compute X-Data-Hash correctly as sha512(requestBody + secretKey)
  • Send X-Data-Application-Id header with correct integer value
  • Verify gateway.ping returns a successful response
  • Store credentials securely (environment variables, not hardcoded)
  • Create deposit payments (payment.in) successfully
  • Create withdrawal payments (payment.out) successfully
  • Handle error responses gracefully (check success field)
  • Store h_id from response for subsequent status queries
  • Send unique c_id per payment to avoid duplicates (error 6001)
  • Retrieve payment status using payment.status with h_id
  • Handle all status values: created, processing, success, error, canceled, declined, refunded
  • Check the final field to determine if a payment has reached a terminal state
  • Check the success field to determine if a final payment was successful
  • Receive webhook notifications
  • Verify webhook signatures
  • Handle payment completion events
  • Handle payment failure events
  • Process events idempotently
  • Success returns HTTP 200, errors return HTTP 400/404 — always check success field
  • Handle error code 3000 (authentication error / invalid signature)
  • Handle error code 3003 (application not found)
  • Handle error code 2002 (no route available)
  • Handle error code 6004 (insufficient funds for withdrawals)
  • Handle error code 1005 (missing or invalid fields)
  • Handle network timeouts and retry with the same c_id
  • Check balance using balance.get before withdrawals
  • Handle insufficient funds errors (error code 6004)

​
Error Code Reference

CodeDescription
1000Common error
1002Method not available (HTTP 404)
1005Invalid request format (missing required field)
2002Payment provider not available
3000Authentication error (invalid signature)
3003Application not found
6001Incorrect transaction amount
6002Incorrect currency code
6004Insufficient funds
6009Payment already exists (duplicate c_id)
6010Payment does not exist
7001Provider interaction error
8801Invalid status transition
9000Validation error

​
Going Live

1

Complete Testing

Ensure all checklist items pass in test mode
2

Request Production Credentials

Contact your 123hub account manager or [email protected] to request production application_id and secret_key
3

Update Configuration

Replace test application_id and secret_key with production credentials in your production environment
4

Update Webhook URLs

Ensure webhooks point to your production server
5

Monitor

Watch the dashboard for your first live transactions
Never use production credentials in development or testing environments. Always keep test and production credentials separate.

​
Common Testing Mistakes

Using Production Credentials in Dev

Always use test application_id and secret_key in development

Skipping Signature Verification

Always verify webhook signatures, even in test mode

Not Testing Errors

Test error scenarios, not just happy paths. Verify your code checks the success field in every response.

Hardcoding Credentials

Use environment variables for application_id and secret_key

​
Need Help?

Developer Support

Contact our team if you have questions about testing