Package com.akraml.satim.request

Class PaymentRequestBuilder

java.lang.Object
com.akraml.satim.request.PaymentRequestBuilder
public class PaymentRequestBuilder extends Object
Builder for payment registration requests.

Provides a fluent API for configuring payment parameters, mirroring the PHP library's chained method pattern.

Example usage: 


 api.registerPayment()
     .amount(100000)                              // 1000 DZD in centimes
     .returnUrl("https://example.com/success")
     .failUrl("https://example.com/fail")
     .description("Product purchase")
     .language(Language.FRENCH)
     .timeout(600)
     .execute();

Required parameters:

See Also:

  • Constructor Details

    • PaymentRequestBuilder

      public PaymentRequestBuilder(@NotNull @NotNull SatimAPI api)
      Creates a new PaymentRequestBuilder.
      Parameters:
      api - the SatimAPI instance to use for executing the request

  • Method Details

    • amount

      public PaymentRequestBuilder amount(long amount)
      Sets the payment amount in centimes.

      Example: For 1000.00 DZD, use amount(100000)

      Parameters:
      amount - the amount in the smallest currency unit (centimes)
      Returns:
      this builder for method chaining
      Throws:
      IllegalArgumentException - if amount is not positive

    • returnUrl

      public PaymentRequestBuilder returnUrl(@NotNull @NotNull String returnUrl)
      Sets the return URL for successful payments.

      The customer will be redirected to this URL after completing payment.

      Parameters:
      returnUrl - the success callback URL
      Returns:
      this builder for method chaining
      Throws:
      IllegalArgumentException - if returnUrl is null or empty

    • failUrl

      public PaymentRequestBuilder failUrl(@Nullable @Nullable String failUrl)
      Sets the fail URL for unsuccessful payments.

      If not set, returnUrl(String) will be used for failures.

      Parameters:
      failUrl - the failure callback URL
      Returns:
      this builder for method chaining

    • description

      public PaymentRequestBuilder description(@Nullable @Nullable String description)
      Sets a description for the payment.

      This may be displayed to the customer on the payment page.

      Parameters:
      description - the payment description
      Returns:
      this builder for method chaining

    • orderNumber

      public PaymentRequestBuilder orderNumber(long orderNumber)
      Sets a custom order number.

      If not set, a random 10-digit number will be generated.

      Parameters:
      orderNumber - the custom order number (should be unique)
      Returns:
      this builder for method chaining

    • language

      public PaymentRequestBuilder language(@NotNull @NotNull Language language)
      Sets the language for the payment page.
      Parameters:
      language - the language enum value
      Returns:
      this builder for method chaining

    • language

      public PaymentRequestBuilder language(@NotNull @NotNull String languageCode)
      Sets the language for the payment page using a string code.
      Parameters:
      languageCode - the language code ("FR", "AR", or "EN")
      Returns:
      this builder for method chaining

    • timeout

      public PaymentRequestBuilder timeout(int seconds)
      Sets the payment session timeout in seconds.

      Default is 600 seconds (10 minutes).

      Parameters:
      seconds - the timeout in seconds
      Returns:
      this builder for method chaining
      Throws:
      IllegalArgumentException - if timeout is not positive

    • currency

      public PaymentRequestBuilder currency(@NotNull @NotNull String currency)
      Sets the currency code.

      Default is "012" (DZD - Algerian Dinar).

      Parameters:
      currency - the ISO 4217 numeric currency code
      Returns:
      this builder for method chaining

    • userDefinedField

      public PaymentRequestBuilder userDefinedField(@NotNull @NotNull String key, @NotNull @NotNull String value)
      Adds a single user-defined field.

      These fields can store custom metadata with the payment.

      Parameters:
      key - the field name
      value - the field value
      Returns:
      this builder for method chaining

    • userDefinedFields

      public PaymentRequestBuilder userDefinedFields(@NotNull @NotNull com.google.gson.JsonObject fields)
      Adds multiple user-defined fields.
      Parameters:
      fields - a JsonObject containing field key-value pairs
      Returns:
      this builder for method chaining

    • execute

      @NotNull public @NotNull CompletableFuture<PaymentReply> execute()
      Validates and executes the payment registration request.
      Returns:
      a CompletableFuture containing the PaymentReply
      Throws:
      IllegalStateException - if required parameters are missing

    • register

      @NotNull public @NotNull CompletableFuture<PaymentReply> register()
      Alias for execute() to match PHP library naming.
      Returns:
      a CompletableFuture containing the PaymentReply