Package com.akraml.satim

Class SatimAPI

java.lang.Object
com.akraml.satim.SatimAPI
public class SatimAPI extends Object
Main entry point for interacting with the SATIM Payment API.

This class provides methods for:

  • Registering new payment orders
  • Confirming payment status
  • Checking order status
  • Processing refunds
  • Reversing payments

Example usage:


 SatimHttpClient client = new ApacheHttpClient(
     "username", "password", "terminalId"
 );

 SatimAPI api = new SatimAPI(client);

 // Register a payment
 api.registerPayment()
     .amount(100000)
     .returnUrl("https://example.com/callback")
     .execute()
     .thenAccept(reply -> {
         System.out.println("Payment URL: " + reply.getPaymentUrl());
     });
See Also:

  • Constructor Details

    • SatimAPI

      public SatimAPI(@NotNull @NotNull SatimHttpClient httpClient)
      Creates a new SatimAPI instance.
      Parameters:
      httpClient - a SatimHttpClient that implements the HTTP behavior for communicating with the API

  • Method Details

    • getHttpClient

      @NotNull public @NotNull SatimHttpClient getHttpClient()
      Retrieves the current instance of HTTP client that's used by this API instance.
      Returns:
      the HTTP client

    • registerPayment

      @NotNull public @NotNull PaymentRequestBuilder registerPayment()
      Creates a new payment request builder.

      Use the builder to configure the payment parameters before executing.

      Example:

      
 api.registerPayment()
     .amount(100000)
     .returnUrl("https://example.com/success")
     .failUrl("https://example.com/fail")
     .description("Product purchase")
     .execute();
      Returns:
      a new PaymentRequestBuilder instance

    • executeRegisterPayment

      @NotNull public @NotNull CompletableFuture<PaymentReply> executeRegisterPayment(@NotNull @NotNull com.google.gson.JsonObject params)
      Executes a payment registration request.

      This method is called internally by PaymentRequestBuilder.execute().

      Parameters:
      params - the request parameters built by PaymentRequestBuilder
      Returns:
      a CompletableFuture containing the PaymentReply

    • confirmPayment

      @NotNull public @NotNull CompletableFuture<OrderConfirmationReply> confirmPayment(@NotNull @NotNull String orderId)
      Confirms a payment order.

      This should be called when the customer returns from the payment page to verify and complete the transaction.

      Example:

      
 api.confirmPayment(orderId)
     .thenAccept(reply -> {
         if (reply.isSuccessful()) {
             System.out.println("Payment confirmed: " + reply.getApprovalCode());
         } else {
             System.out.println("Payment failed: " + reply.getErrorMessage());
         }
     });
      Parameters:
      orderId - the order ID returned from payment registration
      Returns:
      a CompletableFuture containing the OrderConfirmationReply

    • confirm

      @NotNull public @NotNull CompletableFuture<OrderConfirmationReply> confirm(@NotNull @NotNull String orderId)
      Alias for confirmPayment(String) to match PHP library naming.
      Parameters:
      orderId - the order ID
      Returns:
      a CompletableFuture containing the OrderConfirmationReply

    • getPaymentStatus

      @NotNull public @NotNull CompletableFuture<OrderStatusReply> getPaymentStatus(@NotNull @NotNull String orderId)
      Gets the current status of a payment order.

      Example:

      
 api.getPaymentStatus(orderId)
     .thenAccept(reply -> {
         System.out.println("Status: " + reply.getOrderStatus());
         if (reply.isDeposited()) {
             System.out.println("Payment completed!");
         }
     });
      Parameters:
      orderId - the order ID returned from payment registration
      Returns:
      a CompletableFuture containing the OrderStatusReply

    • status

      @NotNull public @NotNull CompletableFuture<OrderStatusReply> status(@NotNull @NotNull String orderId)
      Alias for getPaymentStatus(String) to match PHP library naming.
      Parameters:
      orderId - the order ID
      Returns:
      a CompletableFuture containing the OrderStatusReply

    • refundPayment

      @NotNull public @NotNull CompletableFuture<RefundReply> refundPayment(@NotNull @NotNull String orderId)
      Requests a full refund for a completed payment.

      Example:

      
 api.refundPayment(orderId)
     .thenAccept(reply -> {
         if (reply.isSuccessful()) {
             System.out.println("Refund processed successfully");
         }
     });
      Parameters:
      orderId - the order ID of the payment to refund
      Returns:
      a CompletableFuture containing the RefundReply

    • refundPayment

      @NotNull public @NotNull CompletableFuture<RefundReply> refundPayment(@NotNull @NotNull String orderId, long amount)
      Requests a partial or full refund for a completed payment.

      Example:

      
 // Refund 500 DZD (50000 centimes)
 api.refundPayment(orderId, 50000)
     .thenAccept(reply -> {
         if (reply.isSuccessful()) {
             System.out.println("Partial refund processed");
         }
     });
      Parameters:
      orderId - the order ID of the payment to refund
      amount - the amount to refund in centimes (0 for full refund)
      Returns:
      a CompletableFuture containing the RefundReply

    • refund

      @NotNull public @NotNull CompletableFuture<RefundReply> refund(@NotNull @NotNull String orderId)
      Alias for refundPayment(String) to match PHP library naming.
      Parameters:
      orderId - the order ID
      Returns:
      a CompletableFuture containing the RefundReply

    • reversePayment

      @NotNull public @NotNull CompletableFuture<RefundReply> reversePayment(@NotNull @NotNull String orderId)
      Reverses (cancels) a payment that hasn't been deposited yet.

      Use this for payments that are still in APPROVED status. For deposited payments, use refundPayment(String) instead.

      Example:

      
 api.reversePayment(orderId)
     .thenAccept(reply -> {
         if (reply.isSuccessful()) {
             System.out.println("Payment reversed");
         }
     });
      Parameters:
      orderId - the order ID of the payment to reverse
      Returns:
      a CompletableFuture containing the RefundReply

    • reverse

      @NotNull public @NotNull CompletableFuture<RefundReply> reverse(@NotNull @NotNull String orderId)
      Alias for reversePayment(String).
      Parameters:
      orderId - the order ID
      Returns:
      a CompletableFuture containing the RefundReply

    • close

      public void close() throws Exception
      Closes the HTTP client and releases resources.

      Call this when you're done using the API.

      Throws:
      Exception