Authentication

All requests to EdfaPay APIs require secure authentication using a hash-based mechanism to validate request origin and ensure data integrity. EdfaPay employs a shared-secret hashing method for high security.

How Authentication Works

Authentication involves generating a hash using key fields and your merchant secret password. This hash is sent with the API request for data integrity and authenticity validation.

Hash Generation Logic

To generate the hash:

Required Fields:

payer_email: Customer's email address
card_number: Customer’s card (PAN) - use first 6 digits + last 4 digits only.
password: Secret hash password provided by EdfaPay.

Hash Formula:

HASH = MD5( UPPERCASE( Reverse(payer_email) + password + Reverse(first6PAN + last4PAN) ) )

Example - JavaScript Hash Generation

const password = "YOUR_SECRET_HASH_PASSWORD";
const email = "[email protected]";
const cardNumber = "5123456789012346"; // Full card number

const reverse = str => [...str].reverse().join('');

const baseString = reverse(email) + password + reverse(cardNumber.slice(0, 6) + cardNumber.slice(-4));
const finalHash = CryptoJS.MD5(baseString.toUpperCase()).toString();

console.log("Generated Hash:", finalHash);

📘
Note: Use CryptoJS.MD5 or a similar MD5 hashing utility in your backend language.

Sending the Hash

Include the generated hash in your request as a field named hash.

--form 'hash="e3aab9d93e1b43a0a872bd8442f76c01"'

Authentication & Security Best Practices

Practice	Description
Hash Server-side	Always generate the hash on the server, never client-side.
Use HTTPS	All API endpoints require HTTPS; HTTP requests will be blocked.
Keep Secret Password Safe	Do not hardcode your password; store it in secure environment variables.
Limit IPs (if applicable)	Optionally restrict access to known IPs (contact support).
Monitor Activity	Track unusual transaction volume or failed hash verifications.
Secure Webhooks	Validate incoming hashes on webhook responses to verify authenticity.

❗️
The hash in the request payload is used solely to ensure the integrity of the request and is not related to the hash included in webhook notifications.
For validating webhook notifications, please refer to Webhook Validation.

Authentication Request Possible Errors

Error Code	Message	Cause	Action
`AUTH_HASH_MISSING`	Hash value is missing	The `hash` field was not sent.	Ensure hash is included in request.
`AUTH_HASH_INVALID`	Hash mismatch	Incorrect hash, wrong password, or incorrect fields.	Regenerate hash and check all values.
`MERCHANT_DISABLED`	Merchant account is disabled	Your EdfaPay account is not active.	Contact support.
`INVALID_CLIENT_KEY`	Invalid client key	Wrong `client_key` or malformed value.	Verify `client_key` is correct.
`UNSECURE_CONNECTION`	Request not over HTTPS	Request sent via HTTP.	Always use HTTPS endpoints.

❗️
Important Notes:

Include a valid hash in every payment-related request (SALE, AUTH, RECURRING, etc.).

The full card number is only used during hash generation, not sent with the final payload.

If the hash does not match on the server, the request will be rejected immediately.