API Reference

Overview

Introduction

The WARMKEY API is a RESTful service built for secure and efficient payment gateway operations. Authentication is handled through API keys, ensuring all requests are verified and authorized. Each user receives a pair of credentials: an API key and an RSA private key, similar to a username and password. Importantly, WARMKEY never stores a user’s RSA private key.

  • The API key is placed in header param of body request.
  • The RSA private key is used to generate signature, which ensures the integrity and authenticity of the requests.

By leveraging these keys, WARMKEY ensures a robust security mechanism that prevents unauthorized access while offering a flexible and scalable API for handling payment-related operations.

Base URL

https://api.warmkey.finance

The Base URL is the primary domain used by WARMKEY to receive API requests. Each API endpoint specifies its own unique URL path, and the full API endpoint URL is formed by combining the Base URL with the respective URL path.

For example, the full API request URL structure is:

{Base URL} + {Endpoint URL Path}

This structure allows WARMKEY to efficiently organize and handle different API requests, ensuring that each service call reaches the appropriate endpoint. All requests must begin with the Base URL followed by the specific path corresponding to the desired functionality.

Request

requestBody.header

These headers are compulsory to be included and it is located in request body, not HTTP header.

ParameterType / FormatDescription
api_keystringObtain your API key and its associated RSA private key from https://secure.warmkey.finance portal.
signaturestring / hex64-bytes signature generated from concatenation of $headers and $payload.
noncestring / milliseconds13 digits

Signature Generation

A signature is generated using RSA private key and will be included in signature param of header.


$signature_data = json_encode(["header"=>$headers, "payload"=>$payload]);
$to_sign = hash('sha256', $signature_data, true);
$your_private_key_pem = <<EOD
-----BEGIN PRIVATE KEY-----
MIIBVwIBADANBgkqhkiG9w0BAQEFAASCAUEwggE9AgEAAkEA1eerGN7aInrV0myN
5RYAVL58JsUQCdkIUYDLoupVLnhO8uw0DD5ooNwd8gT8KJU0UzKSpRN+sjSwutD3
ZMrvAQIDAQABAkEA1VLwmKIPa5mTSwLF1DTH6bv6tvOK1jdjC11mOLh4cRjoEw83
FzwSfuWlGyFGdir5PE5SK/1D8nZ41h8bnw9pAQIhAP/AQKUYlha+t7gGstFc+J6Z
9ZgoxT44ngyF5dE/4+FRAiEA1hz8Rpwwrm8pwp+kdho8guTwozmpvMrQYdRufjag
RrECIQCTtZrgf3m3+0CqlZvTlam2GF+jGPEKhbKqsu7P0uGvcQIhAIr1MtEMqxd6
M6sI+q5fZqg4tufoE33gTo8/VBp7j1dxAiEAsvhkqXu0AWvkJxVrCfQWiv5RMxAL
LXPLNzdej9IFEns=
-----END PRIVATE KEY-----
EOD;
$private_key = openssl_pkey_get_private($your_private_key_pem);
openssl_sign($to_sign, $signature, $private_key, OPENSSL_ALGO_SHA256);

Nonce

This is to prevent replay attack with certain tolerance level. User just put current milliseconds will do.

requestBody.payload

  • Each API endpoint has its own unique payload design
  • All param values are in string type, and format type has been specified also in API endpoint. Two reasons we design like this.
    • for ease of signature generation.
    • in crypto world, amount could be very big or very small, string is more suitable to handle this.

Code Sample

<?php

// Define the API credentials
$api_key = '<YOUR API KEY>'; // Replace with your API Key
$api_url = 'https://api.warmkey.finance'; // base url
$api_path = '/paymentV1/queryLog'; // path to reach getConversionRate

// Create a nonce (e.g, current miliseconds to ensure uniqueness)
$nonce = (string)round(microtime(true) * 1000);

// Define the payload (getConversionRate has empty payload)
$payload = [
	'log_id' => 1
];

// Generate the signature
$headers = [
    'api_key' => $api_key,
    'nonce' => $nonce
];

$signature_data = json_encode(["header"=>$headers, "payload"=>$payload]);
$to_sign = hash('sha256', $signature_data, true);
$your_private_key_pem = "<YOUR PRIVATE KEY IN PEM FORMAT>";
$private_key = openssl_pkey_get_private($your_private_key_pem);
openssl_sign($to_sign, $signature, $private_key, OPENSSL_ALGO_SHA256);
$headers["signature"] = bin2hex($signature);

$request_body = ["header"=>$headers, "payload"=>$payload];

// Prepare the cURL request
$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, $api_url.$api_path);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($request_body));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

// Execute the cURL request and get the response
$response = curl_exec($ch);

// Handle errors
if (curl_errno($ch)) {
    echo 'Error:' . curl_error($ch);
} else {
    echo 'Response:' . $response;
}

// Close the cURL session
curl_close($ch);
?>

Response & Errors

  • Response is in JSON document.
  • WARMKEY doesn't rely on HTTP code if exception occured.

Mandatory Parameters

ParameterType / FormatDescription
codestring / uint64Error if code != 100.
messagestringError message if code != 100.
resultgenericEach API endpoint has its own result design.
noncestring / milliseconds13 digits
signaturestring / hex64-bytes signature generated with hash256( json_encode['code'=>..., 'message'=>..., 'result'=> ..., 'nonce'=>...] )

For example,

{
	"code": "100",
	"message": "Success",
	"result": ["... some value ..."]
}

Success

CodeMessageDescription
100SuccessSuccess

General Errors

Code range from 101 to 199.

CodeMessage
101Invalid signature
102WARMKEY is under maintenance
103API key not valid
104Nonce not valid
105Rate limit exceeded
106API method not valid
107This API method is under maintenance

Payment Gateway Errors

Code range from 200 to 299.

CodeMessage
200Withdrawal denied. $reason
201Withdrawal denied. Unique ID was existed.
202No payment was made.