Best Practices

Follow these recommendations for a reliable, safe integration.

Authentication

🔒

Store credentials as secrets

Never put userId or password in source code, logs, or client-side code. Use environment variables or a secrets manager.

Do

🌐

Use the right environment URL

Sandbox credentials only work at sandbox.valuetopup.com. Production at valuetopup.com. Never mix them.

Do

Transactions

🔑

Always use a correlation ID

Every transaction request needs a unique correlation ID from your system. Without it you cannot recover from timeouts.

Do

⚠️

Don't retry without checking first

On timeout, call Check Status before retrying. A timed-out transaction may have succeeded and your account may already be charged.

Don't

✅

Check responseCode, not just HTTP

All responses return HTTP 200. A transaction is only complete when responseCode = "000".

Do

📋

Refresh the product catalog regularly

Never hardcode skuIds. Pricing and availability change in real time. Refresh /catalog/skus at least every 24 hours.

Do

Error handling

Always read the responseCode and responseMessage to surface actionable feedback. For example, distinguish 510 (SKU out of stock — suggest a different product) from 501 (invalid subscriber — ask user to re-enter the number). Use GET /api/v2/catalog/errors to fetch the full list of error codes and their descriptions.