Class MaksuPay

java.lang.Object
com.maksupay.paysdk.MaksuPay
public class MaksuPay extends Object

  • Field Details

  • Constructor Details

    • MaksuPay

      public MaksuPay()

  • Method Details

    • createMaksuPayRequest

      public String createMaksuPayRequest(String merchantKey, String merchantCert, Map<String,String> requestParams) throws GeneralSecurityException
      Creates a MaksuPay request string from the specified request parameters.

      This method typically serializes or concatenates the provided parameters into the format expected by the MaksuPay backend.

      Parameters:
      merchantKey - Merchant private key in PKCS#8 PEM format.
      merchantCert - Merchant certificate (X.509 PEM) containing the public key corresponding to the signing private key.
      requestParams - A map containing the request parameters, where the key is the parameter name and the value is the corresponding value.
      Returns:
      A string representing the formatted MaksuPay request that can be sent to the payment gateway via HTTP POST.
      Throws:
      NullPointerException - if merchantKey, merchantCert or requestParams is null.
      GeneralSecurityException - if the private key is invalid or the signing operation fails.

    • createMaksuPayRequestAsForm

      public String createMaksuPayRequestAsForm(String merchantKey, String merchantCert, String maksuURL, Map<String,String> requestParams) throws GeneralSecurityException
      Creates a MaksuPay request html form string from the specified request parameters.

      This method typically serializes or concatenates the provided parameters into the format expected by the MaksuPay backend.

      Parameters:
      merchantKey - Merchant private key in PKCS#8 PEM format.
      merchantCert - Merchant certificate (X.509 PEM) containing the public key corresponding to the signing private key.
      maksuURL - MaksuPay url
      requestParams - A map containing the request parameters, where the key is the parameter name and the value is the corresponding value.
      Returns:
      A string representing the formatted MaksuPay request that can be sent to the payment gateway via HTTP POST.
      Throws:
      NullPointerException - if merchantKey, merchantCert or requestParams is null.
      GeneralSecurityException - if the private key is invalid or the signing operation fails.

    • validateResponse

      public boolean validateResponse(String maksuCerts, Map<String,String> responseParams)
      Validates a MaksuPay response signature using the provided certificates and response parameters.

      This method reconstructs the canonical signature base string from the provided parameters, extracts the signature from responseParams, and verifies it using the public key extracted from maksuCerts.

      Parameters:
      maksuCerts - The public certificate or certificate bundle used to verify the response signature. Must contain the public key corresponding to the signing key.
      responseParams - A map containing the response parameters returned by the MaksuPay gateway. The map must include the signature field (and publicKeyHash if sent), along with all parameters required to construct the signature base string.
      Returns:
      true if the response signature is valid; otherwise false.
      Throws:
      NullPointerException - if maksuCerts or responseParams is null.
      IllegalArgumentException - if the signature value in responseParams is malformed or cannot be decoded.

    • validateResponse

      public boolean validateResponse(X509Certificate[] maksuCerts, Map<String,String> responseParams)
      Validates a MaksuPay response signature using the provided certificates and response parameters.

      This method reconstructs the canonical signature base string from the provided parameters, extracts the signature from responseParams, and verifies it using the public key extracted from maksuCerts.

      Parameters:
      maksuCerts - The array of public certificates or certificate bundles used to verify the response signature. Must contain the public key corresponding to the signing key.
      responseParams - A map containing the response parameters returned by the MaksuPay gateway. The map must include the signature field (and publicKeyHash if sent), along with all parameters required to construct the signature base string.
      Returns:
      true if the response signature is valid; otherwise false.
      Throws:
      NullPointerException - if maksuCerts or responseParams is null.
      IllegalArgumentException - if the signature value in responseParams is malformed or cannot be decoded.

    • calculateSignature

      public static String calculateSignature(byte[] data, String privateKey) throws GeneralSecurityException
      Calculates a digital signature for the specified data using the provided private key.

      This method typically computes the signature using RSA with SHA-256 (RS256), but the actual algorithm depends on the implementation of the underlying cryptographic provider. Ensure that the private key corresponds to the public key used to validate the signature on the receiving side.

      Parameters:
      data - The raw byte array containing the data to be signed.
      privateKey - The private key in PEM or another compatible string format used to generate the digital signature.
      Returns:
      A Base64-encoded string representing the generated digital signature.
      Throws:
      NullPointerException - if data or privateKey is null.
      GeneralSecurityException - if the private key is invalid or the signing operation fails.

    • sendAPIRequest

      public static HttpResponse<byte[]> sendAPIRequest(String apiURL, int timeout, String merId, PrivateKey merchantKey, X509Certificate merchantCert, Map<String,Object> request, StringBuilder requestHeadersDbg) throws GeneralSecurityException, IOException, InterruptedException
      Sends a MaksuPay API JSON request to the specified HTTPS endpoint with a signature and other required headers.

      This method serializes the request parameters, signs the payload using the provided RSA private key, attaches certificate information, applies the timeout settings, and submits the HTTPS POST request to the MaksuPay API.

      Parameters:
      apiURL - The full HTTPS API endpoint URL to which the request will be sent.
      timeout - The request timeout in milliseconds. A network-related exception may be thrown if the timeout is exceeded.
      merId - The merchant identifier assigned by MaksuPay.
      merchantKey - The merchant's RSA private key used to generate the request signature.
      merchantCert - The merchant’s X.509 certificate corresponding to the signing private key and optionally used to include certificate metadata in the request.
      request - A map containing the request message to be serialized to JSON and signed before sending to the MaksuPay API. Keys represent parameter names and values represent the parameter values.
      Returns:
      The HTTP response returned by the MaksuPay server. The caller is responsible for reading and closing the response body.
      Throws:
      NullPointerException - if apiURL, merId, merchantKey, merchantCert or request is null.
      InterruptedException - if the request is interrupted
      IOException - if the HTTP request fails due to connection or TLS errors.
      GeneralSecurityException - if signing the request with merchantKey fails.

    • sendAPIRequest

      public static HttpResponse<byte[]> sendAPIRequest(String apiURL, int timeout, String merId, String merchantKey, String merchantCert, String request) throws GeneralSecurityException, IOException, InterruptedException
      Throws:
      GeneralSecurityException
      IOException
      InterruptedException

    • sendAPIRequest

      public static HttpResponse<byte[]> sendAPIRequest(String apiURL, int timeout, String merId, String merchantKey, String merchantCert, String request, StringBuilder requestHeadersDbg) throws GeneralSecurityException, IOException, InterruptedException
      Throws:
      GeneralSecurityException
      IOException
      InterruptedException

    • calculateSignatureForJSONHeader

      public static String calculateSignatureForJSONHeader(byte[] data, String privateKey) throws GeneralSecurityException
      Calculates a digital signature for the specified data using the provided private key. Useful for creating a payload signature for a JSON API message, typically used in the X-Payload-Signature HTTP header.

      This method typically computes the signature using RSA with SHA-256 (RS256), but the actual algorithm depends on the implementation of the underlying cryptographic provider. Ensure that the private key corresponds to the public key used to validate the signature on the receiving side.

      Parameters:
      data - The raw byte array containing the data (JSON message body) that will be signed.
      privateKey - The private key in PEM or another compatible string format used to generate the digital signature.
      Returns:
      A Base64-encoded string representing the generated digital signature, prefixed with "RSA-SHA256;".
      Throws:
      NullPointerException - if data or privateKey is null.
      GeneralSecurityException - if the private key is invalid or the signing operation fails.

    • calculateSignatureForJSONHeader

      public static String calculateSignatureForJSONHeader(byte[] data, PrivateKey privateKey) throws GeneralSecurityException
      Calculates a digital signature for the specified data using the provided private key. Useful for creating a payload signature for a JSON API message, typically used in the X-Payload-Signature HTTP header.

      This method typically computes the signature using RSA with SHA-256 (RS256), but the actual algorithm depends on the implementation of the underlying cryptographic provider. Ensure that the private key corresponds to the public key used to validate the signature on the receiving side.

      Parameters:
      data - The raw byte array containing the data (JSON message body) that will be signed.
      privateKey - The private key in PEM or another compatible string format used to generate the digital signature.
      Returns:
      A Base64-encoded string representing the generated digital signature, prefixed with "RSA-SHA256;".
      Throws:
      NullPointerException - if data or privateKey is null.
      GeneralSecurityException - if the private key is invalid or the signing operation fails.

    • validateApiResponse

      public static boolean validateApiResponse(String maksuCerts, String pkHash, String sigB64, byte[] data)
      Validates a MaksuPay API response signature using the provided certificates and response parameters.
      Parameters:
      maksuCerts - The public certificate or certificate bundle used to verify the response signature. Must contain the public key corresponding to the signing key.
      pkHash - The public hash from the X-Public-Key-Hash header to validate, provided as a raw byte array (typically Base64-decoded bytes).
      sigB64 - The digital signature from the X-Payload-Signature header to validate, provided as a raw byte array (typically Base64-decoded bytes).
      data - The raw byte array representing the original data that was signed.
      Returns:
      true if the response signature is valid; otherwise false.
      Throws:
      NullPointerException - if maksuCerts, pkHash, sigB64 or data is null.

    • validateApiResponse

      public static boolean validateApiResponse(X509Certificate[] maksuCerts, String pkHash, String sigB64, byte[] data)
      Validates a MaksuPay API response signature using the provided certificates and response parameters.
      Parameters:
      maksuCerts - The array of public certificates or certificate bundles used to verify the response signature. Must contain the public key corresponding to the signing key.
      pkHash - The public hash from the X-Public-Key-Hash header to validate, provided as a raw byte array (typically Base64-decoded bytes).
      sigB64 - The digital signature from the X-Payload-Signature header to validate, provided as a raw byte array (typically Base64-decoded bytes).
      data - The raw byte array representing the original data that was signed.
      Returns:
      true if the response signature is valid; otherwise false.
      Throws:
      NullPointerException - if maksuCerts, pkHash, sigB64 or data is null.

    • getVersion

      public static String getVersion()

    • validateSignature

      public static boolean validateSignature(PublicKey publicKey, byte[] data, byte[] signature) throws GeneralSecurityException
      Validates a digital signature against the specified data using the provided RSA public key.

      This method typically performs RSA verification using SHA-256 (RS256), depending on the capabilities of the underlying cryptographic provider. Ensure that the signature bytes match the signing algorithm and padding mode used to generate the signature.

      Parameters:
      publicKey - The RSA public key used to verify the signature. Must correspond to the private key that generated the signature.
      data - The raw byte array representing the original data that was signed.
      signature - The digital signature to validate, provided as a raw byte array (typically Base64-decoded bytes).
      Returns:
      true if the signature is valid for the given data and public key; otherwise false.
      Throws:
      NullPointerException - if publicKey, data, or signature is null.
      GeneralSecurityException - if the verification process fails due to an invalid key, incorrect format, unsupported algorithm, or other cryptographic-related issues.

    • validateSignatureJSONHeader

      public static boolean validateSignatureJSONHeader(PublicKey publicKey, String xPayloadSignature, byte[] data) throws GeneralSecurityException
      Validates a digital signature against the specified data using the provided RSA public key.

      This method typically performs RSA verification using SHA-256 (RS256), depending on the configuration of the underlying cryptographic provider. Ensure that the xPayloadSignature bytes match the signing algorithm and padding mode used to generate the signature.

      Parameters:
      publicKey - The RSA public key used to verify the signature. Must correspond to the private key that was used to generate the signature.
      xPayloadSignature - The digital signature from the X-Payload-Signature header to validate, provided as a raw byte array (typically Base64-decoded bytes).
      data - The raw byte array representing the original data that was signed.
      Returns:
      true if the signature is valid for the given data and public key; otherwise false.
      Throws:
      NullPointerException - if publicKey, data, or xPayloadSignature is null.
      GeneralSecurityException - if the verification process fails due to an invalid key, incorrect format, unsupported algorithm, or other cryptographic-related issues.

    • publicKeySHA256Hash

      public static String publicKeySHA256Hash(String certificate) throws GeneralSecurityException
      Throws:
      GeneralSecurityException

    • publicKeySHA256Hash

      public static String publicKeySHA256Hash(X509Certificate cert) throws GeneralSecurityException
      Throws:
      GeneralSecurityException