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, availability, and face values change in real time. Refresh /catalog/getproducts, /catalog/skus and /catalog/skus/giftcards at least every 24 hours.In addition to the scheduled refresh, you'll receive an email notification whenever a price or face value changes. Treat this as a signal to refresh your cached catalog immediately, rather than waiting for your next 24-hour cycle — this prevents customers from seeing outdated pricing or denominations in the interim.

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.