Merchant API Key

Overview

The merchant key belongs to the merchant backend

A merchant API key is a credential that lets a merchant's software access payment functions on a provider. In the OxaPay integration model, it is used for authorized payment API operations and also, according to the current webhook guide, as the shared secret for validating payment callbacks. That second role can be surprising: the same string may be relevant both when your server sends requests and when it verifies incoming notifications. Neither use makes it a blockchain private key; the provider's API permissions determine what it can do.

How the underlying system works

OxaPay's Payment Information endpoint documents a <code>merchant_api_key</code> request header, and invoice creation uses the merchant integration's authentication. A server should load this key from protected configuration, make API requests over HTTPS and return only the data that the customer interface needs. Scope credentials to the relevant integration and rotate them when operating procedures or suspected exposure require it.

The merchant key also appears in OxaPay's webhook verification guidance as shared secret material for payment callback HMACs. That creates a particularly strong reason to avoid embedding it in client-side JavaScript or exposing it through error logs. Payout functions use separate payout credentials; do not assume the merchant key can authorize every service.

Trace a request and a callback

A store's server creates a crypto invoice by sending an authorized API request. The provider returns a track ID and a payment URL, which the server attaches to the order. Later a callback arrives. The server computes the documented HMAC over the raw body using the appropriate merchant credential and compares it to the header. Only then does it check which order the track ID belongs to and what the reported payment state permits. If the key were published in website JavaScript, an attacker could have information necessary to impersonate authorized API calls or signed notifications, depending on the provider's policies.

Keys need ownership and rotation

Store the key in environment-based secrets or a comparable secure store, not in front-end code, a Git repository or an exported analytics report. Define who can rotate it, where the updated value must be deployed, and how payment callback handling will continue during a rotation. Do not use a merchant key to authorize outbound disbursements when separate payout credentials are documented. Treat credential changes as operational events that require tests and monitoring, not merely as replacing a string in a file.

Further reading and related concepts

Reference documents: OxaPay — Payment Information, OxaPay — Webhook.

Related glossary topics: API Key, Webhook Signature, Payment Status API.