Skip to main content

​
Authentication with Omnispay

To get authenticated and start making API calls, you’ll first need to retrieve your API key from the Omnispay dashboard. Prerequisite: Generate an API Key Before making API requests, the merchant must generate an API key by sending a request to the API. The response will contain the API key details, which should be used to authenticate subsequent requests.

​
Step 1: Retrieve your API Key

To obtain your API key:
  1. Log in to your Omnispay dashboard.
  2. Navigate to the Developer Page.
  3. Copy your API Key from the page.

​
Step 2: API Key Validation

Before making any request, the client must include an API key in the request header. Upon receiving the request, the backend will perform the following:
  1. Check the API Key:
    • First check if the request contains a valid API key in the header.
    • Verify whether the API key has the proper access to the requested endpoints.
    • Check if the request originates from an IP address that has been granted permission for that API key.
    • If all these validations pass, the user can access the requested resources.
    • If the URL or IP does not have the necessary permissions, the user can update their allowed endpoints and IP addresses against the API key.
    • If the API key is missing, the request will be rejected with a proper error message.

​
Step 3: HMAC Authentication Using Secret Key

After validating the API key, Omnispay provides a secret key to each merchant during API key creation. This key must be used for HMAC-based authentication.

​
🔐 How HMAC Works

HMAC (Hash-based Message Authentication Code) ensures that the message is:
  • Authentic (sent by a trusted party),
  • Untampered (not altered in transit).
You generate an HMAC by hashing the payload or message (e.g., request body or query) using your secret key and a cryptographic algorithm like HmacSHA256. The server then verifies this signature using the stored secret key.
💡 The secretKey is issued securely by Omnispay Admin when the API key is created. This must be stored securely and never exposed publicly.

​
🔗 External References

  • RFC 2104 – HMAC: Keyed-Hashing for Message Authentication
    The original HMAC specification from the Internet, along with explanations, examples, and use cases. This reference provides a comprehensive understanding of how HMAC ensures data integrity and authenticity using a shared secret key.

​
✅ Sample HMAC Validation Code (Java)

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.nio.charset.StandardCharsets;
import java.util.Base64;

public class HmacUtil {
    /**
     * Generates a Base64-encoded HMAC SHA-256 for the given data using the provided secret key.
     */
    public static String generateHmac(String data, String secretKey) {
        try {
            Mac mac = Mac.getInstance("HmacSHA256");
            SecretKeySpec secretKeySpec = new SecretKeySpec(secretKey.getBytes(StandardCharsets.UTF_8), "HmacSHA256");
            mac.init(secretKeySpec);
            byte[] hmacBytes = mac.doFinal(data.getBytes(StandardCharsets.UTF_8));
            return Base64.getEncoder().encodeToString(hmacBytes);
        } catch (Exception e) {
            // Log exception as per your application's logging strategy
            e.printStackTrace();
            return null;
        }
    }
}
Please note: All connections to the API are server-to-server. Access is permitted only from authenticated sources or explicitly whitelisted IP addresses.