Skip to content
OMPAYOMPAY API Documentation

Request Headers

Merchants must include the following headers in all API requests made to OMPAY. These headers are used for authentication, tracking, and fraud prevention.

Header Name Description Example / Format Mandatory
X-Signature Derived signature for securing the request Refer to the Signature section Yes
X-MERCHANT-BROWSER-FINGERPRINT Unique browser fingerprint hash 8357426ac73fcd60b17355ab7de60421 Yes
X-MERCHANT-USER-AGENT User agent string representing the client browser Mozilla/5.0 (Linux; Android 13; I2203 Build/TP1A.220624.014; wv) AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0 Chrome/119.0.61.150 Mobile Safari/537.36 [FB_IAB/FB4A;FBAV/441.0.0.32.109;] Yes
X-MERCHANT-DOMAIN The merchant’s domain from where the API is called https://www.xyz.com Yes
X-MERCHANT-IP The IP address of the merchant making the request 11.123.123.212 No
Accept-Language The locale of the HTTP client (standard HTTP header). en-US (BCP 47 format) Yes

Signature Generation

Section titled “Signature Generation”

To ensure the integrity and authenticity of the API requests, each request must include an HMAC (Hash-based Message Authentication Code) signature. This signature is generated using the Client Secret and a combination of the API Path and Payload.

Signature Generation Function:

To generate the HMAC signature for an API request, follow the steps below:

const crypto = require('crypto');
function generateHMAC(clientSecret, apiPath, payload = "") {
  const dataToSign = apiPath + payload;
  const signature = crypto.createHmac('sha256', clientSecret)
    .update(dataToSign)
    .digest('hex');
  return signature;
}

Parameters

Section titled “Parameters”
Parameter Mandatory Description Type Example
clientSecret Yes The secret key assigned to you when you onboard with the payment gateway. String <your-client-secret>
apiPath Yes The API endpoint path, e.g., /order, /transaction/status. String /order
payload No (GET method) / Yes (POST method) The request body (optional for GET requests). For POST requests, this is the serialized JSON body of the request. String (JSON) "amount": 100,"currency":"OMR"
Example for POST Method
Section titled “Example for POST Method”

For a POST request, the payload is typically the request body sent in JSON format. Here’s an example:

const apiPath = '/order';
const payload = {
  amount: 100,
  currency: 'OMR',
  description: 'Test Purchase',
  customerFields: {
    name: 'Jhon Doe',
    email: 'johndoe@example.com',
    phone: '1234567890'
  },
  uiMode: 'checkout'
};
const clientSecret = '<your-client-secret>';
// Generate the HMAC signature for the POST request
const signature = generateHMAC(clientSecret, apiPath, JSON.stringify(payload));
Terminal window
curl --location --request POST '{{baseUrl}}/order' \
--header 'Authorization: Basic <your_credentials>' \
--header 'Content-Type: application/json' \
--header 'X-Signature: <generated_signature>' \
--header 'X-MERCHANT-BROWSER-FINGERPRINT: 8357426ac73fcd60b17355ab7de60421' \
--header 'X-MERCHANT-USER-AGENT: <user-agent>' \
--header 'X-MERCHANT-DOMAIN: https://www.xyz.com' \
--header 'X-MERCHANT-IP: 123.123.123.123' \
--data-raw '{
  "amount": 100,
  "currency": "OMR",
  "description": "Test Purchase",
  "customerFields": {
    "name": "Jhon Doe",
    "email": "johndoe@example.com",
    "phone": "1234567890"
  },
  "uiMode": "checkout"
}'
Example for GET Method
Section titled “Example for GET Method”

For a GET request, the signature is usually generated from the API path. Here’s an example:

const apiPath = '/transaction/status/paycbaff3b9dc5443f0ba0997970ebeddfa';
const clientSecret = '<your-client-secret>';
// Generate the HMAC signature for the GET request
const signature = generateHMAC(clientSecret, apiPath);
console.log('Generated Signature:', signature);
Terminal window
curl --location --request GET '{{baseUrl}}/transaction/status/{paymentId}' \
--header 'Authorization: Basic <your_credentials>' \
--header 'Content-Type: application/json' \
--header 'X-Signature: <generated_signature>' \
--header 'X-MERCHANT-BROWSER-FINGERPRINT: 8357426ac73fcd60b17355ab7de60421' \
--header 'X-MERCHANT-USER-AGENT: <user-agent>' \
--header 'X-MERCHANT-DOMAIN: https://www.xyz.com' \
--header 'X-MERCHANT-IP: 123.123.123.123'

Failure Responses

Section titled “Failure Responses”
ResCode Status Description
401 failure Signature missing in the request header.
401 failure Invalid signature. Request cannot be processed.