Package net.libyaguide.gpay.sdk.client

Class GPayApiClient

java.lang.Object
net.libyaguide.gpay.sdk.client.GPayApiClient
public class GPayApiClient extends Object
GPayApiClient provides a client for interacting with the GPay Payment API.

This client handles authentication, request signing, and response verification for all supported endpoints.

Authentication:

  • API Key: Used as a Bearer token in the Authorization header.
  • Secret Key: Used for HMAC-SHA256 signing of requests and responses.
  • Password: Used for hash token generation with a random salt.
Request Signing:
  • Each request includes a random salt and a verification hash in the headers.
  • Parameters are sorted and concatenated to form the string to sign.
  • Signing uses HMAC-SHA256 with the secret key.
Response Verification:
  • Each response is verified using the salt and hash from the response headers.
  • Throws SecurityException if verification fails.
Usage Example: 
   GPayApiClient client = new GPayApiClient(apiKey, secretKey, password, baseUrl);
   Balance balance = client.getWalletBalance("en");
Endpoints:
  • getWalletBalance - Retrieve wallet balance
  • createPaymentRequest - Create a payment request
  • checkPaymentStatus - Check payment status
  • sendMoney - Send money to another wallet
  • getStatement - Get day statement
  • checkWallet - Check wallet existence/details
  • getOutstandingTransactions - Get outstanding transactions

  • Constructor Details

    • GPayApiClient

      public GPayApiClient(String apiKey, String secretKey, String password, GPayApiClient.BaseUrl baseUrl, String language)
      Parameters:
      apiKey - The API key for authentication.
      secretKey - The secret key for signing requests.
      password - The password for hash token generation.
      baseUrl - The base URL enum value (BaseUrl.STAGING or BaseUrl.PRODUCTION).
      language - The language for the response (default: 'en').

    • GPayApiClient

      public GPayApiClient(String apiKey, String secretKey, String password, GPayApiClient.BaseUrl baseUrl)
      Constructor with default language 'en'.
      Parameters:
      apiKey - The API key for authentication.
      secretKey - The secret key for signing requests.
      password - The password for hash token generation.
      baseUrl - The base URL enum value (BaseUrl.STAGING or BaseUrl.PRODUCTION).

  • Method Details

    • getWalletBalance

      public Balance getWalletBalance() throws Exception
      Retrieves the current wallet balance.
      Returns:
      Balance object containing the current available balance and response timestamp.
      Throws:
      Exception - if the request fails or response verification fails.

    • createPaymentRequest

      public PaymentRequest createPaymentRequest(BigDecimal amount, String referenceNo, String description) throws Exception
      Creates a payment request for a specified amount.
      Parameters:
      amount - The amount to request (as string, decimal value).
      referenceNo - Optional reference number (alphanumeric, spaces, underscores).
      description - Optional description (max 255 chars, restricted special chars).
      Returns:
      PaymentRequest object with details of the created payment request.
      Throws:
      Exception - if the request fails or response verification fails.

    • checkPaymentStatus

      public PaymentStatus checkPaymentStatus(String requestId) throws Exception
      Checks the status of a payment request by its request ID.
      Parameters:
      requestId - The payment request ID (UUID).
      Returns:
      PaymentStatus object with the status of the payment request.
      Throws:
      Exception - if the request fails or response verification fails.

    • sendMoney

      public SendMoneyResult sendMoney(BigDecimal amount, String walletGatewayId, String referenceNo, String description) throws Exception
      Sends money to another wallet.
      Parameters:
      amount - The amount to send (as string, decimal value).
      walletGatewayId - The recipient's wallet gateway ID (UUID).
      referenceNo - Optional reference number.
      description - Optional description.
      Returns:
      SendMoneyResult object with details of the transaction.
      Throws:
      Exception - if the request fails or response verification fails.

    • getStatement

      public Statement getStatement(String date) throws Exception
      Retrieves the wallet's transaction statement for a specific day.
      Parameters:
      date - The date in YYYY-MM-DD format.
      Returns:
      Statement object containing the day's transactions and balances.
      Throws:
      Exception - if the request fails or response verification fails.

    • checkWallet

      public WalletCheck checkWallet(String walletGatewayId) throws Exception
      Checks if a wallet exists and retrieves its details.
      Parameters:
      walletGatewayId - The wallet gateway ID to check (UUID).
      Returns:
      WalletCheck object with wallet details.
      Throws:
      Exception - if the request fails or response verification fails.

    • getOutstandingTransactions

      public OutstandingTransactions getOutstandingTransactions() throws Exception
      Retrieves a list of outstanding transactions.
      Returns:
      OutstandingTransactions object containing outstanding credits, debits, and transactions.
      Throws:
      Exception - if the request fails or response verification fails.