API Authentication

To authenticate requests to the Stable Mint Payments API, follow these steps:

1. Create a Public RSA Key

• After receiving your login credentials, visit the Stable Mint dashboard at: dashboard.stablemint.io

• Log in and navigate to the Developer Hub section of the dashboard.

• In the Developer Hub, you will be prompted to input and save your Public RSA Key. This key will be used to verify the authenticity of requests originating from your application.

• After saving your Public RSA Key, your API credentials (API Key and Secret) will be generated automatically.

2. Integrate Authentication

Required Headers

Every request must include the following headers:

1. Signature: A RSA-SHA256 signature of the string: "<TIMESTAMP>,<API_SECRET>,<REQUEST_BODY>"

2. Timestamp:Ok The current timestamp using Unix Epoch time in seconds.

3. ApiKey: The API Key provided by Stable Mint for authenticating requests.

Example Request Headers

ApiKey: <your API Key>
Timestamp: <current UNIX timestamp in seconds>
Signature: <Base64 encoded RSA-SHA256 signature>

Generating the Signature

1. String Construction:

   "<TIMESTAMP>,<API_SECRET>,<REQUEST_BODY>"

   • Replace <TIMESTAMP> with the current timestamp using Unix Epoch time in seconds.
   • Replace <API_SECRET> with your API Secret provided by Stable Mint.
   • Replace <REQUEST_BODY> with the raw JSON request body as a string.

2. Generate and sign the data:

   The string must be signed using RSA-SHA256 with your Private RSA Key. The signature is then base64 encoded.

   Below is an example of a function in Node.js using the built-in crypto module to generate the signature:

    import crypto from "crypto";
   
    function generateSignature(requestBody, apiSecret, privateKey) {
        const timestamp = Math.floor(Date.now() / 1000); // Unix timestamp in seconds
        const payload = JSON.stringify(requestBody); // Convert request body to string
        const dataToSign = `${timestamp},${apiSecret},${payload}`;
   
        const sign = crypto.createSign("SHA256");
        sign.write(dataToSign);
        sign.end();
   
        return {
            signature: sign.sign(privateKey, "base64"),
            timestamp,
        };
    }

3. Header Formation:

   Include all three headers in your request:

   ApiKey: <your_api_key>
   Timestamp: <unix_timestamp_in_seconds>
   Signature: <base64_encoded_signature>

Complete Example

Here's a complete example of making an authenticated request:

import crypto from "crypto";
import fetch from "node-fetch";

async function makeAuthenticatedRequest(endpoint, requestBody, apiKey, apiSecret, privateKey) {
    // Generate timestamp
    const timestamp = Math.floor(Date.now() / 1000);
    
    // Prepare the payload string
    const payload = JSON.stringify(requestBody);
    
    // Create signature string
    const dataToSign = `${timestamp},${apiSecret},${payload}`;
    
    // Sign the data
    const sign = crypto.createSign("SHA256");
    sign.write(dataToSign);
    sign.end();
    const signature = sign.sign(privateKey, "base64");
    
    // Make the request
    const response = await fetch(endpoint, {
        method: "POST",
        headers: {
            "Content-Type": "application/json",
            "ApiKey": apiKey,
            "Timestamp": timestamp.toString(),
            "Signature": signature
        },
        body: payload
    });
    
    return response.json();
}

// Example usage
const requestBody = {
    userId: "user123",
    userEmail: "[email protected]",
    userCountryCode: "US",
    currency: "EUR",
    amount: 100,
    // ... other fields
};

const result = await makeAuthenticatedRequest(
    "https://paymentinitiationservice-rest.stablemint.io/session/hosted/partner-managed-customer",
    requestBody,
    "your-api-key",
    "your-api-secret",
    privateKeyPem
);

Additional Notes

• Private Key Management: Keep your private key secure. It should never be shared or exposed in any form.
• Request Body: The entire raw JSON request body must be included in the signature string exactly as sent in the request.
• Timestamp: Use Unix timestamp in seconds (not milliseconds) for consistency with the server validation.
• Header Names: Headers are case-sensitive. Use ApiKey, Timestamp, and Signature exactly as shown.

3. Requests verification

Stable Mint will use your Public RSA Key to verify the authenticity of requests sent from your application. This ensures that only authorized requests are processed and maintains the integrity of data.

In case the signature verification fails or if any other error occurs during request processing, Stable Mint will return an HTTP status code 401 - unauthorized.