HMAC Authentication for OP Online Payment API

OP Online Payment API uses HMAC (Hash-based Message Authentication Code) authentication to authenticate requests. HMAC is used to verify the integrity of the data sent between the client and the API. This page describes how HMAC can be calculated from parameters.

See Online Payment REST API documentation >

Structure

The authorization header has four parts:

  • Merchant id
  • Algorithm to be used as as numeric value. Current options. 1 = SHA-256
  • Key version used in MAC calculation as a numeric value between 0 and 9999
  • The HMAC value.

The parts are joined into one string with colons (:).

The resulting value is {merchantId}:{algorithm}:{keyVersion}:{signature}

Creating the hash

The string to be hashed has the following structure

String stringToSign = HTTP method name + NEWLINE 
+ Content-Type + NEWLINE 
+ Date + NEWLINE 
+ merchantId + NEWLINE 
+ x-api-key + NEWLINE 
+ x-session-id + NEWLINE 
+ x-request-id + NEWLINE 
+ Full URL with query parameters + NEWLINE 
+ Message body;

The HTTP request must contain the date header.

Example value

String stringToSign = "POST" + "\n" 
+ "application\/json" + "\n"
+ "Wed, 06 Apr 2020 06:09:55 GMT" + "\n"
+ "8cef553-77df-48cc-bd1c-fb05dcfb64fa" + "\n"
+ "dxB2AFwnwraQRrAsLZpJ5T4IrNGp7fhx" + "\n"
+ "d6e17ef4-0832-4aef-a607-cedbcb5af62a" + "\n"
+ "f6938f25-c8a0-4a7c-b412-29cebe69a301" + "\n"
+ "https:\/\/api.op.fi:1234\/paymentbutton\/api\/v1\/m2m\/payment\/newPayment\/" + "\n"
+ "{'hello':'world'}";

For example with the following private key:

-----BEGIN PRIVATE KEY-----\n    
MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQCq4FH4inYm9rsb\n    
PIIFb\/tH1E\/eYX3sXG2JEYFvvjSZIoYUCq8lzzKyfP+GrFjzzqNjpg5naQtyvUi6\n    
7yCIFRP8rhpEi0zpBoSip989VeWxp6PJ3y+V6xYVI8a7dft\/5jKnj6B\/rtPkZL28\n    
Sb1dIhq3DqAiddWCoqT6gcm+B\/w2AUZ97v4XMYBh3P46+UHkNIVZxd2zh8HwIpkf\n    
vySRFxSGj+tnFT8y6Z9GBNz\/RaCmqAxfYt6JTPOmvX2Ep4l+LH8h8947epaI5ZdH\n    
ktZO4br87KxU9Rnw56mAwfkPaWAINDnmogQdXndduSjCH696Ex7JgFfts8pSAkEM\n    
WDQOWlC9AgMBAAECggEAToZZhRL0KwG1iFWtFpyYaDDsJzC8MnNjLtsplVVeTIUu\n    
AmXKiWCHVrjUoGnxUtFCCpgUBHekeCz+EFG1rHOrRLIphhhR1sBVEX59u20O6i40\n    
uZ9j+cwX0M0pFZqpYeRCoPgC9Mo9u7aD7tQgPn1es4L4Gf32iVr+39PnBvoacCIz\n    
nxAUdY4MW\/PgdDZRwtO\/AR+KEA9bUBro0TOCvTMpeR9EJ9spD0\/SfuCDfI+WdofY\n    
2hW7TZbboRt1dszoHcdQelZkFdOM\/oAE2MYMzlBAbygJJUkjyAoI9Bez1997DhJk\n    
01sDbNZTpGJP59aP379R1uoW3rTHmUANxmRcpyZrrQKBgQDWJE8hkvISNCXROgMZ\n    
ea5IGGuseK5o2HDuVAwmGbSf5NfzH5AmET7laYZNx2oniSv1LHm24rucNttc\/6RA\n    
5qz\/nvEbG07AW2DFal7EXYbBZLcQPe9chVUExeWbBs88rhKH4CQ1t6c6y1CzYhSV\n    
wRRXKddw4qXdPvD1GHp5Jsl0MwKBgQDMRv6d8ymPZbRIQ1mThGUFoZY15DHQk2DW\n    
76tPczY7Xz\/Z9UuCmQcH+Nenv8QfdnZF81DhGtt8nfzQECqJwcHdhthx2Fbbin5k\n    
BJpFd8KAN4zCcKVbFH+ewNKGT6Kn6GDcc6+nNnch9dXG4dQkB93lZdeWXHawL\/rJ\n    
udwW1GW3TwKBgGqjUjSp9JpUFbEHbpu1GLEWWChfQJs9jZ9hg1tF2cj2MQQFZ8dN\n    
N0EPN65r69UcXiONrl8AseSs\/LhnJeib9vKkt\/SDuMfZuWsV+XNYD88m1HLmJNiy\n    
HRBvbFOzJGhXVysK131Yo5KHxPxPj2iz6ekuEPdKJsbynROwyOykABY5AoGAaxY8\n    
nCjA\/L9gRxGnf8HEA7O1vwKlaqYX+hUiRUAsietg2a3Rq+D04qT8yJ+q\/KNpVTo8\n    
iAVAUo+v3JLc+eJs8uihxuyWe\/iaUWxoQ0qI2BZG4BeVV63jSSHkOyy8JDGZtXef\n    
+ZR\/13m8W8o\/H7RQCtXcsqI+Rhag7edVDVLDD9kCgYEAzjrCOi45+wmaWib\/yGKU\n    
kCLNmC2NYfyxgHXHsTKfC06CWpuchQBJnW06NxXjnSoZ6kPl4JPJv17gvd+UcXaR\n    
64nLLmZQl9ij4UW\/F6giq2T2hZu2yu2FQdASSY7PYPtIZZX6BuSxAWR++tGEidEw\n
Gf4XybYqmS2\/BrmS9Pvj164=\n
-----END PRIVATE KEY-----

