Basic Integration

The SDK currently provides two types of payment

We can use Any of them by first preparing Moyasar's PaymentRequest object as follows:

val paymentRequest = PaymentRequest(
       givenID = UUID.randomUUID().toString(), // Optional. The payment ID to be created from your side to apply Idempotency (UUID -- v4 is recommended).
        apiKey = "pk_test_vcFUHJDBwiyRu4Bd3hFuPpTnRPY4gp2ssYdNJMY3",
        amount = 1000, // Amount in the smallest currency unit For example: 10 SAR = 10 * 100 Halalas
        currency = "SAR",
        description = "Sample Android SDK Payment",
        manual = false,
        metadata = mapOf(
            "order_id" to "order_123"
        ),
        saveCard = false,
        buttonType = MoyasarButtonType.PAY, // [determine button title: optional]; by default, it's set to `MoyasarButtonType.PAY`.
        allowedNetworks = listOf(
        CreditCardNetwork.Visa,
        CreditCardNetwork.Mastercard,
        CreditCardNetwork.Mada
    ) // Optional set your supported networks
)

info

Use the optional parameter givenID when you need to apply Idempotency Retry Payment Creation if you encounter any of the following:

• A 5xx server error response.
• A network error.
• A timeout error (open, read, or write).

---

• ⚠️ Note: If you ever send the same givenID value for different payments, you will receive a 400 response with the error message Payment is already created.
• Read more about Idempotency to understand the givenID parameter and avoid duplicate payments.

1 - Credit Card Payments integration

Then, we initialize and display Moyasar's PaymentFragment:

class MainActivity : AppCompatActivity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        // Other setup code

        val paymentFragment = PaymentFragment.newInstance(this.application, paymentRequest) { this.handlePaymentResult(it) }

        this.supportFragmentManager.beginTransaction().apply {
            // Id for the payment container view
            replace(R.id.paymentSheetFragment, paymentFragment)
            commit()
        }
    }

    fun handlePaymentResult(result: PaymentResult) {
        // ...
    }

    fun handleCompletedPayment(payment: Payment) {
        // ..
    }
}

info

An error will be thrown if the API key format is incorrect.

The payment fragment appears as follows:

Android SDK Dark Arabic	Android SDK Light English

2 - STC Pay Payments integration

Then, we initialize and display Moyasar's EnterMobileNumberFragment:

class MainActivity : AppCompatActivity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        // Other setup code

        val enterMobileNumberFragment = EnterMobileNumberFragment.newInstance(this.application, paymentRequest) { this.handlePaymentResult(it) }

        this.supportFragmentManager.beginTransaction().apply {
            // Id for the payment container view
            replace(R.id.paymentSheetFragment, enterMobileNumberFragment)
            commit()
        }
    }

    fun handlePaymentResult(result: PaymentResult) {
        // ...
    }

    fun handleCompletedPayment(payment: Payment) {
        // ..
    }
}

info

An error will be thrown if the API key format is incorrect.

The payment fragments appear as follows:

Enter Phone Dark English	Enter OTP Dark English

Handling Payment Result for (Credit Card or STC Pay)

Now, we can handle the Credit Card payment result or STC Pay payment result as follows:

 fun handlePaymentResult(result: PaymentResult) {
    when (result) {
        is PaymentResult.Completed -> {
            handleCompletedPayment(result.payment);
        }
        is PaymentResult.Failed -> {
            // Handle error
            val error = result.error;
        }
        PaymentResult.Canceled -> {
            // User has canceled the payment
        }

        else -> { /* Handle other statuses */ }
    }
}

fun handleCompletedPayment(payment: Payment) {
     when (payment.status) {
        "paid" -> { /* Handle successful payment */ }
        "failed" -> {
            val errorMessage = payment.source["message"]
            /* Handle failed payment */
        }
        else -> { /* Handle other statuses */ }
    }
}

warning

• A Completed payment does not guarantee success; it indicates that the payment process has been finalized successfully.
• You need to check the payment status to ensure that the payment is successful.

info

Payment Status Reference

warning

Ensure that the payment view is removed after obtaining the result.

Java interoperability

The SDK is developed in Kotlin and supports interoperability with Java.

Demo Example

You can explore the SDK driver demo provided in the moyasar-android-sdk repository.