An API key lets your application make payment requests under your merchant account. It belongs in your server configuration, not in the checkout page, a public repository or a screenshot sent to support. This guide explains how to manage the Trust Gateway key through an application's deployment and maintenance cycle.
- Identify every server, worker and bot that uses the current key.
- Keep secrets out of browser bundles and public URLs.
- Prepare the replacement deployment before rolling a key.
- Check one authenticated request and one complete order flow afterward.
Keep the key behind your backend
A customer's browser should ask your backend to start a purchase. Your backend calculates the price, associates the purchase with your own order record, and calls the gateway using its private configuration. The browser can then receive the checkout destination. This separates the customer's payment interface from the credential that authorizes your integration.
For the current order-create endpoint, x-api-key is a supported authentication header. Use the current API documentation for the full request. Prefer the header over putting a secret in a URL, which is more likely to be copied into browser history, access logs or support messages. A public hosted payment link is not a reason to disclose the merchant API key.
Store one deliberate value per deployment
Put the key in your hosting platform's private environment settings or a secret store. Read it only in server-side code. In a React application, do not place it in a browser-exposed environment variable; the value can be embedded in the downloaded application even when no input field displays it. Check compiled output when reviewing an integration prepared by a third party or coding assistant.
Maintain an inventory of consumers: the web server, scheduled jobs, queue workers and messaging bots may each load their own copy. Record configuration names and deployment owners rather than secret values in that inventory. Restrict production access to people and services that need it. If a key has already entered a public repository, removing the visible line does not remove every historical copy.
Understand what Roll Key changes
The API key interface includes a Roll Key action and a confirmation explaining that existing applications must be updated. The current implementation replaces the stored key for the merchant. It does not provide a period in which the old and new keys both authenticate new requests.
Plan a brief controlled change window instead of assuming zero downtime. If a key was exposed, prioritise replacing it and restoring integrations with the new value. A key change is separate from a login-password change and from changing a connected receiving account. Do not assume that one operation rotates every other credential used by your business.
A practical replacement runbook
- Identify pending business orders and every service that creates payment requests.
- Prepare access to the private configuration for each consumer, and arrange to pause new order creation if necessary.
- Use the authenticated merchant interface to roll the key once.
- Update the private server configuration and restart or redeploy consumers that load configuration at startup.
- Make one controlled authenticated order request, saving the returned order reference.
- Verify the intended receiver and complete a controlled payment if required for your release check.
- Resume normal traffic and check errors across all consumers.
Do not repeatedly roll the key while debugging: each replacement makes another value obsolete. Existing checkout attempts also deserve separate attention. Preserve their references and inspect their status before creating replacement orders. The API error-handling guide explains why a failed client request is not sufficient evidence that no order exists.
Diagnose authentication failures in order
| Observation | What to inspect |
|---|---|
| Invalid or inactive API key | The deployed value, accidental whitespace and the merchant integration status |
| One worker fails after rotation | Whether that worker restarted and loaded the replacement configuration |
| Subscription-required response | The merchant's current access status rather than repeatedly changing the key |
| Gateway not configured | The receiving connection and route; authentication alone does not configure a receiver |
Read the response body along with its HTTP status. Different checks can reject a request for different reasons. Log the route, response code, timestamp and a correlation identifier; redact authentication headers and tokens. If support needs a sample request, replace secret values with an obvious placeholder before sending it.
Finish with an integration check
Successful authentication confirms only that the request can act under the intended account. Check the amount, receiving identity, order status and your fulfilment result too. Keep duplicate-delivery handling in place, and do not grant a product merely because a customer returned from a hosted checkout.
Use the checkout test matrix after changing production configuration. For AI-assisted implementation, give the assistant requirements and placeholder variable names through the integration prompt workflow, then supply the real secret through your hosting environment.