the resulting string is as follows:

f8cef553-77df-48cc-bd1c-fb05dcfb64fa:1:0:7079ad6c16e54451ba80bad4f50423c659ddc627727f5e8a72ed4e58f4c9598d1b998a11d865b5d73af8c21661b79f16c7d5738b74e352f0bc548a0a3663f4fde9fda47ab2522efe8b415888bcc6e0ff8330d3718bdc01813db267047be85624b7682ac2595bfa65c62fd6fe8bef0c491590bb215e141f4b7ae9d06a697cc9a70870058db33a72c9e0142f7d456a68ab4c8af1fa038a8ab731a8e40d35e92535fe6676b8fd88dffe2c4fd1cba73c59e9bcf5b401049619646998ba3779ad60ddc3e3dadd2d222f2ba18a96792ecd6c3c3ad3c1e4e93cd4c3e3a7a56222bb8b2067f4e58b611ecdaf0a40c7758b284d0e9a4d8a8cd880a531b3d474ca6225b92c

This value is now ready to be used in the Authorization header.

Public key that matches private key in this example is:

-----BEGIN PUBLIC KEY-----\n
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAquBR+Ip2Jva7GzyCBW/7\n
R9RP3mF97FxtiRGBb740mSKGFAqvJc8ysnz/hqxY886jY6YOZ2kLcr1Iuu8giBUT\n
/K4aRItM6QaEoqffPVXlsaejyd8vlesWFSPGu3X7f+Yyp4+gf67T5GS9vEm9XSIa\n
tw6gInXVgqKk+oHJvgf8NgFGfe7+FzGAYdz+OvlB5DSFWcXds4fB8CKZH78kkRcU\n
ho/rZxU/MumfRgTc/0WgpqgMX2LeiUzzpr19hKeJfix/IfPeO3qWiOWXR5LWTuG6\n
/OysVPUZ8OepgMH5D2lgCDQ55qIEHV53Xbkowh+vehMeyYBX7bPKUgJBDFg0DlpQ\n
vQIDAQAB\n
-----END PUBLIC KEY-----