Skip to main content

API Signature

SSO Login Authentication​

info

Integrations start with the login API, which authenticates the customer. Authentication method: HMAC hash the ssoCustomerId with the key issued by the payment gateway system.

Authentication Flow​

The merchant site creates an SSO hash for the logged-in user with the shared key based on ssoCustomerId, then passes that hash to the login API. The login API validates the hash and issues a JWT bearer token for subsequent API access. Below is a Node.js example of sending the Authorization header in API requests.

tip

The ssoCustomerId must stay consistent across the entire authentication flow to ensure the signature can be verified and the related requests map to the same user.

Node.js Example for Creating & Validating the Hash​

const crypto = require('crypto')
const sharedSecretKey = 'abcdef12-abcd-abcd-abcd-abcdef012345' // Secret key emailed after onboarding
const sso_customer_id = '' // Merchant-defined unique id

const hash = crypto
	.createHmac('sha256', sharedSecretKey)
	.update(sso_customer_id)
	.digest('hex')
warning

Store the key securely on the merchant backend as a secret. Never expose it to frontend code.

Authentication Failure Response​

{ "message": "Missing Authentication Token" }

Public API Signature​

note

Merchants must add this signature to the http header when calling the payment gateway system public APIs.

warning

The fields inside the body must follow the order defined in the documentation before calculating the signature, otherwise verification fails.

Node.js example

const ssoOrderId =  "API-TEST-NUVEI-TESTER-03"
const sign = crypto
  .createHmac('sha256', YourSecretKey) // Secret key issued by the payment gateway system
  .update(ssoOrderId)
  .digest('hex');

const body = {
    ssoOrderId: ssoOrderId,
    merchantId: "1" ,
    sign: sign,
    status:'S'
}

const hash = crypto
  .createHmac('sha256', YourSecretKey)  // Secret key issued by the payment gateway system
  .update(JSON.stringify(body))
  .digest('hex');

const url = 'https://api-onramp.eopay.io/webhook/update-order-status'
const response = await fetch(url, {
    method: 'POST',
    body: JSON.stringify(body),
    headers: { 'X-HMAC-SIGNATURE': hash}
})

Refund & Update Order Status Signature​

note

Merchants must add this signature to the http header when calling the payment gateway system public APIs.

warning

The fields inside the body must follow the order defined in the documentation before calculating the signature, otherwise verification fails.

Node.js example

const sign = crypto
    .createHmac('sha256', YourSecretKey) // Secret key issued by the payment gateway system
    .update(ssoOrderId) // Merchant-defined ssoOrderId
    .digest('hex');

const url = 'https://api-onramp.eopay.io/payment/refund-payment'
const response = await fetch(url, {
    method: 'POST',
    body: JSON.stringify(body),
    headers: { 'X-HMAC-SIGNATURE': hash}
})

Get Order Status Signature​

const data = { ssoOrderId: 'ssoOrderId', merchantId: 'merchantId' }
const hash = crypto
            .createHmac('sha256', YourSecretKey)
            .update(JSON.stringify(data))
            .digest('hex');

const url = 'https://api-onramp.eopay.io/order/get-sso-order-status'
const response = await fetch(url, {
    method: 'POST',
    body: JSON.stringify(data),
    headers: { 'X-HMAC-SIGNATURE': hash}
})