Secure Callback Endpoint

This document outlines the security mechanisms available for securing callback endpoints in our payment gateway solution. When payment events occur, our system sends callbacks to the client’s backend via HTTP requests. To ensure the integrity, authenticity, and security of these callbacks, we provide three complementary security methods:

1. Signature Verification in Header

2. IP Whitelist

3. Transaction Verification via API

Clients can implement one or more of these methods based on their security requirements.

---

1. Signature Verification in Header

Overview

A cryptographic signature is included in the Signature header of each callback request. This signature is generated by hashing the request body concatenated with a secret key using HMAC-SHA256. Clients can verify this signature to ensure the callback originates from our payment gateway and has not been tampered with.

Signature Generation

The signature is computed as follows:

• Algorithm: HMAC-SHA256

• Input: JSON stringified request body

• Key: Client-specific apiSecret

• Output: Hexadecimal string

Callback Request Format

• Method: POST (default, configurable)

• Headers:

  • Content-Type: application/json

  • Signature: <hmac-sha256-signature>

• Body: JSON payload containing payment event details

• Timeout: 5000ms (default, configurable)

Verification Examples

Below are sample implementations to verify the signature in various programming languages.

Typescript

import { createHmac } from 'crypto';

function verifySignature(body: any, signature: string, apiSecret: string): boolean {
    const computedSignature = createHmac('sha256', apiSecret)
        .update(JSON.stringify(body))
        .digest('hex');
    return computedSignature === signature;
}

PHP

function verifySignature($body, $signature, $apiSecret) {
    $computedSignature = hash_hmac('sha256', json_encode($body), $apiSecret);
    return hash_equals($computedSignature, $signature);
}

Java

import org.apache.commons.codec.digest.HmacUtils;
import com.fasterxml.jackson.databind.ObjectMapper;

// in case of using ApacheHttp
String secretKey = "YOUR_SECRET_KEY";
String responseBody = EntityUtils.toString(response.getEntity(), "UTF-8");
Header headerSignature = response.getFirstHeader("Signature").getValue();

// generate signature
String calculatedSignature = HmacUtils.hmacSha256Hex(secretKey, responseBody);

if(headerSignature.equals(calculatedSignature)) {
  System.out.println(responseBody);
} else {
  System.out.println("Invalid signature: " + responseData);
}

C#

public static string ComputeHmacSha256(string body, string secretKey)
{
  using (var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(secretKey)))
  {
    byte[] hash = hmac.ComputeHash(Encoding.UTF8.GetBytes(body));
    return BitConverter.ToString(hash).Replace("-", "").ToLower();
  }
}

String secretKey = "YOUR_SECRET_KEY";
String signature = response.Headers.GetValues("Signature").FirstOrDefault();
string responseBody = await response.Content.ReadAsStringAsync();

// generate signature
string calculatedSignature = ComputeHmacSha256(responseBody, secretKey);

if (headerSignature.Equals(calculatedSignature, StringComparison.OrdinalIgnoreCase))
{
  Console.WriteLine(responseBody);
}
else
{
  Console.WriteLine("Invalid signature: " + responseBody);
}

Best Practices

• Store the apiSecret securely (e.g., in environment variables).

• Use secure comparison functions (like hash_equals in PHP) to prevent timing attacks.

• Reject requests with missing or invalid signatures with a 401 Unauthorized response.

---

2. IP Whitelist

Overview

To restrict callback requests to trusted sources, we provide a fixed set of IP addresses from which callbacks will originate. Clients can whitelist these IPs in their firewall or application logic. Please contact AkashicPay support for a list of IPs to whitelist at [e-mail].

Best Practices

• Configure your environment to use the appropriate IP list (Testnet or Mainnet).

• Regularly check for updates to the IP list in our documentation.

• Log and monitor requests from non-whitelisted IPs for security auditing.

---

3. Transaction Verification via API

Overview

Clients can independently verify payment events by querying our Transaction Detail API using either an L1 or L2 transaction hash. This method confirms the validity of the payment event referenced in the callback.

API Endpoints

Base Domains

• Production: https://api.akashicscan.com

• Testnet: https://api.testnet.akashicscan.com

Endpoints

• L2 Hash Verification: GET /api/v0/transactions/transfer?l2Hash=<L2_HASH> Example: https://api.akashicscan.com/api/v0/transactions/transfer?l2Hash=AS123..

• L1 Hash Verification: GET /api/v0/transactions/hash?txHash=<L1_HASH> Example: https://api.akashicscan.com/api/v0/transactions/hash?txHash=0x123..

Response Format

• Status: 200 OK on success

• Body: JSON object with transaction details (structure depends on implementation)

• Error: 4xx/5xx status codes with error message on failure

Best Practices

• Use the appropriate domain based on your environment (Testnet or Production).

• Implement retry logic for transient network failures.

• Cache successful verifications to reduce API calls, if applicable.

---

Security Considerations

• Use HTTPS for all callback endpoints to encrypt data in transit.

• Implement rate limiting to prevent abuse.

• Log all verification failures for monitoring and auditing.

• Keep your apiSecret and other sensitive credentials secure.